# alanmac07/trading-agent architecture

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

- Interactive diagram: https://gitdiagram.com/alanmac07/trading-agent
- Repository: https://github.com/alanmac07/trading-agent

## Overview

This repository combines an evolutionary trading simulator and dashboard with a separate NEAT training and holdout-evaluation workflow. In the interactive path, market data feeds the FastAPI server and evolution engine; in the research path, data is engineered and split, then evolved across episodes and scored. The README also describes a legacy continuous-engine feature pipeline, but its agent and dashboard files are absent from this tree. Some frontend-to-server wiring is not established by the excerpts, so that link is marked unverified.

Main entry points: [`neat_engine/build_dataset.py`](https://github.com/alanmac07/trading-agent/blob/main/neat_engine/build_dataset.py) (Dataset builder), [`neat_engine/trainer.py`](https://github.com/alanmac07/trading-agent/blob/main/neat_engine/trainer.py) (Population trainer), [`neat_engine/evaluate_holdout.py`](https://github.com/alanmac07/trading-agent/blob/main/neat_engine/evaluate_holdout.py) (Holdout evaluator), [`data/price_data_multi.csv`](https://github.com/alanmac07/trading-agent/blob/main/data/price_data_multi.csv) (Historical market data)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interactive["Interactive simulation"]
  node_server["Simulation API<br/>[server.py]"]
  node_engine["Evolution engine<br/>[evolution.py]"]
end

subgraph group_neat["NEAT research engine"]
  node_dataset["Dataset builder<br/>[build_dataset.py]"]
  node_features["NEAT features<br/>[features.py]"]
  node_episodes["Episode windows<br/>[episodes.py]"]
  node_trainer["Population trainer<br/>[trainer.py]"]
  node_fitness["Fitness evaluation<br/>[fitness.py]"]
  node_network["Genome network<br/>[network_agent.py]"]
  node_risk["Trade risk rules<br/>[risk_manager.py]"]
  node_genome["Best genome"]
  node_holdout["Holdout evaluator"]
end

subgraph group_data["Market data"]
  node_market_source["Historical market data"]
  node_fetch["Market data fetcher<br/>[fetch_data.py]"]
  node_legacy_features["Continuous indicators"]
  node_train_sets["Training datasets"]
  node_test_sets["Holdout datasets"]
end

subgraph group_ui["Dashboard interface"]
  node_dashboard["Dashboard page<br/>[page.tsx]"]
  node_dashboard_components["Agent views and charts"]
  node_api_client["API client<br/>[api.ts]"]
end

node_user(("User"))

node_user -->|"uses"| node_dashboard
node_dashboard -.->|"requests data"| node_api_client
node_api_client -.->|"calls API"| node_server
node_server -->|"runs simulation"| node_engine
node_server -->|"loads data"| node_market_source
node_fetch -->|"writes prices"| node_market_source
node_legacy_features -->|"reads prices"| node_market_source
node_dataset -->|"reads prices"| node_market_source
node_dataset -->|"computes features"| node_features
node_dataset -->|"writes split"| node_train_sets
node_dataset -->|"writes split"| node_test_sets
node_trainer -->|"builds windows"| node_episodes
node_trainer -->|"scores genomes"| node_fitness
node_trainer -->|"reads training data"| node_train_sets
node_fitness -->|"queries signals"| node_network
node_fitness -->|"gets trade decisions"| node_risk
node_trainer -->|"saves winner"| node_genome
node_holdout -->|"queries signals"| node_network
node_holdout -->|"gets trade decisions"| node_risk
node_holdout -->|"reads holdout"| node_test_sets
node_holdout -->|"loads winner"| node_genome
node_dashboard -.->|"renders views"| node_dashboard_components

click node_dashboard "https://github.com/alanmac07/trading-agent/blob/main/frontend/src/app/page.tsx"
click node_dashboard_components "https://github.com/alanmac07/trading-agent/tree/main/frontend/src/components"
click node_api_client "https://github.com/alanmac07/trading-agent/blob/main/frontend/src/lib/api.ts"
click node_server "https://github.com/alanmac07/trading-agent/blob/main/server.py"
click node_engine "https://github.com/alanmac07/trading-agent/blob/main/evolution.py"
click node_market_source "https://github.com/alanmac07/trading-agent/blob/main/data/price_data_multi.csv"
click node_fetch "https://github.com/alanmac07/trading-agent/blob/main/fetch_data.py"
click node_legacy_features "https://github.com/alanmac07/trading-agent/blob/main/feature_engineering.py"
click node_dataset "https://github.com/alanmac07/trading-agent/blob/main/neat_engine/build_dataset.py"
click node_features "https://github.com/alanmac07/trading-agent/blob/main/neat_engine/features.py"
click node_train_sets "https://github.com/alanmac07/trading-agent/tree/main/data"
click node_test_sets "https://github.com/alanmac07/trading-agent/tree/main/data"
click node_episodes "https://github.com/alanmac07/trading-agent/blob/main/neat_engine/episodes.py"
click node_trainer "https://github.com/alanmac07/trading-agent/blob/main/neat_engine/trainer.py"
click node_fitness "https://github.com/alanmac07/trading-agent/blob/main/neat_engine/fitness.py"
click node_network "https://github.com/alanmac07/trading-agent/blob/main/neat_engine/network_agent.py"
click node_risk "https://github.com/alanmac07/trading-agent/blob/main/neat_engine/risk_manager.py"
click node_genome "https://github.com/alanmac07/trading-agent/tree/main/results"
click node_holdout "https://github.com/alanmac07/trading-agent/blob/main/neat_engine/evaluate_holdout.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_server,node_engine,node_user toneBlue
class node_dataset,node_features,node_episodes,node_trainer,node_fitness,node_network,node_risk,node_genome,node_holdout toneAmber
class node_market_source,node_fetch,node_legacy_features,node_train_sets,node_test_sets toneMint
class node_dashboard,node_dashboard_components,node_api_client toneRose
```

## Components

### Interactive simulation

- [Simulation API](https://github.com/alanmac07/trading-agent/blob/main/server.py): `server.py`
- [Evolution engine](https://github.com/alanmac07/trading-agent/blob/main/evolution.py): `evolution.py`

### NEAT research engine

- [Dataset builder](https://github.com/alanmac07/trading-agent/blob/main/neat_engine/build_dataset.py): `neat_engine/build_dataset.py`
- [NEAT features](https://github.com/alanmac07/trading-agent/blob/main/neat_engine/features.py): `neat_engine/features.py`
- [Episode windows](https://github.com/alanmac07/trading-agent/blob/main/neat_engine/episodes.py): `neat_engine/episodes.py`
- [Population trainer](https://github.com/alanmac07/trading-agent/blob/main/neat_engine/trainer.py): `neat_engine/trainer.py`
- [Fitness evaluation](https://github.com/alanmac07/trading-agent/blob/main/neat_engine/fitness.py): `neat_engine/fitness.py`
- [Genome network](https://github.com/alanmac07/trading-agent/blob/main/neat_engine/network_agent.py): `neat_engine/network_agent.py`
- [Trade risk rules](https://github.com/alanmac07/trading-agent/blob/main/neat_engine/risk_manager.py): `neat_engine/risk_manager.py`
- [Best genome](https://github.com/alanmac07/trading-agent/tree/main/results): `results`
- [Holdout evaluator](https://github.com/alanmac07/trading-agent/blob/main/neat_engine/evaluate_holdout.py): `neat_engine/evaluate_holdout.py`

### Market data

- [Historical market data](https://github.com/alanmac07/trading-agent/blob/main/data/price_data_multi.csv): `data/price_data_multi.csv`
- [Market data fetcher](https://github.com/alanmac07/trading-agent/blob/main/fetch_data.py): `fetch_data.py`
- [Continuous indicators](https://github.com/alanmac07/trading-agent/blob/main/feature_engineering.py): `feature_engineering.py`
- [Training datasets](https://github.com/alanmac07/trading-agent/tree/main/data): `data`
- [Holdout datasets](https://github.com/alanmac07/trading-agent/tree/main/data): `data`

### Dashboard interface

- [Dashboard page](https://github.com/alanmac07/trading-agent/blob/main/frontend/src/app/page.tsx): `frontend/src/app/page.tsx`
- [Agent views and charts](https://github.com/alanmac07/trading-agent/tree/main/frontend/src/components): `frontend/src/components`
- [API client](https://github.com/alanmac07/trading-agent/blob/main/frontend/src/lib/api.ts): `frontend/src/lib/api.ts`

### Other components

- **User**

## Connections

- User → Dashboard page: uses (evidence: `README.md`)
- Dashboard page → API client: requests data
- API client → Simulation API: calls API
- Simulation API → Evolution engine: runs simulation (evidence: `server.py`)
- Simulation API → Historical market data: loads data (evidence: `server.py`)
- Market data fetcher → Historical market data: writes prices (evidence: `README.md`)
- Continuous indicators → Historical market data: reads prices (evidence: `README.md`)
- Dataset builder → Historical market data: reads prices (evidence: `neat_engine/build_dataset.py`)
- Dataset builder → NEAT features: computes features (evidence: `neat_engine/build_dataset.py`)
- Dataset builder → Training datasets: writes split (evidence: `neat_engine/build_dataset.py`)
- Dataset builder → Holdout datasets: writes split (evidence: `neat_engine/build_dataset.py`)
- Population trainer → Episode windows: builds windows (evidence: `neat_engine/trainer.py`)
- Population trainer → Fitness evaluation: scores genomes (evidence: `neat_engine/trainer.py`)
- Population trainer → Training datasets: reads training data (evidence: `README.md`)
- Fitness evaluation → Genome network: queries signals (evidence: `neat_engine/fitness.py`)
- Fitness evaluation → Trade risk rules: gets trade decisions (evidence: `neat_engine/fitness.py`)
- Population trainer → Best genome: saves winner (evidence: `neat_engine/trainer.py`)
- Holdout evaluator → Genome network: queries signals (evidence: `neat_engine/evaluate_holdout.py`)
- Holdout evaluator → Trade risk rules: gets trade decisions (evidence: `neat_engine/evaluate_holdout.py`)
- Holdout evaluator → Holdout datasets: reads holdout (evidence: `neat_engine/evaluate_holdout.py`)
- Holdout evaluator → Best genome: loads winner (evidence: `neat_engine/evaluate_holdout.py`)
- Dashboard page → Agent views and charts: renders views
