# appzfx13/marmot architecture

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

## Overview

Marmot is a trading, quantitative research, and backtesting platform. The principal workflow runs from a trader’s web/API request through Django domain and backtest services, into Go worker pools for strategy execution and optimization, with datasets and Redis carrying data and task/progress messages; results are surfaced through charts and telemetry. Separate capabilities include live market feeds, broker execution and webhook reconciliation, risk configuration, AI-assisted analysis, and notifications. Several Go internals and unsampled Django subsystems are represented at their documented directory level; their detailed call paths are not verified here.

Main entry points: [`marmot/urls.py`](https://github.com/appzfx13/marmot/blob/main/marmot/urls.py) (Django domain), [`apps/backtest/services.py`](https://github.com/appzfx13/marmot/blob/main/apps/backtest/services.py) (Backtest services), [`go-app/workers`](https://github.com/appzfx13/marmot/tree/main/go-app/workers) (Go worker pools), [`apps/market/services.py`](https://github.com/appzfx13/marmot/blob/main/apps/market/services.py) (Market services)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Platform and Accounts"]
  node_django["Django domain<br/>[urls.py]"]
  node_api["REST API<br/>[views.py]"]
  node_users[("User accounts<br/>[models.py]")]
  node_admin["Admin operations<br/>[views.py]"]
  node_ws["WebSocket hub<br/>[hub.go]"]
end

subgraph group_research["Research and Backtesting"]
  node_backtest["Backtest services<br/>[services.py]"]
  node_backtestdata[("Backtest models<br/>[models.py]")]
  node_vector["Trade analytics"]
  node_quant["Quant strategies<br/>[quant_engine.go]"]
  node_workers["Go worker pools"]
  node_chart["Chart service<br/>[chart_handler.go]"]
end

subgraph group_trading["Trading and Market Data"]
  node_market["Market services<br/>[services.py]"]
  node_marketmodels[("Market models<br/>[models.py]")]
  node_livefeed["Live feed"]
  node_tradeconfig[("Risk and trade config<br/>[models.py]")]
  node_brokerfactory["Broker selection<br/>[factory.py]"]
  node_dhan["Dhan adapter<br/>[dhan.py]"]
  node_scheduler["Trade scheduler<br/>[scheduler.py]"]
  node_postback["Webhook reconciliation<br/>[services.py]"]
end

subgraph group_infra["Persistence and Messaging"]
  node_parquet[("Parquet datasets")]
  node_redis[("Redis")]
  node_postgres[("PostgreSQL")]
end

subgraph group_signals["Integrations and Alerts"]
  node_ai["AI analysis<br/>[gemini_service.py]"]
  node_notifications["Notifications"]
  node_broker{{"Broker services"}}
end

node_trader(("Trader"))
node_browser(("Web client"))

node_trader -->|"uses"| node_browser
node_browser -->|"HTTP / HTMX"| node_django
node_trader -->|"telemetry"| node_ws
node_django -.->|"routes requests"| node_api
node_django -->|"serves workflows"| node_backtest
node_backtest -->|"stores tasks"| node_backtestdata
node_backtest -->|"reads market data"| node_marketmodels
node_backtest -->|"calls services"| node_market
node_backtest -->|"dispatches tasks"| node_redis
node_redis -->|"dispatches tasks"| node_workers
node_workers -->|"runs strategies"| node_quant
node_workers -->|"reads and writes"| node_parquet
node_workers -->|"publishes progress"| node_redis
node_backtest -.->|"analyzes trades"| node_vector
node_backtest -.->|"requests chart data"| node_chart
node_django -->|"authenticates"| node_users
node_django -->|"serves admin"| node_admin
node_market -->|"reads and writes"| node_marketmodels
node_market -->|"publishes progress"| node_redis
node_livefeed -->|"requests trade book"| node_brokerfactory
node_livefeed -->|"reads settings"| node_tradeconfig
node_livefeed -->|"caches quotes"| node_redis
node_scheduler -->|"reads configuration"| node_tradeconfig
node_scheduler -.->|"selects broker"| node_brokerfactory
node_brokerfactory -->|"creates adapter"| node_dhan
node_brokerfactory -->|"connects broker"| node_broker
node_broker -->|"sends webhooks"| node_postback
node_postback -->|"publishes order events"| node_redis
node_postback -->|"uses account data"| node_tradeconfig
node_ai -->|"supports analysis"| node_market
node_django -.->|"sends alerts"| node_notifications
node_redis -->|"relays stream"| node_ws
node_ws -->|"streams telemetry"| node_browser
node_django -->|"persists domain data"| node_postgres
node_workers -->|"processes datasets"| node_parquet

click node_django "https://github.com/appzfx13/marmot/blob/main/marmot/urls.py"
click node_api "https://github.com/appzfx13/marmot/blob/main/apps/api/views.py"
click node_users "https://github.com/appzfx13/marmot/blob/main/apps/users/models.py"
click node_admin "https://github.com/appzfx13/marmot/blob/main/apps/admins/views.py"
click node_backtest "https://github.com/appzfx13/marmot/blob/main/apps/backtest/services.py"
click node_backtestdata "https://github.com/appzfx13/marmot/blob/main/apps/backtest/models.py"
click node_vector "https://github.com/appzfx13/marmot/blob/main/apps/backtest/trade_vector_engine.py"
click node_quant "https://github.com/appzfx13/marmot/blob/main/go-app/strategies/quant_engine.go"
click node_workers "https://github.com/appzfx13/marmot/tree/main/go-app/workers"
click node_chart "https://github.com/appzfx13/marmot/blob/main/go-app/services/chart_handler.go"
click node_market "https://github.com/appzfx13/marmot/blob/main/apps/market/services.py"
click node_marketmodels "https://github.com/appzfx13/marmot/blob/main/apps/market/models.py"
click node_livefeed "https://github.com/appzfx13/marmot/blob/main/apps/common/services/live_feed_service.py"
click node_tradeconfig "https://github.com/appzfx13/marmot/blob/main/apps/trade_config/models.py"
click node_brokerfactory "https://github.com/appzfx13/marmot/blob/main/apps/trade_core/brokers/factory.py"
click node_dhan "https://github.com/appzfx13/marmot/blob/main/apps/trade_core/brokers/dhan.py"
click node_scheduler "https://github.com/appzfx13/marmot/blob/main/apps/trade_core/scheduler.py"
click node_postback "https://github.com/appzfx13/marmot/blob/main/apps/postback/services.py"
click node_parquet "https://github.com/appzfx13/marmot/tree/main/go-app/parquet"
click node_ai "https://github.com/appzfx13/marmot/blob/main/apps/common/services/gemini_service.py"
click node_notifications "https://github.com/appzfx13/marmot/tree/main/apps/notifications/services"
click node_ws "https://github.com/appzfx13/marmot/blob/main/go-app/ws/hub.go"

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_django,node_api,node_users,node_admin,node_ws,node_browser toneBlue
class node_backtest,node_backtestdata,node_vector,node_quant,node_workers,node_chart toneAmber
class node_market,node_marketmodels,node_livefeed,node_tradeconfig,node_brokerfactory,node_dhan,node_scheduler,node_postback toneMint
class node_parquet,node_redis,node_postgres toneRose
class node_ai,node_notifications,node_broker,node_trader toneIndigo
```

## Components

### Platform and Accounts

- [Django domain](https://github.com/appzfx13/marmot/blob/main/marmot/urls.py): `marmot/urls.py`
- [REST API](https://github.com/appzfx13/marmot/blob/main/apps/api/views.py): `apps/api/views.py`
- [User accounts](https://github.com/appzfx13/marmot/blob/main/apps/users/models.py): `apps/users/models.py`
- [Admin operations](https://github.com/appzfx13/marmot/blob/main/apps/admins/views.py): `apps/admins/views.py`
- [WebSocket hub](https://github.com/appzfx13/marmot/blob/main/go-app/ws/hub.go): `go-app/ws/hub.go`

### Research and Backtesting

- [Backtest services](https://github.com/appzfx13/marmot/blob/main/apps/backtest/services.py): `apps/backtest/services.py`
- [Backtest models](https://github.com/appzfx13/marmot/blob/main/apps/backtest/models.py): `apps/backtest/models.py`
- [Trade analytics](https://github.com/appzfx13/marmot/blob/main/apps/backtest/trade_vector_engine.py): `apps/backtest/trade_vector_engine.py`
- [Quant strategies](https://github.com/appzfx13/marmot/blob/main/go-app/strategies/quant_engine.go): `go-app/strategies/quant_engine.go`
- [Go worker pools](https://github.com/appzfx13/marmot/tree/main/go-app/workers): `go-app/workers`
- [Chart service](https://github.com/appzfx13/marmot/blob/main/go-app/services/chart_handler.go): `go-app/services/chart_handler.go`

### Trading and Market Data

- [Market services](https://github.com/appzfx13/marmot/blob/main/apps/market/services.py): `apps/market/services.py`
- [Market models](https://github.com/appzfx13/marmot/blob/main/apps/market/models.py): `apps/market/models.py`
- [Live feed](https://github.com/appzfx13/marmot/blob/main/apps/common/services/live_feed_service.py): `apps/common/services/live_feed_service.py`
- [Risk and trade config](https://github.com/appzfx13/marmot/blob/main/apps/trade_config/models.py): `apps/trade_config/models.py`
- [Broker selection](https://github.com/appzfx13/marmot/blob/main/apps/trade_core/brokers/factory.py): `apps/trade_core/brokers/factory.py`
- [Dhan adapter](https://github.com/appzfx13/marmot/blob/main/apps/trade_core/brokers/dhan.py): `apps/trade_core/brokers/dhan.py`
- [Trade scheduler](https://github.com/appzfx13/marmot/blob/main/apps/trade_core/scheduler.py): `apps/trade_core/scheduler.py`
- [Webhook reconciliation](https://github.com/appzfx13/marmot/blob/main/apps/postback/services.py): `apps/postback/services.py`

### Persistence and Messaging

- [Parquet datasets](https://github.com/appzfx13/marmot/tree/main/go-app/parquet): `go-app/parquet`
- **Redis**
- **PostgreSQL**

### Integrations and Alerts

- [AI analysis](https://github.com/appzfx13/marmot/blob/main/apps/common/services/gemini_service.py): `apps/common/services/gemini_service.py`
- [Notifications](https://github.com/appzfx13/marmot/tree/main/apps/notifications/services): `apps/notifications/services`
- **Broker services**

### Other components

- **Trader**
- **Web client**

## Connections

- Trader → Web client: uses
- Web client → Django domain: HTTP / HTMX
- Trader → WebSocket hub: telemetry
- Django domain → REST API: routes requests
- Django domain → Backtest services: serves workflows
- Backtest services → Backtest models: stores tasks (evidence: `apps/backtest/services.py`)
- Backtest services → Market models: reads market data (evidence: `apps/backtest/services.py`)
- Backtest services → Market services: calls services (evidence: `apps/backtest/services.py`)
- Backtest services → Redis: dispatches tasks
- Redis → Go worker pools: dispatches tasks
- Go worker pools → Quant strategies: runs strategies
- Go worker pools → Parquet datasets: reads and writes
- Go worker pools → Redis: publishes progress
- Backtest services → Trade analytics: analyzes trades
- Backtest services → Chart service: requests chart data
- Django domain → User accounts: authenticates
- Django domain → Admin operations: serves admin
- Market services → Market models: reads and writes (evidence: `apps/market/services.py`)
- Market services → Redis: publishes progress (evidence: `apps/market/services.py`)
- Live feed → Broker selection: requests trade book (evidence: `apps/common/services/live_feed_service.py`)
- Live feed → Risk and trade config: reads settings (evidence: `apps/common/services/live_feed_service.py`)
- Live feed → Redis: caches quotes (evidence: `apps/common/services/live_feed_service.py`)
- Trade scheduler → Risk and trade config: reads configuration (evidence: `apps/trade_core/scheduler.py`)
- Trade scheduler → Broker selection: selects broker
- Broker selection → Dhan adapter: creates adapter (evidence: `apps/trade_core/brokers/factory.py`)
- Broker selection → Broker services: connects broker
- Broker services → Webhook reconciliation: sends webhooks
- Webhook reconciliation → Redis: publishes order events (evidence: `apps/postback/services.py`)
- Webhook reconciliation → Risk and trade config: uses account data (evidence: `apps/postback/services.py`)
- AI analysis → Market services: supports analysis (evidence: `apps/market/services.py`)
- Django domain → Notifications: sends alerts
- Redis → WebSocket hub: relays stream
- WebSocket hub → Web client: streams telemetry
- Django domain → PostgreSQL: persists domain data
- Go worker pools → Parquet datasets: processes datasets
