# quill3h/agent-ai-t-ng-h-a-vi-c-trading architecture

> Architecture diagram of the GitHub repository quill3h/agent-ai-t-ng-h-a-vi-c-trading, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/quill3h/agent-ai-t-ng-h-a-vi-c-trading
- Repository: https://github.com/quill3h/agent-ai-t-ng-h-a-vi-c-trading

## Overview

Crypto Paper Agent is a cryptocurrency market-data, strategy research, and simulated-trading system; the dependencies shown are paper-only, not live order execution. The principal workflow is historical market data into feature-enriched backtesting, strategy decisions, simulated broker execution, and performance reporting. Separate research tooling supports funding-arbitrage and reinforcement-learning experiments, while a web preview presents offline evidence. The README is empty, and excerpts are partial, so some subsystem wiring—especially data orchestration and report invocation—is not asserted.

Main entry points: [`crypto-paper-agent/src/backtest/engine.py`](https://github.com/quill3h/agent-ai-t-ng-h-a-vi-c-trading/blob/main/crypto-paper-agent/src/backtest/engine.py) (Backtest Engine), [`crypto-paper-agent/src/execution/paper_broker.py`](https://github.com/quill3h/agent-ai-t-ng-h-a-vi-c-trading/blob/main/crypto-paper-agent/src/execution/paper_broker.py) (Paper Broker), [`crypto-paper-agent/web-preview/src/App.jsx`](https://github.com/quill3h/agent-ai-t-ng-h-a-vi-c-trading/blob/main/crypto-paper-agent/web-preview/src/App.jsx) (Evidence Preview), [`crypto-paper-agent/src/data_layer/fetcher.py`](https://github.com/quill3h/agent-ai-t-ng-h-a-vi-c-trading/blob/main/crypto-paper-agent/src/data_layer/fetcher.py) (Market Fetcher)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Market Data"]
  node_fetcher["Market Fetcher<br/>[fetcher.py]"]
  node_downloader["Vision Downloader"]
  node_cache[("Parquet Cache<br/>[cache_manager.py]")]
  node_features["Feature Pipeline<br/>[indicators.py]"]
  node_news["News Calendar<br/>[news_calendar.py]"]
end

subgraph group_trading["Trading Simulation"]
  node_backtest["Backtest Engine<br/>[engine.py]"]
  node_strategies["Trading Strategies"]
  node_broker["Paper Broker<br/>[paper_broker.py]"]
  node_orders["Order Models<br/>[order_models.py]"]
  node_sizing["Position Sizing<br/>[position_sizing.py]"]
  node_invariants["Order Invariants"]
  node_breakers["Circuit Breakers"]
end

subgraph group_research["Research"]
  node_funding["Funding Arbitrage"]
  node_rl["RL Environment<br/>[rl_env.py]"]
  node_workflow["Research Workflow<br/>[workflow.py]"]
  node_validation["Research Validation<br/>[validation.py]"]
end

subgraph group_reporting["Reporting"]
  node_reports["Report Generator<br/>[generator.py]"]
  node_metrics["Performance Metrics<br/>[metrics.py]"]
  node_logger[("Trade Logger<br/>[trade_logger.py]")]
end

subgraph group_preview["Web Preview"]
  node_app["Evidence Preview<br/>[App.jsx]"]
  node_replay["Offline Replay<br/>[replay.js]"]
  node_evidence["Evidence Data<br/>[evidence.js]"]
end

node_researcher(("Researcher"))
node_binance{{"Binance public API"}}

node_researcher -->|"runs simulation"| node_backtest
node_fetcher -->|"fetches data"| node_binance
node_downloader -.->|"downloads archives"| node_binance
node_backtest -->|"computes features"| node_features
node_backtest -->|"evaluates signals"| node_strategies
node_backtest -->|"submits orders"| node_broker
node_backtest -->|"finalizes run"| node_broker
node_broker -->|"sizes orders"| node_sizing
node_funding -->|"records outcomes"| node_breakers
node_rl -->|"simulates actions"| node_broker
node_workflow -->|"validates research"| node_validation
node_reports -->|"writes trade records"| node_logger
node_app -->|"builds replay"| node_replay
node_app -->|"reads evidence"| node_evidence

click node_fetcher "https://github.com/quill3h/agent-ai-t-ng-h-a-vi-c-trading/blob/main/crypto-paper-agent/src/data_layer/fetcher.py"
click node_downloader "https://github.com/quill3h/agent-ai-t-ng-h-a-vi-c-trading/blob/main/crypto-paper-agent/src/data_layer/binance_vision_downloader.py"
click node_cache "https://github.com/quill3h/agent-ai-t-ng-h-a-vi-c-trading/blob/main/crypto-paper-agent/src/data_layer/cache_manager.py"
click node_features "https://github.com/quill3h/agent-ai-t-ng-h-a-vi-c-trading/blob/main/crypto-paper-agent/src/features/indicators.py"
click node_news "https://github.com/quill3h/agent-ai-t-ng-h-a-vi-c-trading/blob/main/crypto-paper-agent/src/features/news_calendar.py"
click node_backtest "https://github.com/quill3h/agent-ai-t-ng-h-a-vi-c-trading/blob/main/crypto-paper-agent/src/backtest/engine.py"
click node_strategies "https://github.com/quill3h/agent-ai-t-ng-h-a-vi-c-trading/tree/main/crypto-paper-agent/src/strategies"
click node_broker "https://github.com/quill3h/agent-ai-t-ng-h-a-vi-c-trading/blob/main/crypto-paper-agent/src/execution/paper_broker.py"
click node_orders "https://github.com/quill3h/agent-ai-t-ng-h-a-vi-c-trading/blob/main/crypto-paper-agent/src/execution/order_models.py"
click node_sizing "https://github.com/quill3h/agent-ai-t-ng-h-a-vi-c-trading/blob/main/crypto-paper-agent/src/risk/position_sizing.py"
click node_invariants "https://github.com/quill3h/agent-ai-t-ng-h-a-vi-c-trading/blob/main/crypto-paper-agent/src/risk/invariant_checks.py"
click node_breakers "https://github.com/quill3h/agent-ai-t-ng-h-a-vi-c-trading/blob/main/crypto-paper-agent/src/risk/circuit_breakers.py"
click node_funding "https://github.com/quill3h/agent-ai-t-ng-h-a-vi-c-trading/blob/main/crypto-paper-agent/src/strategies/funding_arbitrage.py"
click node_rl "https://github.com/quill3h/agent-ai-t-ng-h-a-vi-c-trading/blob/main/crypto-paper-agent/src/research/rl_env.py"
click node_workflow "https://github.com/quill3h/agent-ai-t-ng-h-a-vi-c-trading/blob/main/crypto-paper-agent/src/research/workflow.py"
click node_validation "https://github.com/quill3h/agent-ai-t-ng-h-a-vi-c-trading/blob/main/crypto-paper-agent/src/research/validation.py"
click node_reports "https://github.com/quill3h/agent-ai-t-ng-h-a-vi-c-trading/blob/main/crypto-paper-agent/src/report/generator.py"
click node_metrics "https://github.com/quill3h/agent-ai-t-ng-h-a-vi-c-trading/blob/main/crypto-paper-agent/src/report/metrics.py"
click node_logger "https://github.com/quill3h/agent-ai-t-ng-h-a-vi-c-trading/blob/main/crypto-paper-agent/src/logging/trade_logger.py"
click node_app "https://github.com/quill3h/agent-ai-t-ng-h-a-vi-c-trading/blob/main/crypto-paper-agent/web-preview/src/App.jsx"
click node_replay "https://github.com/quill3h/agent-ai-t-ng-h-a-vi-c-trading/blob/main/crypto-paper-agent/web-preview/src/lib/replay.js"
click node_evidence "https://github.com/quill3h/agent-ai-t-ng-h-a-vi-c-trading/blob/main/crypto-paper-agent/web-preview/src/data/evidence.js"

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_fetcher,node_downloader,node_cache,node_features,node_news toneBlue
class node_backtest,node_strategies,node_broker,node_orders,node_sizing,node_invariants,node_breakers toneAmber
class node_funding,node_rl,node_workflow,node_validation,node_binance toneMint
class node_reports,node_metrics,node_logger toneRose
class node_app,node_replay,node_evidence,node_researcher toneIndigo
```

## Components

### Market Data

- [Market Fetcher](https://github.com/quill3h/agent-ai-t-ng-h-a-vi-c-trading/blob/main/crypto-paper-agent/src/data_layer/fetcher.py): `crypto-paper-agent/src/data_layer/fetcher.py`
- [Vision Downloader](https://github.com/quill3h/agent-ai-t-ng-h-a-vi-c-trading/blob/main/crypto-paper-agent/src/data_layer/binance_vision_downloader.py): `crypto-paper-agent/src/data_layer/binance_vision_downloader.py`
- [Parquet Cache](https://github.com/quill3h/agent-ai-t-ng-h-a-vi-c-trading/blob/main/crypto-paper-agent/src/data_layer/cache_manager.py): `crypto-paper-agent/src/data_layer/cache_manager.py`
- [Feature Pipeline](https://github.com/quill3h/agent-ai-t-ng-h-a-vi-c-trading/blob/main/crypto-paper-agent/src/features/indicators.py): `crypto-paper-agent/src/features/indicators.py`
- [News Calendar](https://github.com/quill3h/agent-ai-t-ng-h-a-vi-c-trading/blob/main/crypto-paper-agent/src/features/news_calendar.py): `crypto-paper-agent/src/features/news_calendar.py`

### Trading Simulation

- [Backtest Engine](https://github.com/quill3h/agent-ai-t-ng-h-a-vi-c-trading/blob/main/crypto-paper-agent/src/backtest/engine.py): `crypto-paper-agent/src/backtest/engine.py`
- [Trading Strategies](https://github.com/quill3h/agent-ai-t-ng-h-a-vi-c-trading/tree/main/crypto-paper-agent/src/strategies): `crypto-paper-agent/src/strategies`
- [Paper Broker](https://github.com/quill3h/agent-ai-t-ng-h-a-vi-c-trading/blob/main/crypto-paper-agent/src/execution/paper_broker.py): `crypto-paper-agent/src/execution/paper_broker.py`
- [Order Models](https://github.com/quill3h/agent-ai-t-ng-h-a-vi-c-trading/blob/main/crypto-paper-agent/src/execution/order_models.py): `crypto-paper-agent/src/execution/order_models.py`
- [Position Sizing](https://github.com/quill3h/agent-ai-t-ng-h-a-vi-c-trading/blob/main/crypto-paper-agent/src/risk/position_sizing.py): `crypto-paper-agent/src/risk/position_sizing.py`
- [Order Invariants](https://github.com/quill3h/agent-ai-t-ng-h-a-vi-c-trading/blob/main/crypto-paper-agent/src/risk/invariant_checks.py): `crypto-paper-agent/src/risk/invariant_checks.py`
- [Circuit Breakers](https://github.com/quill3h/agent-ai-t-ng-h-a-vi-c-trading/blob/main/crypto-paper-agent/src/risk/circuit_breakers.py): `crypto-paper-agent/src/risk/circuit_breakers.py`

### Research

- [Funding Arbitrage](https://github.com/quill3h/agent-ai-t-ng-h-a-vi-c-trading/blob/main/crypto-paper-agent/src/strategies/funding_arbitrage.py): `crypto-paper-agent/src/strategies/funding_arbitrage.py`
- [RL Environment](https://github.com/quill3h/agent-ai-t-ng-h-a-vi-c-trading/blob/main/crypto-paper-agent/src/research/rl_env.py): `crypto-paper-agent/src/research/rl_env.py`
- [Research Workflow](https://github.com/quill3h/agent-ai-t-ng-h-a-vi-c-trading/blob/main/crypto-paper-agent/src/research/workflow.py): `crypto-paper-agent/src/research/workflow.py`
- [Research Validation](https://github.com/quill3h/agent-ai-t-ng-h-a-vi-c-trading/blob/main/crypto-paper-agent/src/research/validation.py): `crypto-paper-agent/src/research/validation.py`

### Reporting

- [Report Generator](https://github.com/quill3h/agent-ai-t-ng-h-a-vi-c-trading/blob/main/crypto-paper-agent/src/report/generator.py): `crypto-paper-agent/src/report/generator.py`
- [Performance Metrics](https://github.com/quill3h/agent-ai-t-ng-h-a-vi-c-trading/blob/main/crypto-paper-agent/src/report/metrics.py): `crypto-paper-agent/src/report/metrics.py`
- [Trade Logger](https://github.com/quill3h/agent-ai-t-ng-h-a-vi-c-trading/blob/main/crypto-paper-agent/src/logging/trade_logger.py): `crypto-paper-agent/src/logging/trade_logger.py`

### Web Preview

- [Evidence Preview](https://github.com/quill3h/agent-ai-t-ng-h-a-vi-c-trading/blob/main/crypto-paper-agent/web-preview/src/App.jsx): `crypto-paper-agent/web-preview/src/App.jsx`
- [Offline Replay](https://github.com/quill3h/agent-ai-t-ng-h-a-vi-c-trading/blob/main/crypto-paper-agent/web-preview/src/lib/replay.js): `crypto-paper-agent/web-preview/src/lib/replay.js`
- [Evidence Data](https://github.com/quill3h/agent-ai-t-ng-h-a-vi-c-trading/blob/main/crypto-paper-agent/web-preview/src/data/evidence.js): `crypto-paper-agent/web-preview/src/data/evidence.js`

### Other components

- **Researcher**
- **Binance public API**

## Connections

- Researcher → Backtest Engine: runs simulation
- Market Fetcher → Binance public API: fetches data
- Vision Downloader → Binance public API: downloads archives
- Backtest Engine → Feature Pipeline: computes features
- Backtest Engine → Trading Strategies: evaluates signals
- Backtest Engine → Paper Broker: submits orders
- Backtest Engine → Paper Broker: finalizes run
- Paper Broker → Position Sizing: sizes orders
- Funding Arbitrage → Circuit Breakers: records outcomes
- RL Environment → Paper Broker: simulates actions
- Research Workflow → Research Validation: validates research
- Report Generator → Trade Logger: writes trade records
- Evidence Preview → Offline Replay: builds replay
- Evidence Preview → Evidence Data: reads evidence