# atul2501/reserch_model architecture

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

- Interactive diagram: https://gitdiagram.com/atul2501/reserch_model
- Repository: https://github.com/atul2501/reserch_model

## Overview

This is a paper-first crypto strategy research and trading platform: a worker turns confirmed market candles into per-agent decisions, applies deterministic risk controls, simulates execution, and records outcomes. A separate scheduled research process evaluates and stress-tests strategies, evolves candidates, and gates promotion using a protected out-of-sample lockbox and champion/challenger governance. The API exposes operational and research views. The README documents the product workflow; sampled source confirms key risk, feature, backtest, fitness, and validation behavior, while some wiring is represented only by that documentation.

Main entry points: [`backend/app/research/pipeline.py`](https://github.com/atul2501/reserch_model/blob/main/backend/app/research/pipeline.py) (Evolution Pipeline), [`backend/app/worker/cycle.py`](https://github.com/atul2501/reserch_model/blob/main/backend/app/worker/cycle.py) (Trading Worker), [`backend/app/agents/decision_loop.py`](https://github.com/atul2501/reserch_model/blob/main/backend/app/agents/decision_loop.py) (Agent Decisions), [`backend/app/execution/router.py`](https://github.com/atul2501/reserch_model/blob/main/backend/app/execution/router.py) (Execution Router)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_trading["Market and Trading"]
  node_worker["Trading Worker<br/>[cycle.py]"]
  node_market_data["Market Data"]
  node_features["Features and Regime<br/>[feature_engine.py]"]
  node_council["AI Council<br/>[service.py]"]
  node_agents["Agent Decisions<br/>[decision_loop.py]"]
  node_strategies["Strategy DNA<br/>[engine.py]"]
  node_risk["Risk Engine<br/>[risk_engine.py]"]
  node_execution["Execution Router<br/>[router.py]"]
  node_paper["Paper Execution<br/>[paper_adapter.py]"]
  node_shadow["Shadow Execution<br/>[shadow_adapter.py]"]
  node_positions["Position Management"]
end

subgraph group_research["Research and Evolution"]
  node_research_pipeline["Evolution Pipeline<br/>[pipeline.py]"]
  node_backtest["Backtesting<br/>[engine.py]"]
  node_regime_validation["Regime Validation"]
  node_fitness["Fitness Scoring<br/>[fitness_engine.py]"]
  node_evolution["Breeding and Promotion"]
  node_lockbox["OOS Lockbox<br/>[lockbox.py]"]
end

subgraph group_governance["Analytics and Governance"]
  node_pnl["PnL Accounting<br/>[pnl_engine.py]"]
  node_database[("Application Database<br/>[database.py]")]
  node_analytics["Performance Analytics"]
end

subgraph group_api["API and Operations"]
  node_api_app["API Application<br/>[main.py]"]
  node_routes["API Routes"]
end

node_exchange(("Hyperliquid"))
node_operator(("Operator and Viewer"))

node_exchange -->|"streams market data"| node_market_data
node_market_data -->|"feeds closed candles"| node_worker
node_worker -->|"builds context"| node_features
node_worker -->|"requests context"| node_council
node_worker -->|"dispatches candle"| node_agents
node_agents -->|"evaluates DNA"| node_strategies
node_agents -->|"checks proposed trade"| node_risk
node_agents -->|"routes approved trade"| node_execution
node_execution -->|"dispatches paper"| node_paper
node_execution -->|"dispatches shadow"| node_shadow
node_worker -->|"manages open positions"| node_positions
node_positions -->|"routes exits"| node_execution
node_positions -->|"computes realized PnL"| node_pnl
node_worker -->|"persists cycle state"| node_database
node_research_pipeline -->|"validates strategies"| node_backtest
node_research_pipeline -->|"checks regime robustness"| node_regime_validation
node_research_pipeline -->|"scores agents"| node_fitness
node_research_pipeline -->|"selects and breeds"| node_evolution
node_research_pipeline -->|"gates OOS use"| node_lockbox
node_research_pipeline -->|"reads and records research"| node_database
node_analytics -->|"reads trade records"| node_database
node_api_app -->|"mounts routes"| node_routes
node_operator -->|"requests API"| node_api_app
node_routes -->|"reads product state"| node_database

click node_worker "https://github.com/atul2501/reserch_model/blob/main/backend/app/worker/cycle.py"
click node_market_data "https://github.com/atul2501/reserch_model/blob/main/backend/app/market/market_data_service.py"
click node_features "https://github.com/atul2501/reserch_model/blob/main/backend/app/market/feature_engine.py"
click node_council "https://github.com/atul2501/reserch_model/blob/main/backend/app/council/service.py"
click node_agents "https://github.com/atul2501/reserch_model/blob/main/backend/app/agents/decision_loop.py"
click node_strategies "https://github.com/atul2501/reserch_model/blob/main/backend/app/strategies/engine.py"
click node_risk "https://github.com/atul2501/reserch_model/blob/main/backend/app/risk/risk_engine.py"
click node_execution "https://github.com/atul2501/reserch_model/blob/main/backend/app/execution/router.py"
click node_paper "https://github.com/atul2501/reserch_model/blob/main/backend/app/execution/paper_adapter.py"
click node_shadow "https://github.com/atul2501/reserch_model/blob/main/backend/app/execution/shadow_adapter.py"
click node_positions "https://github.com/atul2501/reserch_model/blob/main/backend/app/agents/position_manager.py"
click node_pnl "https://github.com/atul2501/reserch_model/blob/main/backend/app/analytics/pnl_engine.py"
click node_database "https://github.com/atul2501/reserch_model/blob/main/backend/app/core/database.py"
click node_research_pipeline "https://github.com/atul2501/reserch_model/blob/main/backend/app/research/pipeline.py"
click node_backtest "https://github.com/atul2501/reserch_model/blob/main/backend/app/backtesting/engine.py"
click node_regime_validation "https://github.com/atul2501/reserch_model/blob/main/backend/app/backtesting/regime_validation_engine.py"
click node_fitness "https://github.com/atul2501/reserch_model/blob/main/backend/app/analytics/fitness_engine.py"
click node_evolution "https://github.com/atul2501/reserch_model/tree/main/backend/app/evolution"
click node_lockbox "https://github.com/atul2501/reserch_model/blob/main/backend/app/research/lockbox.py"
click node_analytics "https://github.com/atul2501/reserch_model/tree/main/backend/app/analytics"
click node_api_app "https://github.com/atul2501/reserch_model/blob/main/backend/app/main.py"
click node_routes "https://github.com/atul2501/reserch_model/tree/main/backend/app/api/routes"

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_worker,node_market_data,node_features,node_council,node_agents,node_strategies,node_risk,node_execution,node_paper,node_shadow,node_positions,node_operator toneBlue
class node_research_pipeline,node_backtest,node_regime_validation,node_fitness,node_evolution,node_lockbox toneAmber
class node_pnl,node_database,node_analytics toneMint
class node_api_app,node_routes toneRose
class node_exchange toneIndigo
```

## Components

### Market and Trading

- [Trading Worker](https://github.com/atul2501/reserch_model/blob/main/backend/app/worker/cycle.py): `backend/app/worker/cycle.py`
- [Market Data](https://github.com/atul2501/reserch_model/blob/main/backend/app/market/market_data_service.py): `backend/app/market/market_data_service.py`
- [Features and Regime](https://github.com/atul2501/reserch_model/blob/main/backend/app/market/feature_engine.py): `backend/app/market/feature_engine.py`
- [AI Council](https://github.com/atul2501/reserch_model/blob/main/backend/app/council/service.py): `backend/app/council/service.py`
- [Agent Decisions](https://github.com/atul2501/reserch_model/blob/main/backend/app/agents/decision_loop.py): `backend/app/agents/decision_loop.py`
- [Strategy DNA](https://github.com/atul2501/reserch_model/blob/main/backend/app/strategies/engine.py): `backend/app/strategies/engine.py`
- [Risk Engine](https://github.com/atul2501/reserch_model/blob/main/backend/app/risk/risk_engine.py): `backend/app/risk/risk_engine.py`
- [Execution Router](https://github.com/atul2501/reserch_model/blob/main/backend/app/execution/router.py): `backend/app/execution/router.py`
- [Paper Execution](https://github.com/atul2501/reserch_model/blob/main/backend/app/execution/paper_adapter.py): `backend/app/execution/paper_adapter.py`
- [Shadow Execution](https://github.com/atul2501/reserch_model/blob/main/backend/app/execution/shadow_adapter.py): `backend/app/execution/shadow_adapter.py`
- [Position Management](https://github.com/atul2501/reserch_model/blob/main/backend/app/agents/position_manager.py): `backend/app/agents/position_manager.py`

### Research and Evolution

- [Evolution Pipeline](https://github.com/atul2501/reserch_model/blob/main/backend/app/research/pipeline.py): `backend/app/research/pipeline.py`
- [Backtesting](https://github.com/atul2501/reserch_model/blob/main/backend/app/backtesting/engine.py): `backend/app/backtesting/engine.py`
- [Regime Validation](https://github.com/atul2501/reserch_model/blob/main/backend/app/backtesting/regime_validation_engine.py): `backend/app/backtesting/regime_validation_engine.py`
- [Fitness Scoring](https://github.com/atul2501/reserch_model/blob/main/backend/app/analytics/fitness_engine.py): `backend/app/analytics/fitness_engine.py`
- [Breeding and Promotion](https://github.com/atul2501/reserch_model/tree/main/backend/app/evolution): `backend/app/evolution`
- [OOS Lockbox](https://github.com/atul2501/reserch_model/blob/main/backend/app/research/lockbox.py): `backend/app/research/lockbox.py`

### Analytics and Governance

- [PnL Accounting](https://github.com/atul2501/reserch_model/blob/main/backend/app/analytics/pnl_engine.py): `backend/app/analytics/pnl_engine.py`
- [Application Database](https://github.com/atul2501/reserch_model/blob/main/backend/app/core/database.py): `backend/app/core/database.py`
- [Performance Analytics](https://github.com/atul2501/reserch_model/tree/main/backend/app/analytics): `backend/app/analytics`

### API and Operations

- [API Application](https://github.com/atul2501/reserch_model/blob/main/backend/app/main.py): `backend/app/main.py`
- [API Routes](https://github.com/atul2501/reserch_model/tree/main/backend/app/api/routes): `backend/app/api/routes`

### Other components

- **Hyperliquid**
- **Operator and Viewer**

## Connections

- Hyperliquid → Market Data: streams market data
- Market Data → Trading Worker: feeds closed candles
- Trading Worker → Features and Regime: builds context
- Trading Worker → AI Council: requests context
- Trading Worker → Agent Decisions: dispatches candle
- Agent Decisions → Strategy DNA: evaluates DNA
- Agent Decisions → Risk Engine: checks proposed trade
- Agent Decisions → Execution Router: routes approved trade
- Execution Router → Paper Execution: dispatches paper
- Execution Router → Shadow Execution: dispatches shadow
- Trading Worker → Position Management: manages open positions
- Position Management → Execution Router: routes exits
- Position Management → PnL Accounting: computes realized PnL
- Trading Worker → Application Database: persists cycle state
- Evolution Pipeline → Backtesting: validates strategies
- Evolution Pipeline → Regime Validation: checks regime robustness
- Evolution Pipeline → Fitness Scoring: scores agents
- Evolution Pipeline → Breeding and Promotion: selects and breeds
- Evolution Pipeline → OOS Lockbox: gates OOS use
- Evolution Pipeline → Application Database: reads and records research
- Performance Analytics → Application Database: reads trade records
- API Application → API Routes: mounts routes
- Operator and Viewer → API Application: requests API
- API Routes → Application Database: reads product state