# m0nk4489/damus architecture

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

- Interactive diagram: https://gitdiagram.com/m0nk4489/damus
- Repository: https://github.com/m0nk4489/damus

## Overview

Damus is a local desktop workbench for market-data research, forecasting experiments, visual analysis, and paper or explicitly armed live trading. Its main workflow is to import or download bars into a local catalog, configure and queue an experiment, run forecasting and backtesting in a separate worker, then inspect results. A separate forward-trading workflow uses a selected feed and execution adapter. The README documents provider breadth and analysis capabilities; sampled excerpts do not expose every internal call, so uncertain wiring is omitted.

Main entry points: [`damus/controller.py`](https://github.com/m0nk4489/damus/blob/main/damus/controller.py) (Application services), [`damus/ui/window.py`](https://github.com/m0nk4489/damus/blob/main/damus/ui/window.py) (Workbench UI), [`damus/worker.py`](https://github.com/m0nk4489/damus/blob/main/damus/worker.py) (Experiment worker), [`damus/providers.py`](https://github.com/m0nk4489/damus/blob/main/damus/providers.py) (Provider adapters)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_desktop["Desktop workbench"]
  node_ui["Workbench UI<br/>[window.py]"]
  node_catalog_ui["Data library<br/>[data_hub.py]"]
  node_trade_ui["Trading controls"]
  node_controller["Application services<br/>[controller.py]"]
end

subgraph group_data["Market data"]
  node_download_worker["Download process<br/>[download_worker.py]"]
  node_providers["Provider adapters<br/>[providers.py]"]
  node_marketdata["Historical data<br/>[marketdata.py]"]
  node_feeds["Quote feeds<br/>[feeds.py]"]
  node_store[("Local catalog<br/>[storage.py]")]
end

subgraph group_research["Forecast research"]
  node_experiment_ui["Experiment setup"]
  node_jobs["Job coordination<br/>[jobs.py]"]
  node_worker["Experiment worker<br/>[worker.py]"]
  node_engine["Forecast and backtest<br/>[engine.py]"]
  node_models["Model adapters"]
  node_analysis_ui["Charts and analysis<br/>[charts.py]"]
  node_chart_data["Chart preparation<br/>[chart_data.py]"]
end

subgraph group_trading["Trading and resources"]
  node_resources["Resource policy<br/>[resources.py]"]
  node_paper["Forward session<br/>[paper.py]"]
  node_execution["Execution adapters"]
end

node_user(("Researcher"))
node_data_services{{"Market data services"}}
node_broker_services{{"Broker or exchange"}}

node_user -->|"uses"| node_ui
node_ui -->|"opens library"| node_catalog_ui
node_ui -->|"configures runs"| node_experiment_ui
node_ui -->|"inspects results"| node_analysis_ui
node_ui -->|"controls trading"| node_trade_ui
node_catalog_ui -->|"requests data"| node_controller
node_controller -->|"isolates download"| node_download_worker
node_download_worker -->|"requests bars"| node_controller
node_controller -->|"selects source"| node_providers
node_providers -->|"provides history"| node_marketdata
node_providers -.->|"requests bars"| node_data_services
node_controller -->|"registers datasets"| node_store
node_controller -->|"queues experiment"| node_jobs
node_jobs -->|"dispatches job"| node_worker
node_worker -->|"runs experiment"| node_engine
node_worker -->|"configures limits"| node_resources
node_engine -->|"fits and predicts"| node_models
node_worker -->|"writes results"| node_store
node_analysis_ui -->|"requests results"| node_controller
node_analysis_ui -->|"prepares plots"| node_chart_data
node_trade_ui -->|"controls session"| node_controller
node_controller -->|"starts session"| node_paper
node_paper -->|"reads quotes"| node_feeds
node_feeds -.->|"polls quotes"| node_data_services
node_paper -->|"routes actions"| node_execution
node_execution -.->|"places orders"| node_broker_services
node_controller -->|"selects broker"| node_execution

click node_ui "https://github.com/m0nk4489/damus/blob/main/damus/ui/window.py"
click node_catalog_ui "https://github.com/m0nk4489/damus/blob/main/damus/ui/data_hub.py"
click node_trade_ui "https://github.com/m0nk4489/damus/blob/main/damus/ui/trading_controls.py"
click node_controller "https://github.com/m0nk4489/damus/blob/main/damus/controller.py"
click node_download_worker "https://github.com/m0nk4489/damus/blob/main/damus/download_worker.py"
click node_providers "https://github.com/m0nk4489/damus/blob/main/damus/providers.py"
click node_marketdata "https://github.com/m0nk4489/damus/blob/main/damus/marketdata.py"
click node_feeds "https://github.com/m0nk4489/damus/blob/main/damus/feeds.py"
click node_store "https://github.com/m0nk4489/damus/blob/main/damus/storage.py"
click node_experiment_ui "https://github.com/m0nk4489/damus/blob/main/damus/ui/experiment_inputs.py"
click node_jobs "https://github.com/m0nk4489/damus/blob/main/damus/jobs.py"
click node_worker "https://github.com/m0nk4489/damus/blob/main/damus/worker.py"
click node_engine "https://github.com/m0nk4489/damus/blob/main/damus/engine.py"
click node_models "https://github.com/m0nk4489/damus/tree/main/damus/models"
click node_analysis_ui "https://github.com/m0nk4489/damus/blob/main/damus/ui/charts.py"
click node_chart_data "https://github.com/m0nk4489/damus/blob/main/damus/chart_data.py"
click node_resources "https://github.com/m0nk4489/damus/blob/main/damus/resources.py"
click node_paper "https://github.com/m0nk4489/damus/blob/main/damus/paper.py"
click node_execution "https://github.com/m0nk4489/damus/blob/main/damus/execution_adapters.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_ui,node_catalog_ui,node_trade_ui,node_controller toneBlue
class node_download_worker,node_providers,node_marketdata,node_feeds,node_store toneAmber
class node_experiment_ui,node_jobs,node_worker,node_engine,node_models,node_analysis_ui,node_chart_data toneMint
class node_resources,node_paper,node_execution toneRose
class node_user,node_data_services,node_broker_services toneIndigo
```

## Components

### Desktop workbench

- [Workbench UI](https://github.com/m0nk4489/damus/blob/main/damus/ui/window.py): `damus/ui/window.py`
- [Data library](https://github.com/m0nk4489/damus/blob/main/damus/ui/data_hub.py): `damus/ui/data_hub.py`
- [Trading controls](https://github.com/m0nk4489/damus/blob/main/damus/ui/trading_controls.py): `damus/ui/trading_controls.py`
- [Application services](https://github.com/m0nk4489/damus/blob/main/damus/controller.py): `damus/controller.py`

### Market data

- [Download process](https://github.com/m0nk4489/damus/blob/main/damus/download_worker.py): `damus/download_worker.py`
- [Provider adapters](https://github.com/m0nk4489/damus/blob/main/damus/providers.py): `damus/providers.py`
- [Historical data](https://github.com/m0nk4489/damus/blob/main/damus/marketdata.py): `damus/marketdata.py`
- [Quote feeds](https://github.com/m0nk4489/damus/blob/main/damus/feeds.py): `damus/feeds.py`
- [Local catalog](https://github.com/m0nk4489/damus/blob/main/damus/storage.py): `damus/storage.py`

### Forecast research

- [Experiment setup](https://github.com/m0nk4489/damus/blob/main/damus/ui/experiment_inputs.py): `damus/ui/experiment_inputs.py`
- [Job coordination](https://github.com/m0nk4489/damus/blob/main/damus/jobs.py): `damus/jobs.py`
- [Experiment worker](https://github.com/m0nk4489/damus/blob/main/damus/worker.py): `damus/worker.py`
- [Forecast and backtest](https://github.com/m0nk4489/damus/blob/main/damus/engine.py): `damus/engine.py`
- [Model adapters](https://github.com/m0nk4489/damus/tree/main/damus/models): `damus/models`
- [Charts and analysis](https://github.com/m0nk4489/damus/blob/main/damus/ui/charts.py): `damus/ui/charts.py`
- [Chart preparation](https://github.com/m0nk4489/damus/blob/main/damus/chart_data.py): `damus/chart_data.py`

### Trading and resources

- [Resource policy](https://github.com/m0nk4489/damus/blob/main/damus/resources.py): `damus/resources.py`
- [Forward session](https://github.com/m0nk4489/damus/blob/main/damus/paper.py): `damus/paper.py`
- [Execution adapters](https://github.com/m0nk4489/damus/blob/main/damus/execution_adapters.py): `damus/execution_adapters.py`

### Other components

- **Researcher**
- **Market data services**
- **Broker or exchange**

## Connections

- Researcher → Workbench UI: uses
- Workbench UI → Data library: opens library
- Workbench UI → Experiment setup: configures runs
- Workbench UI → Charts and analysis: inspects results
- Workbench UI → Trading controls: controls trading
- Data library → Application services: requests data
- Application services → Download process: isolates download
- Download process → Application services: requests bars
- Application services → Provider adapters: selects source
- Provider adapters → Historical data: provides history
- Provider adapters → Market data services: requests bars
- Application services → Local catalog: registers datasets
- Application services → Job coordination: queues experiment
- Job coordination → Experiment worker: dispatches job
- Experiment worker → Forecast and backtest: runs experiment
- Experiment worker → Resource policy: configures limits
- Forecast and backtest → Model adapters: fits and predicts
- Experiment worker → Local catalog: writes results
- Charts and analysis → Application services: requests results
- Charts and analysis → Chart preparation: prepares plots
- Trading controls → Application services: controls session
- Application services → Forward session: starts session
- Forward session → Quote feeds: reads quotes
- Quote feeds → Market data services: polls quotes
- Forward session → Execution adapters: routes actions
- Execution adapters → Broker or exchange: places orders
- Application services → Execution adapters: selects broker