# agutinbaigo28/trading-backtest-kit architecture

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

- Interactive diagram: https://gitdiagram.com/agutinbaigo28/trading-backtest-kit
- Repository: https://github.com/agutinbaigo28/trading-backtest-kit

## Overview

Backtest Kit is a TypeScript engine for researching and running trading strategies in backtest, paper, and live modes, with a CLI and frontend for operation and inspection. The primary workflow is to configure exchange, frame, and strategy schemas, run a mode against market data, evaluate signals and manage positions, then persist and emit results. The README documents these capabilities; source excerpts additionally show strategy execution context, event emitters, and storage behavior. Some subsystems are represented by tree paths and README claims because their implementation was not sampled.

Main entry points: [`src/client/ClientStrategy.ts`](https://github.com/agutinbaigo28/trading-backtest-kit/blob/master/src/client/ClientStrategy.ts) (Strategy client), [`cli/src/main/main.ts`](https://github.com/agutinbaigo28/trading-backtest-kit/blob/master/cli/src/main/main.ts) (CLI entry), [`src/classes/Storage.ts`](https://github.com/agutinbaigo28/trading-backtest-kit/blob/master/src/classes/Storage.ts) (Signal storage), [`packages/mongo/src/lib/services/db/StorageDbService.ts`](https://github.com/agutinbaigo28/trading-backtest-kit/blob/master/packages/mongo/src/lib/services/db/StorageDbService.ts) (Mongo storage)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_engine["Trading engine"]
  node_schemas["Strategy schemas<br/>[index.ts]"]
  node_exchange["Exchange data<br/>[ClientExchange.ts]"]
  node_strategy["Strategy client<br/>[ClientStrategy.ts]"]
  node_time_context["Execution context"]
  node_method_context["Schema context"]
  node_events["Trading events<br/>[emitters.ts]"]
end

subgraph group_runtime["Execution modes"]
  node_backtest["Backtest runner"]
  node_live["Live runner<br/>[LiveMainService.ts]"]
  node_paper["Paper runner"]
  node_walker["Walker runner"]
end

subgraph group_operations["CLI and operations"]
  node_cli["CLI entry<br/>[main.ts]"]
  node_telegram["Telegram notifications"]
end

subgraph group_persistence["Persistence"]
  node_storage[("Signal storage<br/>[Storage.ts]")]
  node_mongo_store[("Mongo storage")]
  node_mongo_cache["Mongo cache"]
  node_pg_store[("Postgres storage")]
  node_pg_cache["Postgres cache"]
end

subgraph group_frontend["Frontend"]
  node_dashboard["Trading dashboard<br/>[App.tsx]"]
  node_dashboard_params["Dashboard parameters<br/>[params.ts]"]
  node_notification_detail["Signal inspection"]
end

node_developer(("Strategy developer"))
node_exchange_service["Exchange service"]
node_mongo[("MongoDB")]
node_postgres[("PostgreSQL")]
node_operator(("Trader"))

node_developer -->|"registers"| node_schemas
node_schemas -->|"configures"| node_exchange
node_cli -.->|"routes"| node_backtest
node_cli -.->|"routes"| node_live
node_cli -.->|"routes"| node_paper
node_cli -.->|"routes"| node_walker
node_backtest -->|"runs"| node_strategy
node_live -->|"runs"| node_strategy
node_paper -.->|"runs"| node_strategy
node_walker -.->|"evaluates"| node_strategy
node_strategy -->|"fetches candles"| node_exchange
node_strategy -->|"uses time"| node_time_context
node_strategy -->|"uses schemas"| node_method_context
node_strategy -->|"persists signals"| node_storage
node_strategy -->|"emits events"| node_events
node_storage -.->|"adapts storage"| node_mongo_store
node_storage -.->|"adapts storage"| node_pg_store
node_mongo_store -->|"updates cache"| node_mongo_cache
node_pg_store -->|"updates cache"| node_pg_cache
node_mongo_store -->|"reads and writes"| node_mongo
node_pg_store -->|"reads and writes"| node_postgres
node_operator -->|"runs commands"| node_cli
node_operator -.->|"inspects results"| node_dashboard
node_dashboard -.->|"uses settings"| node_dashboard_params
node_notification_detail -->|"requests candles"| node_exchange_service
node_notification_detail -.->|"presents details"| node_operator
node_cli -.->|"configures notifications"| node_telegram

click node_cli "https://github.com/agutinbaigo28/trading-backtest-kit/blob/master/cli/src/main/main.ts"
click node_schemas "https://github.com/agutinbaigo28/trading-backtest-kit/blob/master/src/index.ts"
click node_exchange "https://github.com/agutinbaigo28/trading-backtest-kit/blob/master/src/client/ClientExchange.ts"
click node_strategy "https://github.com/agutinbaigo28/trading-backtest-kit/blob/master/src/client/ClientStrategy.ts"
click node_time_context "https://github.com/agutinbaigo28/trading-backtest-kit/blob/master/src/lib/services/context/ExecutionContextService.ts"
click node_method_context "https://github.com/agutinbaigo28/trading-backtest-kit/blob/master/src/lib/services/context/MethodContextService.ts"
click node_events "https://github.com/agutinbaigo28/trading-backtest-kit/blob/master/cli/src/config/emitters.ts"
click node_backtest "https://github.com/agutinbaigo28/trading-backtest-kit/blob/master/cli/src/lib/services/main/BacktestMainService.ts"
click node_live "https://github.com/agutinbaigo28/trading-backtest-kit/blob/master/cli/src/lib/services/main/LiveMainService.ts"
click node_paper "https://github.com/agutinbaigo28/trading-backtest-kit/blob/master/cli/src/lib/services/main/PaperMainService.ts"
click node_walker "https://github.com/agutinbaigo28/trading-backtest-kit/blob/master/cli/src/lib/services/main/WalkerMainService.ts"
click node_storage "https://github.com/agutinbaigo28/trading-backtest-kit/blob/master/src/classes/Storage.ts"
click node_mongo_store "https://github.com/agutinbaigo28/trading-backtest-kit/blob/master/packages/mongo/src/lib/services/db/StorageDbService.ts"
click node_mongo_cache "https://github.com/agutinbaigo28/trading-backtest-kit/blob/master/packages/mongo/src/lib/services/cache/StorageCacheService.ts"
click node_pg_store "https://github.com/agutinbaigo28/trading-backtest-kit/blob/master/packages/pg/src/lib/services/db/StorageDbService.ts"
click node_pg_cache "https://github.com/agutinbaigo28/trading-backtest-kit/blob/master/packages/pg/src/lib/services/cache/StorageCacheService.ts"
click node_dashboard "https://github.com/agutinbaigo28/trading-backtest-kit/blob/master/packages/front/modules/frontend/src/components/App.tsx"
click node_dashboard_params "https://github.com/agutinbaigo28/trading-backtest-kit/blob/master/packages/front/modules/frontend/src/config/params.ts"
click node_notification_detail "https://github.com/agutinbaigo28/trading-backtest-kit/blob/master/packages/front/modules/frontend/src/hooks/useAverageBuyCommitView/useAverageBuyCommitView.tsx"
click node_telegram "https://github.com/agutinbaigo28/trading-backtest-kit/blob/master/cli/src/lib/services/api/TelegramApiService.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_schemas,node_exchange,node_strategy,node_time_context,node_method_context,node_events toneBlue
class node_backtest,node_live,node_paper,node_walker,node_mongo,node_postgres toneAmber
class node_cli,node_telegram toneMint
class node_storage,node_mongo_store,node_mongo_cache,node_pg_store,node_pg_cache toneRose
class node_dashboard,node_dashboard_params,node_notification_detail,node_developer,node_exchange_service,node_operator toneIndigo
```

## Components

### Trading engine

- [Strategy schemas](https://github.com/agutinbaigo28/trading-backtest-kit/blob/master/src/index.ts): `src/index.ts`
- [Exchange data](https://github.com/agutinbaigo28/trading-backtest-kit/blob/master/src/client/ClientExchange.ts): `src/client/ClientExchange.ts`
- [Strategy client](https://github.com/agutinbaigo28/trading-backtest-kit/blob/master/src/client/ClientStrategy.ts): `src/client/ClientStrategy.ts`
- [Execution context](https://github.com/agutinbaigo28/trading-backtest-kit/blob/master/src/lib/services/context/ExecutionContextService.ts): `src/lib/services/context/ExecutionContextService.ts`
- [Schema context](https://github.com/agutinbaigo28/trading-backtest-kit/blob/master/src/lib/services/context/MethodContextService.ts): `src/lib/services/context/MethodContextService.ts`
- [Trading events](https://github.com/agutinbaigo28/trading-backtest-kit/blob/master/cli/src/config/emitters.ts): `cli/src/config/emitters.ts`

### Execution modes

- [Backtest runner](https://github.com/agutinbaigo28/trading-backtest-kit/blob/master/cli/src/lib/services/main/BacktestMainService.ts): `cli/src/lib/services/main/BacktestMainService.ts`
- [Live runner](https://github.com/agutinbaigo28/trading-backtest-kit/blob/master/cli/src/lib/services/main/LiveMainService.ts): `cli/src/lib/services/main/LiveMainService.ts`
- [Paper runner](https://github.com/agutinbaigo28/trading-backtest-kit/blob/master/cli/src/lib/services/main/PaperMainService.ts): `cli/src/lib/services/main/PaperMainService.ts`
- [Walker runner](https://github.com/agutinbaigo28/trading-backtest-kit/blob/master/cli/src/lib/services/main/WalkerMainService.ts): `cli/src/lib/services/main/WalkerMainService.ts`

### CLI and operations

- [CLI entry](https://github.com/agutinbaigo28/trading-backtest-kit/blob/master/cli/src/main/main.ts): `cli/src/main/main.ts`
- [Telegram notifications](https://github.com/agutinbaigo28/trading-backtest-kit/blob/master/cli/src/lib/services/api/TelegramApiService.ts): `cli/src/lib/services/api/TelegramApiService.ts`

### Persistence

- [Signal storage](https://github.com/agutinbaigo28/trading-backtest-kit/blob/master/src/classes/Storage.ts): `src/classes/Storage.ts`
- [Mongo storage](https://github.com/agutinbaigo28/trading-backtest-kit/blob/master/packages/mongo/src/lib/services/db/StorageDbService.ts): `packages/mongo/src/lib/services/db/StorageDbService.ts`
- [Mongo cache](https://github.com/agutinbaigo28/trading-backtest-kit/blob/master/packages/mongo/src/lib/services/cache/StorageCacheService.ts): `packages/mongo/src/lib/services/cache/StorageCacheService.ts`
- [Postgres storage](https://github.com/agutinbaigo28/trading-backtest-kit/blob/master/packages/pg/src/lib/services/db/StorageDbService.ts): `packages/pg/src/lib/services/db/StorageDbService.ts`
- [Postgres cache](https://github.com/agutinbaigo28/trading-backtest-kit/blob/master/packages/pg/src/lib/services/cache/StorageCacheService.ts): `packages/pg/src/lib/services/cache/StorageCacheService.ts`

### Frontend

- [Trading dashboard](https://github.com/agutinbaigo28/trading-backtest-kit/blob/master/packages/front/modules/frontend/src/components/App.tsx): `packages/front/modules/frontend/src/components/App.tsx`
- [Dashboard parameters](https://github.com/agutinbaigo28/trading-backtest-kit/blob/master/packages/front/modules/frontend/src/config/params.ts): `packages/front/modules/frontend/src/config/params.ts`
- [Signal inspection](https://github.com/agutinbaigo28/trading-backtest-kit/blob/master/packages/front/modules/frontend/src/hooks/useAverageBuyCommitView/useAverageBuyCommitView.tsx): `packages/front/modules/frontend/src/hooks/useAverageBuyCommitView/useAverageBuyCommitView.tsx`

### Other components

- **Strategy developer**
- **Exchange service**
- **MongoDB**
- **PostgreSQL**
- **Trader**

## Connections

- Strategy developer → Strategy schemas: registers
- Strategy schemas → Exchange data: configures
- CLI entry → Backtest runner: routes
- CLI entry → Live runner: routes
- CLI entry → Paper runner: routes
- CLI entry → Walker runner: routes
- Backtest runner → Strategy client: runs
- Live runner → Strategy client: runs
- Paper runner → Strategy client: runs
- Walker runner → Strategy client: evaluates
- Strategy client → Exchange data: fetches candles
- Strategy client → Execution context: uses time (evidence: `src/client/ClientStrategy.ts`)
- Strategy client → Schema context: uses schemas
- Strategy client → Signal storage: persists signals
- Strategy client → Trading events: emits events
- Signal storage → Mongo storage: adapts storage
- Signal storage → Postgres storage: adapts storage
- Mongo storage → Mongo cache: updates cache (evidence: `packages/mongo/src/lib/services/db/StorageDbService.ts`)
- Postgres storage → Postgres cache: updates cache (evidence: `packages/pg/src/lib/services/db/StorageDbService.ts`)
- Mongo storage → MongoDB: reads and writes (evidence: `packages/mongo/src/lib/services/db/StorageDbService.ts`)
- Postgres storage → PostgreSQL: reads and writes (evidence: `packages/pg/src/lib/services/db/StorageDbService.ts`)
- Trader → CLI entry: runs commands
- Trader → Trading dashboard: inspects results
- Trading dashboard → Dashboard parameters: uses settings
- Signal inspection → Exchange service: requests candles (evidence: `packages/front/modules/frontend/src/hooks/useAverageBuyCommitView/useAverageBuyCommitView.tsx`)
- Signal inspection → Trader: presents details
- CLI entry → Telegram notifications: configures notifications
