# likitha-1504/ai-trading architecture

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

- Interactive diagram: https://gitdiagram.com/likitha-1504/ai-trading
- Repository: https://github.com/likitha-1504/ai-trading

## Overview

AI Micro-Trading Agent is a local-first Indian-equities trading system with a React terminal, FastAPI control plane, deterministic trading controls, and an independent exit watchdog. The principal workflow runs from market ticks through features, strategy ranking, advisory AI, deterministic risk and cost sizing, broker execution, and position monitoring. Research, simulation, operations, and dashboard capabilities are shown as product branches. Workflow links follow the README; sampled code confirms selected internal responsibilities, but many subsystem integrations were not inspected.

Main entry points: [`backend/app/engine/feature_engine.py`](https://github.com/likitha-1504/ai-trading/blob/main/backend/app/engine/feature_engine.py) (Feature Engine), [`backend/app/execution/execution_engine.py`](https://github.com/likitha-1504/ai-trading/blob/main/backend/app/execution/execution_engine.py) (Execution Engine), [`backend/app/watcher/position_watcher.py`](https://github.com/likitha-1504/ai-trading/blob/main/backend/app/watcher/position_watcher.py) (Position Watcher), [`backend/app/adapters`](https://github.com/likitha-1504/ai-trading/tree/main/backend/app/adapters) (Broker Adapter)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_market_signals["Market Signals"]
  node_market_normalizer["Tick Normalizer<br/>[normalizer.py]"]
  node_feature_engine["Feature Engine<br/>[feature_engine.py]"]
  node_strategies["Strategies"]
  node_candidate_ranker["Candidate Ranker"]
  node_market_intelligence["Market Intelligence"]
end

subgraph group_trade_control["Trade Control"]
  node_ai_council["AI Council"]
  node_trade_gate["Deterministic Trade Gate<br/>[trade_gate.py]"]
  node_risk_sizing["Risk &amp; Cost Sizing<br/>[risk_engine.py]"]
end

subgraph group_execution_safety["Execution Safety"]
  node_execution_engine["Execution Engine"]
  node_broker_adapter["Broker Adapter"]
  node_position_watcher["Position Watcher"]
  node_trade_store[("SQLite WAL")]
end

subgraph group_research_ops["Research &amp; Operations"]
  node_learning["Post-Trade Learning"]
  node_backtesting["Backtesting &amp; Paper"]
  node_research["Strategy Research<br/>[research_engine.py]"]
  node_sandbox["Research Sandbox<br/>[sandbox_engine.py]"]
  node_capital_scaling["Capital Scaling<br/>[scaling_manager.py]"]
  node_recovery_ops["Recovery &amp; Operations"]
end

subgraph group_terminal["Trading Terminal"]
  node_api["REST API"]
  node_frontend["React Terminal<br/>[App.tsx]"]
  node_api_client["API Client<br/>[api.ts]"]
end

node_operator(("Trader / Operator"))
node_market_feed(("Broker Market Feed"))
node_exchange_sim["Exchange / Simulator"]

node_market_feed -->|"streams ticks"| node_market_normalizer
node_market_normalizer -->|"normalizes events"| node_feature_engine
node_feature_engine -->|"provides features"| node_strategies
node_strategies -->|"produces candidates"| node_candidate_ranker
node_candidate_ranker -->|"requests review"| node_ai_council
node_ai_council -->|"returns advice"| node_trade_gate
node_trade_gate -->|"permits candidate"| node_risk_sizing
node_risk_sizing -->|"sends sized order"| node_execution_engine
node_execution_engine -->|"dispatches order"| node_broker_adapter
node_broker_adapter -->|"submits order"| node_exchange_sim
node_market_feed -->|"supplies ticks"| node_position_watcher
node_position_watcher -->|"dispatches exits"| node_broker_adapter
node_execution_engine -->|"records trades"| node_trade_store
node_position_watcher -->|"records exits"| node_trade_store
node_trade_store -->|"supplies trade history"| node_learning
node_operator -->|"uses terminal"| node_frontend
node_frontend -->|"requests data"| node_api_client
node_api_client -->|"calls REST"| node_api
node_operator -->|"controls trading"| node_api
node_feature_engine -->|"analyzes market context"| node_market_intelligence
node_operator -->|"runs simulations"| node_backtesting
node_operator -->|"evaluates strategies"| node_research
node_research -.->|"tests in isolation"| node_sandbox
node_operator -->|"authorizes stage changes"| node_capital_scaling
node_operator -->|"manages recovery"| node_recovery_ops

click node_market_normalizer "https://github.com/likitha-1504/ai-trading/blob/main/backend/app/adapters/normalizer.py"
click node_feature_engine "https://github.com/likitha-1504/ai-trading/blob/main/backend/app/engine/feature_engine.py"
click node_strategies "https://github.com/likitha-1504/ai-trading/tree/main/backend/app/strategies"
click node_candidate_ranker "https://github.com/likitha-1504/ai-trading/blob/main/backend/app/strategies/candidate_ranker.py"
click node_market_intelligence "https://github.com/likitha-1504/ai-trading/blob/main/backend/app/market_intelligence/intelligence_engine.py"
click node_ai_council "https://github.com/likitha-1504/ai-trading/tree/main/backend/app/ai"
click node_trade_gate "https://github.com/likitha-1504/ai-trading/blob/main/backend/app/gate/trade_gate.py"
click node_risk_sizing "https://github.com/likitha-1504/ai-trading/blob/main/backend/app/capital/risk_engine.py"
click node_execution_engine "https://github.com/likitha-1504/ai-trading/blob/main/backend/app/execution/execution_engine.py"
click node_broker_adapter "https://github.com/likitha-1504/ai-trading/tree/main/backend/app/adapters"
click node_position_watcher "https://github.com/likitha-1504/ai-trading/blob/main/backend/app/watcher/position_watcher.py"
click node_trade_store "https://github.com/likitha-1504/ai-trading/tree/main/backend/app/db"
click node_learning "https://github.com/likitha-1504/ai-trading/tree/main/backend/app/learning"
click node_backtesting "https://github.com/likitha-1504/ai-trading/tree/main/backend/app/backtesting"
click node_research "https://github.com/likitha-1504/ai-trading/blob/main/backend/app/research/research_engine.py"
click node_sandbox "https://github.com/likitha-1504/ai-trading/blob/main/backend/app/sandbox/sandbox_engine.py"
click node_capital_scaling "https://github.com/likitha-1504/ai-trading/blob/main/backend/app/capital_scaling/scaling_manager.py"
click node_recovery_ops "https://github.com/likitha-1504/ai-trading/tree/main/backend/app/disaster_recovery"
click node_api "https://github.com/likitha-1504/ai-trading/tree/main/backend/app/api/v1"
click node_frontend "https://github.com/likitha-1504/ai-trading/blob/main/frontend/src/App.tsx"
click node_api_client "https://github.com/likitha-1504/ai-trading/blob/main/frontend/src/services/api.ts"

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_market_normalizer,node_feature_engine,node_strategies,node_candidate_ranker,node_market_intelligence toneBlue
class node_ai_council,node_trade_gate,node_risk_sizing toneAmber
class node_execution_engine,node_broker_adapter,node_position_watcher,node_trade_store toneMint
class node_learning,node_backtesting,node_research,node_sandbox,node_capital_scaling,node_recovery_ops toneRose
class node_api,node_frontend,node_api_client,node_operator,node_market_feed,node_exchange_sim toneIndigo
```

## Components

### Market Signals

- [Tick Normalizer](https://github.com/likitha-1504/ai-trading/blob/main/backend/app/adapters/normalizer.py): `backend/app/adapters/normalizer.py`
- [Feature Engine](https://github.com/likitha-1504/ai-trading/blob/main/backend/app/engine/feature_engine.py): `backend/app/engine/feature_engine.py`
- [Strategies](https://github.com/likitha-1504/ai-trading/tree/main/backend/app/strategies): `backend/app/strategies`
- [Candidate Ranker](https://github.com/likitha-1504/ai-trading/blob/main/backend/app/strategies/candidate_ranker.py): `backend/app/strategies/candidate_ranker.py`
- [Market Intelligence](https://github.com/likitha-1504/ai-trading/blob/main/backend/app/market_intelligence/intelligence_engine.py): `backend/app/market_intelligence/intelligence_engine.py`

### Trade Control

- [AI Council](https://github.com/likitha-1504/ai-trading/tree/main/backend/app/ai): `backend/app/ai`
- [Deterministic Trade Gate](https://github.com/likitha-1504/ai-trading/blob/main/backend/app/gate/trade_gate.py): `backend/app/gate/trade_gate.py`
- [Risk & Cost Sizing](https://github.com/likitha-1504/ai-trading/blob/main/backend/app/capital/risk_engine.py): `backend/app/capital/risk_engine.py`

### Execution Safety

- [Execution Engine](https://github.com/likitha-1504/ai-trading/blob/main/backend/app/execution/execution_engine.py): `backend/app/execution/execution_engine.py`
- [Broker Adapter](https://github.com/likitha-1504/ai-trading/tree/main/backend/app/adapters): `backend/app/adapters`
- [Position Watcher](https://github.com/likitha-1504/ai-trading/blob/main/backend/app/watcher/position_watcher.py): `backend/app/watcher/position_watcher.py`
- [SQLite WAL](https://github.com/likitha-1504/ai-trading/tree/main/backend/app/db): `backend/app/db`

### Research & Operations

- [Post-Trade Learning](https://github.com/likitha-1504/ai-trading/tree/main/backend/app/learning): `backend/app/learning`
- [Backtesting & Paper](https://github.com/likitha-1504/ai-trading/tree/main/backend/app/backtesting): `backend/app/backtesting`
- [Strategy Research](https://github.com/likitha-1504/ai-trading/blob/main/backend/app/research/research_engine.py): `backend/app/research/research_engine.py`
- [Research Sandbox](https://github.com/likitha-1504/ai-trading/blob/main/backend/app/sandbox/sandbox_engine.py): `backend/app/sandbox/sandbox_engine.py`
- [Capital Scaling](https://github.com/likitha-1504/ai-trading/blob/main/backend/app/capital_scaling/scaling_manager.py): `backend/app/capital_scaling/scaling_manager.py`
- [Recovery & Operations](https://github.com/likitha-1504/ai-trading/tree/main/backend/app/disaster_recovery): `backend/app/disaster_recovery`

### Trading Terminal

- [REST API](https://github.com/likitha-1504/ai-trading/tree/main/backend/app/api/v1): `backend/app/api/v1`
- [React Terminal](https://github.com/likitha-1504/ai-trading/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [API Client](https://github.com/likitha-1504/ai-trading/blob/main/frontend/src/services/api.ts): `frontend/src/services/api.ts`

### Other components

- **Trader / Operator**
- **Broker Market Feed**
- **Exchange / Simulator**

## Connections

- Broker Market Feed → Tick Normalizer: streams ticks
- Tick Normalizer → Feature Engine: normalizes events
- Feature Engine → Strategies: provides features
- Strategies → Candidate Ranker: produces candidates
- Candidate Ranker → AI Council: requests review
- AI Council → Deterministic Trade Gate: returns advice
- Deterministic Trade Gate → Risk & Cost Sizing: permits candidate
- Risk & Cost Sizing → Execution Engine: sends sized order
- Execution Engine → Broker Adapter: dispatches order
- Broker Adapter → Exchange / Simulator: submits order
- Broker Market Feed → Position Watcher: supplies ticks
- Position Watcher → Broker Adapter: dispatches exits
- Execution Engine → SQLite WAL: records trades
- Position Watcher → SQLite WAL: records exits
- SQLite WAL → Post-Trade Learning: supplies trade history
- Trader / Operator → React Terminal: uses terminal
- React Terminal → API Client: requests data
- API Client → REST API: calls REST
- Trader / Operator → REST API: controls trading
- Feature Engine → Market Intelligence: analyzes market context
- Trader / Operator → Backtesting & Paper: runs simulations
- Trader / Operator → Strategy Research: evaluates strategies
- Strategy Research → Research Sandbox: tests in isolation
- Trader / Operator → Capital Scaling: authorizes stage changes
- Trader / Operator → Recovery & Operations: manages recovery