# frigomia/trade-agent architecture

> Architecture diagram of the GitHub repository frigomia/trade-agent, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/frigomia/trade-agent
- Repository: https://github.com/frigomia/trade-agent

## Overview

Trade Agent is an advisory-only trading assistant: users review portfolio and watchlist analysis, then approve or dismiss recommendations; any resulting trade is placed manually outside the system. The graph follows the dashboard-to-API path and shows analysis, discovery, portfolio planning, and supporting account/data services. The README documents several capabilities whose implementation was not sampled; those appear as subsystem nodes, with only documented or indexed relationships connected. Some backend routes and domain stages are unsampled, so their internal call paths are intentionally not inferred.

Main entry points: [`backend/app/agents`](https://github.com/frigomia/trade-agent/tree/master/backend/app/agents) (Analysis agents), [`frontend/lib/api/client.ts`](https://github.com/frigomia/trade-agent/blob/master/frontend/lib/api/client.ts) (API client), [`backend/app/main.py`](https://github.com/frigomia/trade-agent/blob/master/backend/app/main.py) (FastAPI app), [`backend/app/routers/discover.py`](https://github.com/frigomia/trade-agent/blob/master/backend/app/routers/discover.py) (Watchlist research)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["User dashboard"]
  node_dashboard["Dashboard<br/>[page.tsx]"]
  node_discover_ui["Discover UI<br/>[page.tsx]"]
  node_portfolio_ui["Portfolio UI<br/>[page.tsx]"]
  node_chat_ui["Portfolio chat<br/>[page.tsx]"]
  node_api_client["API client<br/>[client.ts]"]
end

subgraph group_api["API and identity"]
  node_api_app["FastAPI app<br/>[main.py]"]
  node_auth["Authentication<br/>[deps.py]"]
  node_admin["User administration<br/>[service.py]"]
end

subgraph group_analysis["Research and decisions"]
  node_discover_api["Watchlist research<br/>[discover.py]"]
  node_discovery["Opportunity discovery"]
  node_agents["Analysis agents"]
  node_recommendations["Recommendations<br/>[recommend.py]"]
  node_memory["Research memory"]
  node_backtest["Signal backtests<br/>[engine.py]"]
end

subgraph group_portfolio["Portfolio workflows"]
  node_portfolio_api["Portfolio API<br/>[portfolio.py]"]
  node_planner["Contribution planner<br/>[plans.py]"]
  node_orders["Manual order tracking<br/>[trades.py]"]
  node_recurring["Recurring investments<br/>[recurring.py]"]
  node_notifications["Telegram notices<br/>[telegram.py]"]
end

subgraph group_state["Data and operations"]
  node_db_layer["Database access<br/>[db.py]"]
  node_models["Application records<br/>[models.py]"]
  node_postgres[("Postgres and pgvector")]
  node_redis[("Redis<br/>[redis_client.py]")]
  node_supabase["Supabase Auth"]
end

node_user(("Investor"))
node_claude["Anthropic Claude"]
node_telegram_service["Telegram service"]

node_user -->|"reviews"| node_dashboard
node_user -->|"browses"| node_discover_ui
node_user -->|"manages"| node_portfolio_ui
node_user -->|"asks"| node_chat_ui
node_dashboard -.->|"requests data"| node_api_client
node_discover_ui -.->|"requests data"| node_api_client
node_portfolio_ui -.->|"requests data"| node_api_client
node_chat_ui -.->|"requests chat"| node_api_client
node_api_client -->|"calls API"| node_api_app
node_api_app -->|"authenticates requests"| node_auth
node_api_app -->|"registers routes"| node_discover_api
node_api_app -->|"registers routes"| node_portfolio_api
node_admin -->|"manages accounts"| node_supabase
node_discover_api -->|"starts research"| node_agents
node_discover_api -->|"uses company jobs"| node_discovery
node_discovery -->|"uses market data"| node_agents
node_agents -.->|"requests analysis"| node_claude
node_agents -->|"claims search budget"| node_redis
node_backtest -->|"simulates signals"| node_recommendations
node_portfolio_api -.->|"reads and writes"| node_db_layer
node_planner -->|"creates trackable orders"| node_orders
node_recurring -->|"logs placed buys"| node_orders
node_notifications -->|"sends notices"| node_telegram_service
node_db_layer -->|"opens sessions"| node_postgres
node_db_layer -->|"uses records"| node_models
node_models -->|"maps data"| node_postgres
node_agents -.->|"uses long-term memory"| node_memory

click node_dashboard "https://github.com/frigomia/trade-agent/blob/master/frontend/app/(shell)/today/page.tsx"
click node_discover_ui "https://github.com/frigomia/trade-agent/blob/master/frontend/app/(shell)/discover/page.tsx"
click node_portfolio_ui "https://github.com/frigomia/trade-agent/blob/master/frontend/app/(shell)/portfolio/page.tsx"
click node_chat_ui "https://github.com/frigomia/trade-agent/blob/master/frontend/app/(shell)/chat/page.tsx"
click node_api_client "https://github.com/frigomia/trade-agent/blob/master/frontend/lib/api/client.ts"
click node_api_app "https://github.com/frigomia/trade-agent/blob/master/backend/app/main.py"
click node_auth "https://github.com/frigomia/trade-agent/blob/master/backend/app/auth/deps.py"
click node_admin "https://github.com/frigomia/trade-agent/blob/master/backend/app/admin/service.py"
click node_discover_api "https://github.com/frigomia/trade-agent/blob/master/backend/app/routers/discover.py"
click node_discovery "https://github.com/frigomia/trade-agent/tree/master/backend/app/discovery"
click node_agents "https://github.com/frigomia/trade-agent/tree/master/backend/app/agents"
click node_recommendations "https://github.com/frigomia/trade-agent/blob/master/backend/app/analysis/recommend.py"
click node_memory "https://github.com/frigomia/trade-agent/tree/master/backend/app/memory"
click node_backtest "https://github.com/frigomia/trade-agent/blob/master/backend/app/backtest/engine.py"
click node_portfolio_api "https://github.com/frigomia/trade-agent/blob/master/backend/app/routers/portfolio.py"
click node_planner "https://github.com/frigomia/trade-agent/blob/master/backend/app/plans.py"
click node_orders "https://github.com/frigomia/trade-agent/blob/master/backend/app/trades.py"
click node_recurring "https://github.com/frigomia/trade-agent/blob/master/backend/app/recurring.py"
click node_notifications "https://github.com/frigomia/trade-agent/blob/master/backend/app/telegram.py"
click node_db_layer "https://github.com/frigomia/trade-agent/blob/master/backend/app/db.py"
click node_models "https://github.com/frigomia/trade-agent/blob/master/backend/app/models.py"
click node_redis "https://github.com/frigomia/trade-agent/blob/master/backend/app/redis_client.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_dashboard,node_discover_ui,node_portfolio_ui,node_chat_ui,node_api_client toneBlue
class node_api_app,node_auth,node_admin toneAmber
class node_discover_api,node_discovery,node_agents,node_recommendations,node_memory,node_backtest toneMint
class node_portfolio_api,node_planner,node_orders,node_recurring,node_notifications toneRose
class node_db_layer,node_models,node_postgres,node_redis,node_supabase,node_user,node_claude,node_telegram_service toneIndigo
```

## Components

### User dashboard

- [Dashboard](https://github.com/frigomia/trade-agent/blob/master/frontend/app/(shell)/today/page.tsx): `frontend/app/(shell)/today/page.tsx`
- [Discover UI](https://github.com/frigomia/trade-agent/blob/master/frontend/app/(shell)/discover/page.tsx): `frontend/app/(shell)/discover/page.tsx`
- [Portfolio UI](https://github.com/frigomia/trade-agent/blob/master/frontend/app/(shell)/portfolio/page.tsx): `frontend/app/(shell)/portfolio/page.tsx`
- [Portfolio chat](https://github.com/frigomia/trade-agent/blob/master/frontend/app/(shell)/chat/page.tsx): `frontend/app/(shell)/chat/page.tsx`
- [API client](https://github.com/frigomia/trade-agent/blob/master/frontend/lib/api/client.ts): `frontend/lib/api/client.ts`

### API and identity

- [FastAPI app](https://github.com/frigomia/trade-agent/blob/master/backend/app/main.py): `backend/app/main.py`
- [Authentication](https://github.com/frigomia/trade-agent/blob/master/backend/app/auth/deps.py): `backend/app/auth/deps.py`
- [User administration](https://github.com/frigomia/trade-agent/blob/master/backend/app/admin/service.py): `backend/app/admin/service.py`

### Research and decisions

- [Watchlist research](https://github.com/frigomia/trade-agent/blob/master/backend/app/routers/discover.py): `backend/app/routers/discover.py`
- [Opportunity discovery](https://github.com/frigomia/trade-agent/tree/master/backend/app/discovery): `backend/app/discovery`
- [Analysis agents](https://github.com/frigomia/trade-agent/tree/master/backend/app/agents): `backend/app/agents`
- [Recommendations](https://github.com/frigomia/trade-agent/blob/master/backend/app/analysis/recommend.py): `backend/app/analysis/recommend.py`
- [Research memory](https://github.com/frigomia/trade-agent/tree/master/backend/app/memory): `backend/app/memory`
- [Signal backtests](https://github.com/frigomia/trade-agent/blob/master/backend/app/backtest/engine.py): `backend/app/backtest/engine.py`

### Portfolio workflows

- [Portfolio API](https://github.com/frigomia/trade-agent/blob/master/backend/app/routers/portfolio.py): `backend/app/routers/portfolio.py`
- [Contribution planner](https://github.com/frigomia/trade-agent/blob/master/backend/app/plans.py): `backend/app/plans.py`
- [Manual order tracking](https://github.com/frigomia/trade-agent/blob/master/backend/app/trades.py): `backend/app/trades.py`
- [Recurring investments](https://github.com/frigomia/trade-agent/blob/master/backend/app/recurring.py): `backend/app/recurring.py`
- [Telegram notices](https://github.com/frigomia/trade-agent/blob/master/backend/app/telegram.py): `backend/app/telegram.py`

### Data and operations

- [Database access](https://github.com/frigomia/trade-agent/blob/master/backend/app/db.py): `backend/app/db.py`
- [Application records](https://github.com/frigomia/trade-agent/blob/master/backend/app/models.py): `backend/app/models.py`
- **Postgres and pgvector**
- [Redis](https://github.com/frigomia/trade-agent/blob/master/backend/app/redis_client.py): `backend/app/redis_client.py`
- **Supabase Auth**

### Other components

- **Investor**
- **Anthropic Claude**
- **Telegram service**

## Connections

- Investor → Dashboard: reviews (evidence: `README.md`)
- Investor → Discover UI: browses (evidence: `README.md`)
- Investor → Portfolio UI: manages (evidence: `README.md`)
- Investor → Portfolio chat: asks (evidence: `README.md`)
- Dashboard → API client: requests data
- Discover UI → API client: requests data
- Portfolio UI → API client: requests data
- Portfolio chat → API client: requests chat
- API client → FastAPI app: calls API (evidence: `README.md`)
- FastAPI app → Authentication: authenticates requests (evidence: `backend/app/main.py`)
- FastAPI app → Watchlist research: registers routes (evidence: `backend/app/main.py`)
- FastAPI app → Portfolio API: registers routes (evidence: `backend/app/main.py`)
- User administration → Supabase Auth: manages accounts (evidence: `backend/app/admin/service.py`)
- Watchlist research → Analysis agents: starts research (evidence: `backend/app/routers/discover.py`)
- Watchlist research → Opportunity discovery: uses company jobs (evidence: `backend/app/routers/discover.py`)
- Opportunity discovery → Analysis agents: uses market data (evidence: `backend/app/discovery/admit.py`)
- Analysis agents → Anthropic Claude: requests analysis
- Analysis agents → Redis: claims search budget (evidence: `backend/app/agents/research.py`)
- Signal backtests → Recommendations: simulates signals (evidence: `backend/app/backtest/engine.py`)
- Portfolio API → Database access: reads and writes
- Contribution planner → Manual order tracking: creates trackable orders (evidence: `README.md`)
- Recurring investments → Manual order tracking: logs placed buys (evidence: `backend/app/recurring.py`)
- Telegram notices → Telegram service: sends notices (evidence: `README.md`)
- Database access → Postgres and pgvector: opens sessions (evidence: `backend/app/db.py`)
- Database access → Application records: uses records (evidence: `backend/app/db.py`)
- Application records → Postgres and pgvector: maps data (evidence: `backend/app/models.py`)
- Analysis agents → Research memory: uses long-term memory
