# munquantsociety/mqs-backtest-visualizer architecture

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

- Interactive diagram: https://gitdiagram.com/munquantsociety/mqs-backtest-visualizer
- Repository: https://github.com/munquantsociety/mqs-backtest-visualizer

## Overview

MQS Backtest Visualizer is a backend for submitting quantitative backtests and viewing completed results. The principal workflow is a member submitting a run through the HTTP API; a job manager dispatches execution to a process pool, the engine runs a strategy against market data and produces a report, and successful reports are persisted for retrieval. Separate capabilities include strategy validation and storage, market context, and report exports. The README documents these capabilities, but several route and worker implementations were not sampled; uncertain internal links are omitted or marked unverified.

Main entry points: [`src/api/router.py`](https://github.com/munquantsociety/mqs-backtest-visualizer/blob/main/src/api/router.py) (API router), [`engine/core/backtest_engine.py`](https://github.com/munquantsociety/mqs-backtest-visualizer/blob/main/engine/core/backtest_engine.py) (Backtest engine), [`src/workers/job_manager.py`](https://github.com/munquantsociety/mqs-backtest-visualizer/blob/main/src/workers/job_manager.py) (Job manager), [`src/services/market_context.py`](https://github.com/munquantsociety/mqs-backtest-visualizer/blob/main/src/services/market_context.py) (Market context)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["HTTP API"]
  node_api_router["API router<br/>[router.py]"]
  node_backtest_routes["Backtest routes<br/>[backtests.py]"]
  node_strategy_routes["Strategy routes<br/>[strategies.py]"]
  node_context_routes["Context routes<br/>[market_context.py]"]
end

subgraph group_jobs["Run orchestration"]
  node_job_manager["Job manager<br/>[job_manager.py]"]
  node_run_worker["Run worker<br/>[run_job.py]"]
  node_backtest_service["Backtest service<br/>[backtests.py]"]
end

subgraph group_engine["Backtest engine"]
  node_engine_core["Backtest engine<br/>[backtest_engine.py]"]
  node_strategy["Strategy runtime<br/>[strategy.py]"]
  node_reporting["Report analytics<br/>[reporting.py]"]
end

subgraph group_data["Data and persistence"]
  node_market_data["Market data<br/>[fmp.py]"]
  node_app_database[("Application database<br/>[engine.py]")]
  node_report_storage[("Completed reports<br/>[reports.py]")]
  node_news_database[("News database<br/>[engine.py]")]
end

subgraph group_capabilities["Product capabilities"]
  node_strategy_validation["Strategy validation"]
  node_strategy_store["Strategy storage<br/>[strategy_store.py]"]
  node_market_context["Market context<br/>[market_context.py]"]
  node_exports["Report exports<br/>[report_exports.py]"]
end

node_member(("Member"))
node_frontend["Frontend"]

node_member -->|"views results"| node_frontend
node_frontend -->|"sends requests"| node_api_router
node_api_router -->|"mounts"| node_backtest_routes
node_api_router -->|"mounts"| node_strategy_routes
node_api_router -->|"mounts"| node_context_routes
node_backtest_routes -.->|"handles submission"| node_backtest_service
node_backtest_service -.->|"registers runs"| node_job_manager
node_job_manager -.->|"dispatches work"| node_run_worker
node_run_worker -.->|"executes run"| node_engine_core
node_engine_core -->|"runs strategy"| node_strategy
node_engine_core -->|"loads history"| node_market_data
node_engine_core -->|"builds report"| node_reporting
node_job_manager -->|"saves success"| node_report_storage
node_report_storage -.->|"persists reports"| node_app_database
node_strategy_routes -.->|"validates submissions"| node_strategy_validation
node_strategy_validation -.->|"uses storage"| node_strategy_store
node_context_routes -->|"serves context"| node_market_context
node_market_context -->|"reads news"| node_news_database
node_market_context -->|"reads prices"| node_app_database
node_exports -.->|"exports reports"| node_report_storage

click node_api_router "https://github.com/munquantsociety/mqs-backtest-visualizer/blob/main/src/api/router.py"
click node_backtest_routes "https://github.com/munquantsociety/mqs-backtest-visualizer/blob/main/src/api/routes/backtests.py"
click node_strategy_routes "https://github.com/munquantsociety/mqs-backtest-visualizer/blob/main/src/api/routes/strategies.py"
click node_context_routes "https://github.com/munquantsociety/mqs-backtest-visualizer/blob/main/src/api/routes/market_context.py"
click node_job_manager "https://github.com/munquantsociety/mqs-backtest-visualizer/blob/main/src/workers/job_manager.py"
click node_run_worker "https://github.com/munquantsociety/mqs-backtest-visualizer/blob/main/src/workers/run_job.py"
click node_backtest_service "https://github.com/munquantsociety/mqs-backtest-visualizer/blob/main/src/services/backtests.py"
click node_engine_core "https://github.com/munquantsociety/mqs-backtest-visualizer/blob/main/engine/core/backtest_engine.py"
click node_strategy "https://github.com/munquantsociety/mqs-backtest-visualizer/blob/main/engine/strategies/portfolio_BASE/strategy.py"
click node_reporting "https://github.com/munquantsociety/mqs-backtest-visualizer/blob/main/engine/analytics/reporting.py"
click node_market_data "https://github.com/munquantsociety/mqs-backtest-visualizer/blob/main/engine/data/fmp.py"
click node_app_database "https://github.com/munquantsociety/mqs-backtest-visualizer/blob/main/src/db/engine.py"
click node_report_storage "https://github.com/munquantsociety/mqs-backtest-visualizer/blob/main/src/repositories/reports.py"
click node_strategy_validation "https://github.com/munquantsociety/mqs-backtest-visualizer/tree/main/src/services/strategy_validation"
click node_strategy_store "https://github.com/munquantsociety/mqs-backtest-visualizer/blob/main/src/integrations/strategy_store.py"
click node_market_context "https://github.com/munquantsociety/mqs-backtest-visualizer/blob/main/src/services/market_context.py"
click node_news_database "https://github.com/munquantsociety/mqs-backtest-visualizer/blob/main/src/db/engine.py"
click node_exports "https://github.com/munquantsociety/mqs-backtest-visualizer/blob/main/src/services/report_exports.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_api_router,node_backtest_routes,node_strategy_routes,node_context_routes,node_frontend toneBlue
class node_job_manager,node_run_worker,node_backtest_service toneAmber
class node_engine_core,node_strategy,node_reporting toneMint
class node_market_data,node_app_database,node_report_storage,node_news_database toneRose
class node_strategy_validation,node_strategy_store,node_market_context,node_exports,node_member toneIndigo
```

## Components

### HTTP API

- [API router](https://github.com/munquantsociety/mqs-backtest-visualizer/blob/main/src/api/router.py): `src/api/router.py`
- [Backtest routes](https://github.com/munquantsociety/mqs-backtest-visualizer/blob/main/src/api/routes/backtests.py): `src/api/routes/backtests.py`
- [Strategy routes](https://github.com/munquantsociety/mqs-backtest-visualizer/blob/main/src/api/routes/strategies.py): `src/api/routes/strategies.py`
- [Context routes](https://github.com/munquantsociety/mqs-backtest-visualizer/blob/main/src/api/routes/market_context.py): `src/api/routes/market_context.py`

### Run orchestration

- [Job manager](https://github.com/munquantsociety/mqs-backtest-visualizer/blob/main/src/workers/job_manager.py): `src/workers/job_manager.py`
- [Run worker](https://github.com/munquantsociety/mqs-backtest-visualizer/blob/main/src/workers/run_job.py): `src/workers/run_job.py`
- [Backtest service](https://github.com/munquantsociety/mqs-backtest-visualizer/blob/main/src/services/backtests.py): `src/services/backtests.py`

### Backtest engine

- [Backtest engine](https://github.com/munquantsociety/mqs-backtest-visualizer/blob/main/engine/core/backtest_engine.py): `engine/core/backtest_engine.py`
- [Strategy runtime](https://github.com/munquantsociety/mqs-backtest-visualizer/blob/main/engine/strategies/portfolio_BASE/strategy.py): `engine/strategies/portfolio_BASE/strategy.py`
- [Report analytics](https://github.com/munquantsociety/mqs-backtest-visualizer/blob/main/engine/analytics/reporting.py): `engine/analytics/reporting.py`

### Data and persistence

- [Market data](https://github.com/munquantsociety/mqs-backtest-visualizer/blob/main/engine/data/fmp.py): `engine/data/fmp.py`
- [Application database](https://github.com/munquantsociety/mqs-backtest-visualizer/blob/main/src/db/engine.py): `src/db/engine.py`
- [Completed reports](https://github.com/munquantsociety/mqs-backtest-visualizer/blob/main/src/repositories/reports.py): `src/repositories/reports.py`
- [News database](https://github.com/munquantsociety/mqs-backtest-visualizer/blob/main/src/db/engine.py): `src/db/engine.py`

### Product capabilities

- [Strategy validation](https://github.com/munquantsociety/mqs-backtest-visualizer/tree/main/src/services/strategy_validation): `src/services/strategy_validation`
- [Strategy storage](https://github.com/munquantsociety/mqs-backtest-visualizer/blob/main/src/integrations/strategy_store.py): `src/integrations/strategy_store.py`
- [Market context](https://github.com/munquantsociety/mqs-backtest-visualizer/blob/main/src/services/market_context.py): `src/services/market_context.py`
- [Report exports](https://github.com/munquantsociety/mqs-backtest-visualizer/blob/main/src/services/report_exports.py): `src/services/report_exports.py`

### Other components

- **Member**
- **Frontend**

## Connections

- Member → Frontend: views results (evidence: `README.md`)
- Frontend → API router: sends requests (evidence: `src/api/router.py`)
- API router → Backtest routes: mounts (evidence: `src/api/router.py`)
- API router → Strategy routes: mounts (evidence: `src/api/router.py`)
- API router → Context routes: mounts (evidence: `src/api/router.py`)
- Backtest routes → Backtest service: handles submission
- Backtest service → Job manager: registers runs
- Job manager → Run worker: dispatches work
- Run worker → Backtest engine: executes run
- Backtest engine → Strategy runtime: runs strategy (evidence: `engine/core/backtest_engine.py`)
- Backtest engine → Market data: loads history (evidence: `engine/core/backtest_engine.py`)
- Backtest engine → Report analytics: builds report (evidence: `engine/core/backtest_engine.py`)
- Job manager → Completed reports: saves success (evidence: `src/workers/job_manager.py`)
- Completed reports → Application database: persists reports
- Strategy routes → Strategy validation: validates submissions
- Strategy validation → Strategy storage: uses storage
- Context routes → Market context: serves context (evidence: `src/api/routes/market_context.py`)
- Market context → News database: reads news (evidence: `src/services/market_context.py`)
- Market context → Application database: reads prices (evidence: `src/services/market_context.py`)
- Report exports → Completed reports: exports reports
