mirror of https://github.com/ghostfolio/ghostfolio
Browse Source
Comprehensive project guide covering codebase structure, key services, commands, database models, API routes, coding conventions, and the AgentForge AI agent integration plan. https://claude.ai/code/session_01Uf16jhwBHEixYxMLk2BgWGpull/6390/head
Claude
1 month ago
1 changed files with 300 additions and 0 deletions
@ -0,0 +1,300 @@ |
|||
# CLAUDE.md — AgentForge x Ghostfolio |
|||
|
|||
## Project Overview |
|||
|
|||
This is **AgentForge x Ghostfolio** — an AI-powered financial agent layer being built on top of [Ghostfolio](https://github.com/ghostfolio/ghostfolio), an open-source wealth management application. The goal is to add a conversational AI assistant that can analyze portfolios, provide market insights, execute trades, assess risk, and help users manage their finances through natural language. |
|||
|
|||
### What Ghostfolio Is (The Foundation) |
|||
|
|||
Ghostfolio is a privacy-first, open-source personal finance dashboard for tracking stocks, ETFs, funds, and cryptocurrencies across multiple accounts and platforms. It provides: |
|||
|
|||
- Multi-account portfolio tracking with performance analytics (ROAI, ROI, TWR, MWR) |
|||
- Risk analysis via portfolio rules (cluster risk, currency risk, fee ratios, etc.) |
|||
- Multi-currency support with automatic exchange rate conversion |
|||
- Multiple data providers (Yahoo Finance, CoinGecko, Alpha Vantage, EOD Historical Data, etc.) |
|||
- Import/export of transactions, public portfolio sharing, and an admin panel |
|||
|
|||
### What AgentForge Adds (The AI Layer) |
|||
|
|||
AgentForge introduces an AI agent module that integrates with Ghostfolio's existing services: |
|||
|
|||
- **Conversational AI assistant** — natural language interface for portfolio queries and actions |
|||
- **Multi-agent orchestration** — Coordinator, Analyst, Executor, and Risk Manager agents |
|||
- **Tool registry** — AI-callable tools wrapping Ghostfolio services (portfolio analysis, market data, trade execution, risk assessment, goal tracking) |
|||
- **Real-time streaming** — Server-Sent Events (SSE) for streaming AI responses |
|||
- **Conversation memory** — persistent chat history stored in PostgreSQL via Prisma |
|||
- **Permission-based tool access** — tools gated by user roles and subscription tier |
|||
|
|||
--- |
|||
|
|||
## Tech Stack |
|||
|
|||
| Layer | Technology | |
|||
|-------|-----------| |
|||
| **Monorepo** | Nx 21.x | |
|||
| **Backend** | NestJS 11.x (TypeScript 5.9) | |
|||
| **Frontend** | Angular 21.x with Angular Material | |
|||
| **Database** | PostgreSQL 15 via Prisma 6.x ORM | |
|||
| **Cache** | Redis (Bull queues for background jobs) | |
|||
| **AI/LLM** | LangChain / LangGraph (planned) | |
|||
| **Auth** | JWT, Google OAuth, OIDC, WebAuthn (Passport strategies) | |
|||
| **Containerization** | Docker / Docker Compose | |
|||
| **i18n** | Angular i18n (12 languages) | |
|||
|
|||
--- |
|||
|
|||
## Repository Structure |
|||
|
|||
``` |
|||
ghostfolio/ |
|||
├── apps/ |
|||
│ ├── api/ # NestJS backend (REST API) |
|||
│ │ └── src/ |
|||
│ │ ├── app/ # Feature modules (controllers + services) |
|||
│ │ │ ├── portfolio/ # Portfolio controller & service |
|||
│ │ │ ├── order/ # Order/activity controller & service |
|||
│ │ │ ├── account/ # Account controller & service |
|||
│ │ │ ├── admin/ # Admin controller |
|||
│ │ │ ├── auth/ # Auth controller + strategies |
|||
│ │ │ ├── user/ # User controller & service |
|||
│ │ │ ├── import/ # CSV/JSON import |
|||
│ │ │ ├── export/ # Portfolio export |
|||
│ │ │ └── ... # Additional feature modules |
|||
│ │ ├── services/ # Shared backend services |
|||
│ │ │ ├── data-provider/ # Multi-provider data aggregation |
|||
│ │ │ ├── exchange-rate-data/ # Currency exchange rates |
|||
│ │ │ ├── portfolio-snapshot/ # Portfolio snapshot queue |
|||
│ │ │ ├── data-gathering/ # Background data jobs |
|||
│ │ │ └── ... |
|||
│ │ ├── interceptors/ # Request/response interceptors |
|||
│ │ ├── guards/ # Auth & permission guards |
|||
│ │ └── models/rules/ # Portfolio analysis rules |
|||
│ └── client/ # Angular frontend (PWA) |
|||
│ └── src/ |
|||
│ ├── app/ |
|||
│ │ ├── pages/ # Route-level page components |
|||
│ │ ├── components/ # Shared page-level components |
|||
│ │ └── services/ # HTTP client services |
|||
│ ├── locales/ # i18n translation files |
|||
│ └── styles/ # Global SCSS styles |
|||
├── libs/ |
|||
│ ├── common/ # Shared TypeScript types, interfaces, helpers |
|||
│ │ └── src/lib/ |
|||
│ │ ├── interfaces/ # 100+ shared interface definitions |
|||
│ │ ├── types/ # Shared type aliases |
|||
│ │ └── helper/ # Utility functions |
|||
│ └── ui/ # Angular component library + Storybook |
|||
│ └── src/lib/ # Reusable UI components (tables, charts, forms) |
|||
├── prisma/ |
|||
│ ├── schema.prisma # Database schema (all models defined here) |
|||
│ ├── migrations/ # Prisma migration history |
|||
│ └── seed.ts # Database seeding script |
|||
├── docker/ # Docker Compose configs (dev, build, prod) |
|||
├── .github/workflows/ # CI/CD (lint, test, build, Docker publish) |
|||
└── CLAUDE.md # This file |
|||
``` |
|||
|
|||
### TypeScript Path Aliases |
|||
|
|||
``` |
|||
@ghostfolio/api/* → apps/api/src/* |
|||
@ghostfolio/client/* → apps/client/src/app/* |
|||
@ghostfolio/common/* → libs/common/src/lib/* |
|||
@ghostfolio/ui/* → libs/ui/src/lib/* |
|||
``` |
|||
|
|||
--- |
|||
|
|||
## Key Commands |
|||
|
|||
### Development |
|||
|
|||
```bash |
|||
npm run start:server # Start NestJS API with file watching |
|||
npm run start:client # Start Angular dev server (localhost:4200/en) |
|||
npm run start:storybook # Start Storybook UI component browser |
|||
``` |
|||
|
|||
### Build |
|||
|
|||
```bash |
|||
npm run build:production # Full production build (API + Client + Storybook) |
|||
npm run watch:server # Watch mode API build |
|||
``` |
|||
|
|||
### Test |
|||
|
|||
```bash |
|||
npm test # Run ALL tests (uses .env.example, 4 parallel workers) |
|||
npm run test:api # Run API tests only |
|||
npm run test:common # Run common lib tests only |
|||
npm run test:ui # Run UI lib tests only |
|||
``` |
|||
|
|||
Tests use Jest and require environment variables from `.env.example` (loaded via `dotenv-cli`). |
|||
|
|||
### Lint & Format |
|||
|
|||
```bash |
|||
npm run lint # Lint entire codebase (ESLint) |
|||
npm run format:check # Check Prettier formatting |
|||
npm run format:write # Auto-fix formatting |
|||
``` |
|||
|
|||
### Database |
|||
|
|||
```bash |
|||
npm run database:setup # Push schema + seed (for initial setup) |
|||
npm run database:push # Sync Prisma schema to DB (no migration) |
|||
npm run database:migrate # Run Prisma migrations |
|||
npm run database:seed # Seed database with initial data |
|||
npm run database:gui # Open Prisma Studio (DB browser) |
|||
npm run database:generate-typings # Regenerate Prisma client types |
|||
npm run database:format-schema # Format schema.prisma |
|||
``` |
|||
|
|||
### Docker (local development infrastructure) |
|||
|
|||
```bash |
|||
docker-compose -f docker/docker-compose.dev.yml up # Start PostgreSQL + Redis |
|||
docker-compose -f docker/docker-compose.build.yml up # Build & run full app locally |
|||
``` |
|||
|
|||
--- |
|||
|
|||
## Key Backend Services |
|||
|
|||
### PortfolioService (`apps/api/src/app/portfolio/portfolio.service.ts`) |
|||
The core service. Calculates portfolio performance (ROAI, ROI, TWR, MWR), aggregates holdings across accounts, generates risk analysis reports, handles time-range filtering (1d, WTD, MTD, YTD, 1Y, 5Y, Max), and manages portfolio snapshots. |
|||
|
|||
### OrderService (`apps/api/src/app/order/order.service.ts`) |
|||
CRUD for activities/transactions. Handles BUY, SELL, DIVIDEND, FEE, INTEREST, and LIABILITY activity types. Triggers data gathering for new assets and emits portfolio change events for cache invalidation. |
|||
|
|||
### AccountService (`apps/api/src/app/account/account.service.ts`) |
|||
Manages trading accounts and platforms. Calculates account balances, retrieves account history, and handles account-level exclusions from portfolio calculations. |
|||
|
|||
### DataProviderService (`apps/api/src/services/data-provider/data-provider.service.ts`) |
|||
Orchestrates multiple market data providers (Yahoo Finance, CoinGecko, Alpha Vantage, etc.). Fetches quotes, historical data, asset profiles, and dividends. Handles provider-specific API keys and rate limiting. |
|||
|
|||
### ExchangeRateDataService (`apps/api/src/services/exchange-rate-data/exchange-rate-data.service.ts`) |
|||
Manages currency exchange rates with caching. Initializes currency pairs on module load, fills historical gaps via forward-fill, and supports derived currencies. |
|||
|
|||
--- |
|||
|
|||
## Database Models (Prisma) |
|||
|
|||
Key models in `prisma/schema.prisma`: |
|||
|
|||
| Model | Purpose | |
|||
|-------|---------| |
|||
| `User` | User accounts with roles (ADMIN, USER) and auth provider | |
|||
| `Account` | Trading/brokerage accounts linked to platforms | |
|||
| `Order` | Transaction records (BUY, SELL, DIVIDEND, FEE, etc.) | |
|||
| `SymbolProfile` | Asset metadata (stocks, ETFs, crypto) with data source | |
|||
| `MarketData` | Historical price data with market state | |
|||
| `AccountBalance` | Historical account balance snapshots | |
|||
| `Tag` | Transaction/holding tags for filtering | |
|||
| `Access` | Portfolio sharing/access control tokens | |
|||
| `Subscription` | Premium subscription records | |
|||
| `Analytics` | User activity analytics | |
|||
| `ApiKey` | API key management | |
|||
| `AuthDevice` | WebAuthn device registration | |
|||
| `Platform` | Trading platform references | |
|||
| `Property` | Application-level key-value configuration | |
|||
| `Settings` | User settings (JSON) | |
|||
|
|||
--- |
|||
|
|||
## Key API Routes |
|||
|
|||
| Method | Route | Purpose | |
|||
|--------|-------|---------| |
|||
| `GET` | `/api/v1/portfolio/details` | Full portfolio details | |
|||
| `GET` | `/api/v1/portfolio/holdings` | Current holdings | |
|||
| `GET` | `/api/v1/portfolio/performance` | Performance metrics | |
|||
| `GET` | `/api/v1/portfolio/report` | Risk analysis report | |
|||
| `GET/POST/PUT/DELETE` | `/api/v1/order` | Activity CRUD | |
|||
| `GET/POST/PUT/DELETE` | `/api/v1/account` | Account CRUD | |
|||
| `POST` | `/api/v1/import` | Import transactions | |
|||
| `GET` | `/api/v1/export` | Export portfolio | |
|||
| `POST` | `/api/v1/auth/anonymous` | Token-based login | |
|||
| `GET` | `/api/v1/auth/google` | Google OAuth | |
|||
| `GET` | `/api/v1/health` | Health check | |
|||
| `GET` | `/api/v1/info` | System info | |
|||
| `GET` | `/api/v1/public/:accessId/portfolio` | Public portfolio | |
|||
|
|||
--- |
|||
|
|||
## AgentForge Integration Plan |
|||
|
|||
The AI agent layer will be implemented as a new NestJS module within the API app: |
|||
|
|||
### New Module: `apps/api/src/app/agent-forge/` |
|||
|
|||
``` |
|||
agent-forge/ |
|||
├── agent-forge.module.ts # NestJS module registration |
|||
├── agent-forge.controller.ts # REST + SSE endpoints |
|||
├── agent-forge.service.ts # Core orchestration service |
|||
├── tools/ # AI-callable tool definitions |
|||
│ ├── portfolio-analysis.tool.ts # Wraps PortfolioService |
|||
│ ├── market-data.tool.ts # Wraps DataProviderService |
|||
│ ├── trade-execution.tool.ts # Wraps OrderService |
|||
│ ├── risk-assessment.tool.ts # Wraps portfolio rules engine |
|||
│ └── goal-tracking.tool.ts # Financial goal management |
|||
├── agents/ # Multi-agent definitions |
|||
│ ├── coordinator.agent.ts # Routes queries to specialist agents |
|||
│ ├── analyst.agent.ts # Portfolio & market analysis |
|||
│ ├── executor.agent.ts # Trade execution with confirmation |
|||
│ └── risk-manager.agent.ts # Risk assessment & guardrails |
|||
├── memory/ # Conversation persistence |
|||
│ └── conversation.service.ts # Chat history via Prisma |
|||
└── streaming/ # Real-time response streaming |
|||
└── sse.service.ts # Server-Sent Events |
|||
``` |
|||
|
|||
### New Prisma Models (to be added) |
|||
|
|||
- `Conversation` — chat session metadata (userId, title, timestamps) |
|||
- `Message` — individual messages (role, content, toolCalls, tokens) |
|||
- `FinancialGoal` — user-defined financial goals with progress tracking |
|||
|
|||
### Key Design Principles |
|||
|
|||
1. **Wrap, don't replace** — AI tools call existing Ghostfolio services; no duplicate business logic |
|||
2. **Permission-gated tools** — tool access respects user roles and subscription tiers |
|||
3. **Human-in-the-loop** — trade execution requires explicit user confirmation |
|||
4. **Streaming-first** — all AI responses use SSE for real-time token delivery |
|||
5. **Auditable** — all tool invocations are logged for compliance and debugging |
|||
|
|||
--- |
|||
|
|||
## Coding Conventions |
|||
|
|||
- **Backend patterns**: NestJS modules with controller + service pairs, dependency injection throughout |
|||
- **Frontend patterns**: Angular standalone components, lazy-loaded routes, Angular Material UI |
|||
- **Naming**: PascalCase for classes/interfaces, camelCase for variables/functions, kebab-case for file names |
|||
- **Imports**: Use `@ghostfolio/` path aliases — never relative paths across app/lib boundaries |
|||
- **Testing**: Jest for all tests; test files co-located with source as `*.spec.ts` |
|||
- **Database changes**: Always update `prisma/schema.prisma`, then run `npm run database:push` or create a migration |
|||
- **Shared types**: Define interfaces in `libs/common/src/lib/interfaces/`, export via barrel files |
|||
- **UI components**: Reusable components go in `libs/ui/`, page-specific components stay in `apps/client/` |
|||
|
|||
--- |
|||
|
|||
## Environment Variables |
|||
|
|||
Required variables (see `.env.example`): |
|||
|
|||
``` |
|||
COMPOSE_PROJECT_NAME=ghostfolio |
|||
POSTGRES_DB=ghostfolio-db |
|||
POSTGRES_USER=user |
|||
POSTGRES_PASSWORD=<password> |
|||
DATABASE_URL=postgresql://user:password@localhost:5432/ghostfolio-db |
|||
REDIS_HOST=localhost |
|||
REDIS_PORT=6379 |
|||
REDIS_PASSWORD=<password> |
|||
ACCESS_TOKEN_SALT=<random-string> |
|||
JWT_SECRET_KEY=<random-string> |
|||
``` |
|||
Loading…
Reference in new issue