AI-Trader/docs/developer/architecture.md

Architecture

System design and component overview.

---

Component Diagram

See README.md for architecture diagram.

---

Key Components

FastAPI Server (api/main.py)

• REST API endpoints
• Request validation
• Response formatting

Job Manager (api/job_manager.py)

• Job lifecycle management
• SQLite operations
• Concurrency control

Simulation Worker (api/simulation_worker.py)

• Background job execution
• Date-sequential, model-parallel orchestration
• Error handling

Model-Day Executor (api/model_day_executor.py)

• Single model-day execution
• Runtime config isolation
• Agent invocation

Base Agent (agent/base_agent/base_agent.py)

• Trading session execution
• MCP tool integration
• Position management

MCP Services (agent_tools/)

• Math, Search, Trade, Price tools
• Internal HTTP servers
• Localhost-only access

---

Data Flow

1. API receives trigger request
2. Job Manager validates and creates job
3. Worker starts background execution
4. For each date (sequential):
   • For each model (parallel):
     • Executor creates isolated runtime config
     • Agent executes trading session
     • Results stored in database
5. Job status updated
6. Results available via API

---

Anti-Look-Ahead Controls

• TODAY_DATE in runtime config limits data access
• Price queries filter by date
• Search results filtered by publication date

See CLAUDE.md for implementation details.

---

Position Tracking Across Jobs

Design: Portfolio state is tracked per-model across all jobs, not per-job.

Query Logic:

# Get starting position for current trading day
SELECT id, ending_cash FROM trading_days
WHERE model = ? AND date < ?  # No job_id filter
ORDER BY date DESC
LIMIT 1

Benefits:

• Portfolio continuity when creating new jobs with overlapping dates
• Prevents accidental portfolio resets
• Enables flexible job scheduling (resume, rerun, backfill)

Example:

• Job 1: Runs 2025-10-13 to 2025-10-15 for model-a
• Job 2: Runs 2025-10-16 to 2025-10-20 for model-a
• Job 2 starts with Job 1's ending position from 2025-10-15