# basiltt/candleviewer architecture

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

- Interactive diagram: https://gitdiagram.com/basiltt/candleviewer
- Repository: https://github.com/basiltt/candleviewer

## Overview

CandleViewer is a pre-alpha charting platform with a React web client, GPU-oriented chart-engine package, and Python API. The implemented backend has concrete ingestion, instrument-catalogue, market-data, authentication, audit, and trading-domain modules; the README’s indicators, scripting, collaboration, and richer charting features are largely roadmap goals, so those are shown as planned capabilities rather than verified runtime integrations. The clearest evidenced runtime path is web app startup and routing, plus API composition and lifecycle. Several API modules were not sampled, so some subsystem links are documented or left unverified.

Main entry points: [`services/api/candleviewer/app.py`](https://github.com/basiltt/candleviewer/blob/main/services/api/candleviewer/app.py) (API composition), [`apps/web/src/main.tsx`](https://github.com/basiltt/candleviewer/blob/main/apps/web/src/main.tsx) (Web application), [`services/api/candleviewer/main.py`](https://github.com/basiltt/candleviewer/blob/main/services/api/candleviewer/main.py) (ASGI lifecycle), [`services/api/candleviewer/ingestion/service.py`](https://github.com/basiltt/candleviewer/blob/main/services/api/candleviewer/ingestion/service.py) (Feed ingestion)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client"]
  node_web["Web application<br/>[main.tsx]"]
  node_routes["Route tree<br/>[tree.tsx]"]
  node_chart["Chart engine<br/>[handle.ts]"]
  node_desktop["Desktop shell<br/>[shellPort.ts]"]
end

subgraph group_market["Market data"]
  node_ingest["Feed ingestion<br/>[service.py]"]
  node_instrument_refresh["Instrument refresh"]
  node_exchange["Exchange adapters<br/>[instruments.py]"]
  node_market_storage[("Market data store<br/>[repository.py]")]
end

subgraph group_backend["API and domains"]
  node_api["API composition<br/>[app.py]"]
  node_asgi["ASGI lifecycle<br/>[main.py]"]
  node_storage_service["Storage lifecycle<br/>[service.py]"]
  node_events["Domain events<br/>[events.py]"]
  node_trading_domains["Trading services"]
end

subgraph group_identity["Identity and audit"]
  node_auth["Session service<br/>[session_service.py]"]
  node_sessions_api["Session endpoints<br/>[sessions.py]"]
  node_audit["Audit queries<br/>[query.py]"]
end

subgraph group_planned["Planned capabilities"]
  node_indicators["Indicators"]
  node_alerts["Alerts<br/>[service.py]"]
  node_replay["Replay and backtest<br/>[service.py]"]
  node_scripting["Script sandbox"]
  node_collaboration["Live collaboration"]
end

node_trader(("Trader"))

node_trader -->|"uses"| node_web
node_web -->|"renders"| node_routes
node_web -.->|"REST / WebSocket"| node_api
node_chart -.->|"renders charts"| node_web
node_desktop -.->|"hosts client"| node_web
node_asgi -->|"creates app"| node_api
node_asgi -->|"starts modules"| node_api
node_api -->|"composes modules"| node_ingest
node_ingest -->|"starts scheduler"| node_instrument_refresh
node_instrument_refresh -->|"refreshes instruments"| node_exchange
node_storage_service -.->|"owns tier"| node_market_storage
node_api -->|"composes modules"| node_storage_service
node_api -->|"registers endpoints"| node_sessions_api
node_sessions_api -.->|"uses sessions"| node_auth
node_auth -.->|"persists sessions"| node_market_storage
node_api -->|"supervises modules"| node_trading_domains
node_trader -.->|"analyzes charts"| node_indicators
node_trader -.->|"configures alerts"| node_alerts
node_trader -.->|"tests strategies"| node_replay
node_trader -.->|"writes scripts"| node_scripting
node_trader -.->|"co-edits charts"| node_collaboration

click node_web "https://github.com/basiltt/candleviewer/blob/main/apps/web/src/main.tsx"
click node_routes "https://github.com/basiltt/candleviewer/blob/main/apps/web/src/routes/tree.tsx"
click node_chart "https://github.com/basiltt/candleviewer/blob/main/packages/chart-engine/src/core/handle.ts"
click node_desktop "https://github.com/basiltt/candleviewer/blob/main/apps/desktop/src/main/shellPort.ts"
click node_api "https://github.com/basiltt/candleviewer/blob/main/services/api/candleviewer/app.py"
click node_asgi "https://github.com/basiltt/candleviewer/blob/main/services/api/candleviewer/main.py"
click node_ingest "https://github.com/basiltt/candleviewer/blob/main/services/api/candleviewer/ingestion/service.py"
click node_instrument_refresh "https://github.com/basiltt/candleviewer/blob/main/services/api/candleviewer/ingestion/instruments_refresh.py"
click node_exchange "https://github.com/basiltt/candleviewer/blob/main/services/api/candleviewer/exchange/base/instruments.py"
click node_market_storage "https://github.com/basiltt/candleviewer/blob/main/services/api/candleviewer/storage/questdb/repository.py"
click node_storage_service "https://github.com/basiltt/candleviewer/blob/main/services/api/candleviewer/storage/service.py"
click node_auth "https://github.com/basiltt/candleviewer/blob/main/services/api/candleviewer/auth/session_service.py"
click node_sessions_api "https://github.com/basiltt/candleviewer/blob/main/services/api/candleviewer/api/sessions.py"
click node_audit "https://github.com/basiltt/candleviewer/blob/main/services/api/candleviewer/audit/query.py"
click node_events "https://github.com/basiltt/candleviewer/blob/main/services/api/candleviewer/domain/events.py"
click node_trading_domains "https://github.com/basiltt/candleviewer/tree/main/services/api/candleviewer"
click node_alerts "https://github.com/basiltt/candleviewer/blob/main/services/api/candleviewer/alerts/service.py"
click node_replay "https://github.com/basiltt/candleviewer/blob/main/services/api/candleviewer/replay/service.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_web,node_routes,node_chart,node_desktop toneBlue
class node_ingest,node_instrument_refresh,node_exchange,node_market_storage toneAmber
class node_api,node_asgi,node_storage_service,node_events,node_trading_domains toneMint
class node_auth,node_sessions_api,node_audit toneRose
class node_indicators,node_alerts,node_replay,node_scripting,node_collaboration,node_trader toneIndigo
```

## Components

### Client

- [Web application](https://github.com/basiltt/candleviewer/blob/main/apps/web/src/main.tsx): `apps/web/src/main.tsx`
- [Route tree](https://github.com/basiltt/candleviewer/blob/main/apps/web/src/routes/tree.tsx): `apps/web/src/routes/tree.tsx`
- [Chart engine](https://github.com/basiltt/candleviewer/blob/main/packages/chart-engine/src/core/handle.ts): `packages/chart-engine/src/core/handle.ts`
- [Desktop shell](https://github.com/basiltt/candleviewer/blob/main/apps/desktop/src/main/shellPort.ts): `apps/desktop/src/main/shellPort.ts`

### Market data

- [Feed ingestion](https://github.com/basiltt/candleviewer/blob/main/services/api/candleviewer/ingestion/service.py): `services/api/candleviewer/ingestion/service.py`
- [Instrument refresh](https://github.com/basiltt/candleviewer/blob/main/services/api/candleviewer/ingestion/instruments_refresh.py): `services/api/candleviewer/ingestion/instruments_refresh.py`
- [Exchange adapters](https://github.com/basiltt/candleviewer/blob/main/services/api/candleviewer/exchange/base/instruments.py): `services/api/candleviewer/exchange/base/instruments.py`
- [Market data store](https://github.com/basiltt/candleviewer/blob/main/services/api/candleviewer/storage/questdb/repository.py): `services/api/candleviewer/storage/questdb/repository.py`

### API and domains

- [API composition](https://github.com/basiltt/candleviewer/blob/main/services/api/candleviewer/app.py): `services/api/candleviewer/app.py`
- [ASGI lifecycle](https://github.com/basiltt/candleviewer/blob/main/services/api/candleviewer/main.py): `services/api/candleviewer/main.py`
- [Storage lifecycle](https://github.com/basiltt/candleviewer/blob/main/services/api/candleviewer/storage/service.py): `services/api/candleviewer/storage/service.py`
- [Domain events](https://github.com/basiltt/candleviewer/blob/main/services/api/candleviewer/domain/events.py): `services/api/candleviewer/domain/events.py`
- [Trading services](https://github.com/basiltt/candleviewer/tree/main/services/api/candleviewer): `services/api/candleviewer`

### Identity and audit

- [Session service](https://github.com/basiltt/candleviewer/blob/main/services/api/candleviewer/auth/session_service.py): `services/api/candleviewer/auth/session_service.py`
- [Session endpoints](https://github.com/basiltt/candleviewer/blob/main/services/api/candleviewer/api/sessions.py): `services/api/candleviewer/api/sessions.py`
- [Audit queries](https://github.com/basiltt/candleviewer/blob/main/services/api/candleviewer/audit/query.py): `services/api/candleviewer/audit/query.py`

### Planned capabilities

- **Indicators**
- [Alerts](https://github.com/basiltt/candleviewer/blob/main/services/api/candleviewer/alerts/service.py): `services/api/candleviewer/alerts/service.py`
- [Replay and backtest](https://github.com/basiltt/candleviewer/blob/main/services/api/candleviewer/replay/service.py): `services/api/candleviewer/replay/service.py`
- **Script sandbox**
- **Live collaboration**

### Other components

- **Trader**

## Connections

- Trader → Web application: uses (evidence: `README.md`)
- Web application → Route tree: renders
- Web application → API composition: REST / WebSocket (evidence: `README.md`)
- Chart engine → Web application: renders charts (evidence: `README.md`)
- Desktop shell → Web application: hosts client (evidence: `README.md`)
- ASGI lifecycle → API composition: creates app (evidence: `services/api/candleviewer/main.py`)
- ASGI lifecycle → API composition: starts modules (evidence: `services/api/candleviewer/main.py`)
- API composition → Feed ingestion: composes modules (evidence: `services/api/candleviewer/app.py`)
- Feed ingestion → Instrument refresh: starts scheduler (evidence: `services/api/candleviewer/ingestion/service.py`)
- Instrument refresh → Exchange adapters: refreshes instruments (evidence: `services/api/candleviewer/ingestion/instruments_refresh.py`)
- Storage lifecycle → Market data store: owns tier
- API composition → Storage lifecycle: composes modules (evidence: `services/api/candleviewer/app.py`)
- API composition → Session endpoints: registers endpoints (evidence: `services/api/candleviewer/app.py`)
- Session endpoints → Session service: uses sessions
- Session service → Market data store: persists sessions
- API composition → Trading services: supervises modules (evidence: `services/api/candleviewer/app.py`)
- Trader → Indicators: analyzes charts (evidence: `README.md`)
- Trader → Alerts: configures alerts (evidence: `README.md`)
- Trader → Replay and backtest: tests strategies (evidence: `README.md`)
- Trader → Script sandbox: writes scripts (evidence: `README.md`)
- Trader → Live collaboration: co-edits charts (evidence: `README.md`)
