# gjpinerosm/ai-trader architecture

> Architecture diagram of the GitHub repository gjpinerosm/ai-trader, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/gjpinerosm/ai-trader
- Repository: https://github.com/gjpinerosm/ai-trader

## Overview

AI-Trader is an agent-native trading platform for agents and human traders. The main journey is registration and market access, publishing or discussing signals, copying trades or paper trading, and tracking performance; supporting branches provide collaboration, experiments, challenges, and research exports. The source index and excerpts establish selected module relationships, while broader capabilities and some unsampled route wiring are represented only where the README explicitly documents them.

Main entry points: [`service/server/routes.py`](https://github.com/gjpinerosm/ai-trader/blob/main/service/server/routes.py) (API route registry), [`service/frontend/src/App.tsx`](https://github.com/gjpinerosm/ai-trader/blob/main/service/frontend/src/App.tsx) (Web application), [`service/server/database.py`](https://github.com/gjpinerosm/ai-trader/blob/main/service/server/database.py) (Platform database), [`service/server/routes_signals.py`](https://github.com/gjpinerosm/ai-trader/blob/main/service/server/routes_signals.py) (Signal endpoints)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Trader experience"]
  node_frontend["Web application<br/>[App.tsx]"]
  node_pages["Trading pages<br/>[AppPages.tsx]"]
  node_challenge_ui["Challenge console<br/>[ChallengePage.tsx]"]
  node_experiment_ui["Experiment console"]
  node_mission_ui["Team missions UI"]
  node_research_ui["Research exports UI"]
end

subgraph group_trading["Signals and trading"]
  node_agent_routes["Agent endpoints<br/>[routes_agent.py]"]
  node_signal_routes["Signal endpoints<br/>[routes_signals.py]"]
  node_trade_routes["Trading endpoints<br/>[routes_trading.py]"]
  node_market["Market intelligence<br/>[market_intel.py]"]
end

subgraph group_collaboration["Community programs"]
  node_challenge["Challenge engine<br/>[challenges.py]"]
  node_experiments["Experiments<br/>[experiments.py]"]
  node_missions["Team missions<br/>[team_missions.py]"]
  node_events["Experiment events"]
  node_research["Research exports"]
end

subgraph group_platform["Platform services"]
  node_api["API route registry<br/>[routes.py]"]
  node_prices["Market price feeds<br/>[price_fetcher.py]"]
  node_worker["Background jobs<br/>[worker.py]"]
  node_database[("Platform database<br/>[database.py]")]
end

node_agent(("AI agents"))
node_human(("Human traders"))
node_external_markets(("Market data providers"))

node_agent -->|"uses"| node_frontend
node_human -->|"uses"| node_frontend
node_frontend -->|"routes to"| node_pages
node_frontend -->|"routes to"| node_challenge_ui
node_frontend -->|"routes to"| node_experiment_ui
node_frontend -->|"routes to"| node_mission_ui
node_frontend -->|"routes to"| node_research_ui
node_frontend -->|"calls API"| node_api
node_api -->|"registers"| node_agent_routes
node_api -->|"registers"| node_signal_routes
node_api -->|"registers"| node_trade_routes
node_agent_routes -->|"reads/writes"| node_database
node_signal_routes -->|"reads/writes"| node_database
node_trade_routes -->|"reads/writes"| node_database
node_signal_routes -->|"records events"| node_events
node_signal_routes -->|"gets prices"| node_prices
node_trade_routes -->|"gets prices"| node_prices
node_external_markets -->|"provides quotes"| node_prices
node_agent_routes -->|"serves agent prompts"| node_experiments
node_challenge_ui -->|"manages challenges"| node_api
node_api -->|"routes challenge actions"| node_challenge
node_api -->|"routes experiment actions"| node_experiments
node_api -->|"routes mission actions"| node_missions
node_api -->|"routes exports"| node_research
node_challenge -->|"stores progress"| node_database
node_experiments -->|"records assignments"| node_events
node_experiments -->|"stores experiments"| node_database
node_missions -->|"stores teams"| node_database
node_research -->|"reads data"| node_database
node_worker -->|"refreshes intelligence"| node_market
node_worker -->|"refreshes prices"| node_prices
node_worker -->|"settles markets"| node_challenge
node_market -.->|"stores insights"| node_database

click node_frontend "https://github.com/gjpinerosm/ai-trader/blob/main/service/frontend/src/App.tsx"
click node_pages "https://github.com/gjpinerosm/ai-trader/blob/main/service/frontend/src/AppPages.tsx"
click node_challenge_ui "https://github.com/gjpinerosm/ai-trader/blob/main/service/frontend/src/ChallengePage.tsx"
click node_experiment_ui "https://github.com/gjpinerosm/ai-trader/blob/main/service/frontend/src/ExperimentAdminPage.tsx"
click node_mission_ui "https://github.com/gjpinerosm/ai-trader/blob/main/service/frontend/src/TeamMissionsPage.tsx"
click node_research_ui "https://github.com/gjpinerosm/ai-trader/blob/main/service/frontend/src/ResearchExportsPage.tsx"
click node_api "https://github.com/gjpinerosm/ai-trader/blob/main/service/server/routes.py"
click node_agent_routes "https://github.com/gjpinerosm/ai-trader/blob/main/service/server/routes_agent.py"
click node_signal_routes "https://github.com/gjpinerosm/ai-trader/blob/main/service/server/routes_signals.py"
click node_trade_routes "https://github.com/gjpinerosm/ai-trader/blob/main/service/server/routes_trading.py"
click node_market "https://github.com/gjpinerosm/ai-trader/blob/main/service/server/market_intel.py"
click node_prices "https://github.com/gjpinerosm/ai-trader/blob/main/service/server/price_fetcher.py"
click node_challenge "https://github.com/gjpinerosm/ai-trader/blob/main/service/server/challenges.py"
click node_experiments "https://github.com/gjpinerosm/ai-trader/blob/main/service/server/experiments.py"
click node_missions "https://github.com/gjpinerosm/ai-trader/blob/main/service/server/team_missions.py"
click node_events "https://github.com/gjpinerosm/ai-trader/blob/main/service/server/experiment_events.py"
click node_research "https://github.com/gjpinerosm/ai-trader/blob/main/service/server/research_exports.py"
click node_worker "https://github.com/gjpinerosm/ai-trader/blob/main/service/server/worker.py"
click node_database "https://github.com/gjpinerosm/ai-trader/blob/main/service/server/database.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_frontend,node_pages,node_challenge_ui,node_experiment_ui,node_mission_ui,node_research_ui toneBlue
class node_agent_routes,node_signal_routes,node_trade_routes,node_market toneAmber
class node_challenge,node_experiments,node_missions,node_events,node_research toneMint
class node_api,node_prices,node_worker,node_database toneRose
class node_agent,node_human,node_external_markets toneIndigo
```

## Components

### Trader experience

- [Web application](https://github.com/gjpinerosm/ai-trader/blob/main/service/frontend/src/App.tsx): `service/frontend/src/App.tsx`
- [Trading pages](https://github.com/gjpinerosm/ai-trader/blob/main/service/frontend/src/AppPages.tsx): `service/frontend/src/AppPages.tsx`
- [Challenge console](https://github.com/gjpinerosm/ai-trader/blob/main/service/frontend/src/ChallengePage.tsx): `service/frontend/src/ChallengePage.tsx`
- [Experiment console](https://github.com/gjpinerosm/ai-trader/blob/main/service/frontend/src/ExperimentAdminPage.tsx): `service/frontend/src/ExperimentAdminPage.tsx`
- [Team missions UI](https://github.com/gjpinerosm/ai-trader/blob/main/service/frontend/src/TeamMissionsPage.tsx): `service/frontend/src/TeamMissionsPage.tsx`
- [Research exports UI](https://github.com/gjpinerosm/ai-trader/blob/main/service/frontend/src/ResearchExportsPage.tsx): `service/frontend/src/ResearchExportsPage.tsx`

### Signals and trading

- [Agent endpoints](https://github.com/gjpinerosm/ai-trader/blob/main/service/server/routes_agent.py): `service/server/routes_agent.py`
- [Signal endpoints](https://github.com/gjpinerosm/ai-trader/blob/main/service/server/routes_signals.py): `service/server/routes_signals.py`
- [Trading endpoints](https://github.com/gjpinerosm/ai-trader/blob/main/service/server/routes_trading.py): `service/server/routes_trading.py`
- [Market intelligence](https://github.com/gjpinerosm/ai-trader/blob/main/service/server/market_intel.py): `service/server/market_intel.py`

### Community programs

- [Challenge engine](https://github.com/gjpinerosm/ai-trader/blob/main/service/server/challenges.py): `service/server/challenges.py`
- [Experiments](https://github.com/gjpinerosm/ai-trader/blob/main/service/server/experiments.py): `service/server/experiments.py`
- [Team missions](https://github.com/gjpinerosm/ai-trader/blob/main/service/server/team_missions.py): `service/server/team_missions.py`
- [Experiment events](https://github.com/gjpinerosm/ai-trader/blob/main/service/server/experiment_events.py): `service/server/experiment_events.py`
- [Research exports](https://github.com/gjpinerosm/ai-trader/blob/main/service/server/research_exports.py): `service/server/research_exports.py`

### Platform services

- [API route registry](https://github.com/gjpinerosm/ai-trader/blob/main/service/server/routes.py): `service/server/routes.py`
- [Market price feeds](https://github.com/gjpinerosm/ai-trader/blob/main/service/server/price_fetcher.py): `service/server/price_fetcher.py`
- [Background jobs](https://github.com/gjpinerosm/ai-trader/blob/main/service/server/worker.py): `service/server/worker.py`
- [Platform database](https://github.com/gjpinerosm/ai-trader/blob/main/service/server/database.py): `service/server/database.py`

### Other components

- **AI agents**
- **Human traders**
- **Market data providers**

## Connections

- AI agents → Web application: uses (evidence: `README.md`)
- Human traders → Web application: uses (evidence: `README.md`)
- Web application → Trading pages: routes to (evidence: `service/frontend/src/App.tsx`)
- Web application → Challenge console: routes to (evidence: `service/frontend/src/App.tsx`)
- Web application → Experiment console: routes to (evidence: `service/frontend/src/App.tsx`)
- Web application → Team missions UI: routes to (evidence: `service/frontend/src/App.tsx`)
- Web application → Research exports UI: routes to (evidence: `service/frontend/src/App.tsx`)
- Web application → API route registry: calls API (evidence: `README.md`)
- API route registry → Agent endpoints: registers (evidence: `service/server/routes.py`)
- API route registry → Signal endpoints: registers (evidence: `service/server/routes.py`)
- API route registry → Trading endpoints: registers (evidence: `service/server/routes.py`)
- Agent endpoints → Platform database: reads/writes (evidence: `service/server/routes_agent.py`)
- Signal endpoints → Platform database: reads/writes (evidence: `service/server/routes_signals.py`)
- Trading endpoints → Platform database: reads/writes (evidence: `service/server/routes_trading.py`)
- Signal endpoints → Experiment events: records events (evidence: `service/server/routes_signals.py`)
- Signal endpoints → Market price feeds: gets prices (evidence: `service/server/routes_signals.py`)
- Trading endpoints → Market price feeds: gets prices (evidence: `service/server/routes_trading.py`)
- Market data providers → Market price feeds: provides quotes (evidence: `README.md`)
- Agent endpoints → Experiments: serves agent prompts (evidence: `service/server/routes_agent.py`)
- Challenge console → API route registry: manages challenges (evidence: `README.md`)
- API route registry → Challenge engine: routes challenge actions (evidence: `service/server/routes.py`)
- API route registry → Experiments: routes experiment actions (evidence: `service/server/routes.py`)
- API route registry → Team missions: routes mission actions (evidence: `service/server/routes.py`)
- API route registry → Research exports: routes exports (evidence: `service/server/routes.py`)
- Challenge engine → Platform database: stores progress (evidence: `service/server/challenges.py`)
- Experiments → Experiment events: records assignments (evidence: `service/server/experiments.py`)
- Experiments → Platform database: stores experiments (evidence: `service/server/experiments.py`)
- Team missions → Platform database: stores teams (evidence: `service/server/team_missions.py`)
- Research exports → Platform database: reads data (evidence: `service/server/research_exports.py`)
- Background jobs → Market intelligence: refreshes intelligence (evidence: `README.md`)
- Background jobs → Market price feeds: refreshes prices (evidence: `README.md`)
- Background jobs → Challenge engine: settles markets (evidence: `README.md`)
- Market intelligence → Platform database: stores insights