# simplyaksh18/tradelens-ai architecture

> Architecture diagram of the GitHub repository simplyaksh18/tradelens-ai, 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/simplyaksh18/tradelens-ai
- Repository: https://github.com/simplyaksh18/tradelens-ai

## Overview

TradeLens is an authenticated strategy-research and auditing application. A user explores instruments and market history, computes indicators and strategy signals, then inspects forward signal outcomes, simulated backtests and performance, historical audits, and failure investigations. The API is the browser-facing entry point; documented agent/MCP capabilities are represented as a separate integration branch. Sampled engines establish the main calculation handoffs; routes and other unsampled internals are shown only where the tree and entry point support them.

Main entry points: [`backend/app/api/routes`](https://github.com/simplyaksh18/tradelens-ai/tree/main/backend/app/api/routes) (API routes), [`backend/app/strategies/engine.py`](https://github.com/simplyaksh18/tradelens-ai/blob/main/backend/app/strategies/engine.py) (Strategy evaluation), [`backend/app/outcomes/engine.py`](https://github.com/simplyaksh18/tradelens-ai/blob/main/backend/app/outcomes/engine.py) (Signal outcomes), [`backend/app/market_data/service.py`](https://github.com/simplyaksh18/tradelens-ai/blob/main/backend/app/market_data/service.py) (Market data service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Web client"]
  node_app["Application routes<br/>[App.tsx]"]
  node_pages["Research pages"]
  node_browser_api["API client<br/>[client.ts]"]
end

subgraph group_api["API and identity"]
  node_api_entry["FastAPI entry<br/>[main.py]"]
  node_auth["Authentication"]
  node_api_routes["API routes"]
end

subgraph group_market["Market data"]
  node_instruments["Instrument catalogue"]
  node_market_service["Market data service<br/>[service.py]"]
  node_market_provider["Yahoo provider"]
  node_market_cache["Market cache<br/>[cache.py]"]
  node_validation["Data validation<br/>[validator.py]"]
end

subgraph group_research["Strategy research"]
  node_indicators["Indicators<br/>[engine.py]"]
  node_strategies["Strategy evaluation<br/>[engine.py]"]
  node_outcomes["Signal outcomes<br/>[engine.py]"]
  node_backtesting["Backtesting<br/>[engine.py]"]
  node_analytics["Performance analytics<br/>[engine.py]"]
  node_audits["Strategy audits<br/>[engine.py]"]
  node_investigation["Failure investigation<br/>[engine.py]"]
  node_knowledge["Knowledge retrieval<br/>[retriever.py]"]
end

subgraph group_integration["Agent interfaces"]
  node_agent["Agent tools<br/>[agent.py]"]
  node_mcp["MCP adapter/server<br/>[server.py]"]
end

node_user(("Research user"))
node_yahoo(("Yahoo Finance"))
node_mcp_client(("MCP client"))

node_user -->|"uses"| node_app
node_app -->|"routes"| node_pages
node_pages -->|"requests"| node_browser_api
node_browser_api -->|"calls API"| node_api_entry
node_api_entry -->|"dispatches"| node_api_routes
node_api_routes -->|"authenticates"| node_auth
node_api_routes -->|"queries"| node_instruments
node_api_routes -->|"requests data"| node_market_service
node_market_service -->|"reads/writes"| node_market_cache
node_market_service -->|"fetches"| node_market_provider
node_market_provider -->|"requests quotes"| node_yahoo
node_api_routes -->|"validates data"| node_validation
node_indicators -->|"validates input"| node_validation
node_api_routes -->|"requests indicators"| node_indicators
node_api_routes -->|"requests evaluation"| node_strategies
node_strategies -->|"reads series"| node_indicators
node_api_routes -->|"requests outcomes"| node_outcomes
node_outcomes -->|"reads evaluations"| node_strategies
node_api_routes -->|"requests backtest"| node_backtesting
node_backtesting -->|"reads evaluations"| node_strategies
node_api_routes -->|"requests analytics"| node_analytics
node_analytics -->|"reads result"| node_backtesting
node_api_routes -->|"requests audit"| node_audits
node_audits -->|"reads evaluations"| node_strategies
node_audits -->|"reads outcomes"| node_outcomes
node_api_routes -->|"requests investigation"| node_investigation
node_investigation -->|"classifies outcomes"| node_outcomes
node_api_routes -.->|"retrieves knowledge"| node_knowledge
node_api_routes -.->|"invokes research"| node_agent
node_mcp_client -.->|"calls tools"| node_mcp
node_mcp -.->|"dispatches tools"| node_agent

click node_app "https://github.com/simplyaksh18/tradelens-ai/blob/main/frontend/src/App.tsx"
click node_pages "https://github.com/simplyaksh18/tradelens-ai/tree/main/frontend/src/pages"
click node_browser_api "https://github.com/simplyaksh18/tradelens-ai/blob/main/frontend/src/api/client.ts"
click node_api_entry "https://github.com/simplyaksh18/tradelens-ai/blob/main/backend/app/main.py"
click node_auth "https://github.com/simplyaksh18/tradelens-ai/tree/main/backend/app/auth"
click node_api_routes "https://github.com/simplyaksh18/tradelens-ai/tree/main/backend/app/api/routes"
click node_instruments "https://github.com/simplyaksh18/tradelens-ai/tree/main/backend/app/instruments"
click node_market_service "https://github.com/simplyaksh18/tradelens-ai/blob/main/backend/app/market_data/service.py"
click node_market_provider "https://github.com/simplyaksh18/tradelens-ai/blob/main/backend/app/market_data/providers/yfinance_provider.py"
click node_market_cache "https://github.com/simplyaksh18/tradelens-ai/blob/main/backend/app/market_data/cache.py"
click node_validation "https://github.com/simplyaksh18/tradelens-ai/blob/main/backend/app/market_data/validation/validator.py"
click node_indicators "https://github.com/simplyaksh18/tradelens-ai/blob/main/backend/app/indicators/engine.py"
click node_strategies "https://github.com/simplyaksh18/tradelens-ai/blob/main/backend/app/strategies/engine.py"
click node_outcomes "https://github.com/simplyaksh18/tradelens-ai/blob/main/backend/app/outcomes/engine.py"
click node_backtesting "https://github.com/simplyaksh18/tradelens-ai/blob/main/backend/app/backtesting/engine.py"
click node_analytics "https://github.com/simplyaksh18/tradelens-ai/blob/main/backend/app/analytics/engine.py"
click node_audits "https://github.com/simplyaksh18/tradelens-ai/blob/main/backend/app/audit/engine.py"
click node_investigation "https://github.com/simplyaksh18/tradelens-ai/blob/main/backend/app/investigation/engine.py"
click node_knowledge "https://github.com/simplyaksh18/tradelens-ai/blob/main/backend/app/knowledge/retriever.py"
click node_agent "https://github.com/simplyaksh18/tradelens-ai/blob/main/backend/app/agent/agent.py"
click node_mcp "https://github.com/simplyaksh18/tradelens-ai/blob/main/backend/app/mcp/server.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_app,node_pages,node_browser_api,node_user,node_mcp_client toneBlue
class node_api_entry,node_auth,node_api_routes toneAmber
class node_instruments,node_market_service,node_market_provider,node_market_cache,node_validation toneMint
class node_indicators,node_strategies,node_outcomes,node_backtesting,node_analytics,node_audits,node_investigation,node_knowledge toneRose
class node_agent,node_mcp,node_yahoo toneIndigo
```

## Components

### Web client

- [Application routes](https://github.com/simplyaksh18/tradelens-ai/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Research pages](https://github.com/simplyaksh18/tradelens-ai/tree/main/frontend/src/pages): `frontend/src/pages`
- [API client](https://github.com/simplyaksh18/tradelens-ai/blob/main/frontend/src/api/client.ts): `frontend/src/api/client.ts`

### API and identity

- [FastAPI entry](https://github.com/simplyaksh18/tradelens-ai/blob/main/backend/app/main.py): `backend/app/main.py`
- [Authentication](https://github.com/simplyaksh18/tradelens-ai/tree/main/backend/app/auth): `backend/app/auth`
- [API routes](https://github.com/simplyaksh18/tradelens-ai/tree/main/backend/app/api/routes): `backend/app/api/routes`

### Market data

- [Instrument catalogue](https://github.com/simplyaksh18/tradelens-ai/tree/main/backend/app/instruments): `backend/app/instruments`
- [Market data service](https://github.com/simplyaksh18/tradelens-ai/blob/main/backend/app/market_data/service.py): `backend/app/market_data/service.py`
- [Yahoo provider](https://github.com/simplyaksh18/tradelens-ai/blob/main/backend/app/market_data/providers/yfinance_provider.py): `backend/app/market_data/providers/yfinance_provider.py`
- [Market cache](https://github.com/simplyaksh18/tradelens-ai/blob/main/backend/app/market_data/cache.py): `backend/app/market_data/cache.py`
- [Data validation](https://github.com/simplyaksh18/tradelens-ai/blob/main/backend/app/market_data/validation/validator.py): `backend/app/market_data/validation/validator.py`

### Strategy research

- [Indicators](https://github.com/simplyaksh18/tradelens-ai/blob/main/backend/app/indicators/engine.py): `backend/app/indicators/engine.py`
- [Strategy evaluation](https://github.com/simplyaksh18/tradelens-ai/blob/main/backend/app/strategies/engine.py): `backend/app/strategies/engine.py`
- [Signal outcomes](https://github.com/simplyaksh18/tradelens-ai/blob/main/backend/app/outcomes/engine.py): `backend/app/outcomes/engine.py`
- [Backtesting](https://github.com/simplyaksh18/tradelens-ai/blob/main/backend/app/backtesting/engine.py): `backend/app/backtesting/engine.py`
- [Performance analytics](https://github.com/simplyaksh18/tradelens-ai/blob/main/backend/app/analytics/engine.py): `backend/app/analytics/engine.py`
- [Strategy audits](https://github.com/simplyaksh18/tradelens-ai/blob/main/backend/app/audit/engine.py): `backend/app/audit/engine.py`
- [Failure investigation](https://github.com/simplyaksh18/tradelens-ai/blob/main/backend/app/investigation/engine.py): `backend/app/investigation/engine.py`
- [Knowledge retrieval](https://github.com/simplyaksh18/tradelens-ai/blob/main/backend/app/knowledge/retriever.py): `backend/app/knowledge/retriever.py`

### Agent interfaces

- [Agent tools](https://github.com/simplyaksh18/tradelens-ai/blob/main/backend/app/agent/agent.py): `backend/app/agent/agent.py`
- [MCP adapter/server](https://github.com/simplyaksh18/tradelens-ai/blob/main/backend/app/mcp/server.py): `backend/app/mcp/server.py`

### Other components

- **Research user**
- **Yahoo Finance**
- **MCP client**

## Connections

- Research user → Application routes: uses
- Application routes → Research pages: routes
- Research pages → API client: requests
- API client → FastAPI entry: calls API
- FastAPI entry → API routes: dispatches
- API routes → Authentication: authenticates
- API routes → Instrument catalogue: queries
- API routes → Market data service: requests data
- Market data service → Market cache: reads/writes
- Market data service → Yahoo provider: fetches
- Yahoo provider → Yahoo Finance: requests quotes
- API routes → Data validation: validates data
- Indicators → Data validation: validates input
- API routes → Indicators: requests indicators
- API routes → Strategy evaluation: requests evaluation
- Strategy evaluation → Indicators: reads series
- API routes → Signal outcomes: requests outcomes
- Signal outcomes → Strategy evaluation: reads evaluations
- API routes → Backtesting: requests backtest
- Backtesting → Strategy evaluation: reads evaluations
- API routes → Performance analytics: requests analytics
- Performance analytics → Backtesting: reads result
- API routes → Strategy audits: requests audit
- Strategy audits → Strategy evaluation: reads evaluations
- Strategy audits → Signal outcomes: reads outcomes
- API routes → Failure investigation: requests investigation
- Failure investigation → Signal outcomes: classifies outcomes
- API routes → Knowledge retrieval: retrieves knowledge
- API routes → Agent tools: invokes research
- MCP client → MCP adapter/server: calls tools
- MCP adapter/server → Agent tools: dispatches tools