# dykij/dmarket_bot architecture

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

- Interactive diagram: https://gitdiagram.com/dykij/dmarket_bot
- Repository: https://github.com/dykij/dmarket_bot

## Overview

#### Purpose and entry points
DMarket Quantitative Engine is an autonomous Python trading system for DMarket marketplace items. It scans order-book-derived demand signals, evaluates candidates, executes purchases/resales (or dry runs), and manages positions. Primary runtime entry point is `src/__main__.py`, which initializes and runs the application via `src/core/application.py`; operational startup is also supported by `scripts/start.sh` and Docker definitions.

#### Application lifecycle and orchestration
The core application owns configuration, startup/shutdown, recovery, signals, and notifications. It composes long-running scanner and trading services rather than exposing an HTTP application interface.
- `src/core/application.py`
- `src/core/app_initialization.py`
- `src/core/app_lifecycle.py`

Control flow is: load environment/configuration → initialize persistence, API, risk, telemetry, and notifications → run scheduled/autonomous scan cycles → recover or shut down safely on lifecycle events.

#### Market-access boundary
DMarket REST v2 interaction is isolated behind a signed client with account, market, offer, target, fee, retry/backoff, and rate-limit concerns. Rust/PyO3 provides Ed25519 signing support, creating a language boundary between Python orchestration and cryptographic performance code.
- `src/api/dmarket_api_client/core.py`
- `src/api/dmarket_api_client/rate_limiter.py`
- `src/rust_core/src/lib.rs`

External dependencies are DMarket API credentials/services and, optionally, Telegram. API responses become normalized market/candidate inputs for trading stages.

#### Target-sniping trading pipeline
`target_sniping` is the architecture’s execution-critical pipeline. Its cycle orchestrator schedules scanner output through filtering, microstructure analysis, demand/price ranking, validation, guarded execution, and resale management.
- `src/core/target_sniping/cycle_orchestrator.py`
- `src/core/target_sniping/scanner.py`
- `src/core/target_sniping/execution.py`

Primary data flow: listings and aggregated bid/ask data → candidate items → OBI/demand and price calculations → ranked, validated targets → purchase order or sandbox result → inventory position → resale/exit action.

#### Signal, valuation, and strategy layer
Microstructure modules calculate OBI-related signals and volatility; the algorithm pack supplies statistical models. The demand strategy applies adaptive thresholds, and pricing/fair-value logic establishes expected economics before a target is eligible.
- `src/core/target_sniping/microstructure_pipeline.py`
- `src/core/target_sniping/demand_strategy.py`
- `src/core/target_sniping/pricing.py`

This is intentionally separated from API transport and execution, allowing signal generation and strategy tuning without directly placing orders. Additional strategies exist under `src/strategies/`, but the target-sniping demand pipeline is the stated primary path.

#### Risk, positions, and persistence
Risk controls form a gate around both entry and holding: price validation, liquidity/pump checks, concentration/portfolio rules, dynamic controls, and circuit breaking. Position guards and resale modules determine stops, profit targets, holding limits, and exit execution. SQLite in WAL mode persists price history, inventory, targets, state, and analytics.
- `src/risk/risk_manager.py`
- `src/core/target_sniping/position_guard.py`
- `src/db/price_history/core.py`

The persistence boundary should preserve trade/position state across restarts; recovery logic is in the core lifecycle rather than the database package.

#### Operations, observability, and control
Telegram is the operator command and notification surface, while Prometheus metrics and health endpoints support machine monitoring. Docker Compose provides deployment composition; Python 3.13+ is the main runtime, with Rust built through Cargo/Maturin.
- `src/telegram/control_bot/bot.py`
- `src/monitoring/prometheus_metrics.py`
- `src/utils/health_server.py`

Dry-run and live-shadow components provide non-production execution boundaries before real DMarket order placement.
- `src/core/live_shadow.py`
- `src/core/target_sniping/sandbox.py`

Main entry points: [`src/core/target_sniping/execution.py`](https://github.com/dykij/dmarket_bot/blob/main/src/core/target_sniping/execution.py) (Guarded execution), [`src/core/application.py`](https://github.com/dykij/dmarket_bot/blob/main/src/core/application.py) (Application), [`src/api/dmarket_api_client/core.py`](https://github.com/dykij/dmarket_bot/blob/main/src/api/dmarket_api_client/core.py) (DMarket client), [`src/core/app_initialization.py`](https://github.com/dykij/dmarket_bot/blob/main/src/core/app_initialization.py) (Initialization)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime & Control"]
  node_application["Application<br/>Python orchestrator<br/>[application.py]"]
  node_initialization["Initialization<br/>composition"]
  node_lifecycle["Lifecycle &amp; recovery<br/>[app_lifecycle.py]"]
  node_sandbox["Sandbox<br/>dry-run execution<br/>[sandbox.py]"]
  node_live_shadow["Live shadow<br/>non-production boundary<br/>[live_shadow.py]"]
end

subgraph group_pipeline["Target-Sniping Pipeline"]
  node_target_cycle["Target cycle<br/>cycle orchestrator"]
  node_scanner["Market scanner<br/>candidate discovery<br/>[scanner.py]"]
  node_microstructure["Microstructure signals<br/>OBI and volatility"]
  node_strategy["Demand strategy<br/>adaptive thresholds<br/>[demand_strategy.py]"]
  node_pricing["Pricing &amp; fair value<br/>valuation<br/>[pricing.py]"]
  node_execution["Guarded execution<br/>purchase and resale<br/>[execution.py]"]
end

subgraph group_integrations["Market &amp; Operations"]
  node_dmarket_client["DMarket client<br/>signed REST v2 client<br/>[core.py]"]
  node_rate_limiter["Rate limiter<br/>API throttling<br/>[rate_limiter.py]"]
  node_rust_signing["Rust signing core<br/>PyO3 Ed25519<br/>[lib.rs]"]
  node_telegram_bot["Telegram control<br/>operator bot<br/>[bot.py]"]
  node_metrics["Prometheus metrics<br/>observability"]
  node_health_server["Health server<br/>health endpoint<br/>[health_server.py]"]
end

subgraph group_state["Risk &amp; State"]
  node_position_guard["Position guard<br/>exit controls<br/>[position_guard.py]"]
  node_risk_manager{{"Risk manager<br/>entry and portfolio gate<br/>[risk_manager.py]"}}
  node_price_history[("SQLite state<br/>WAL persistence<br/>[core.py]")]
end

node_application -->|"initializes"| node_initialization
node_application -->|"manages"| node_lifecycle
node_initialization -->|"configures"| node_dmarket_client
node_initialization -->|"configures"| node_risk_manager
node_application -->|"runs cycles"| node_target_cycle
node_lifecycle -->|"recovers state"| node_price_history
node_target_cycle -->|"scans"| node_scanner
node_scanner -->|"fetches listings and books"| node_dmarket_client
node_scanner -->|"candidate market data"| node_microstructure
node_microstructure -->|"demand signals"| node_strategy
node_strategy -->|"eligible candidates"| node_pricing
node_pricing -->|"valued targets"| node_risk_manager
node_risk_manager -->|"approved targets"| node_execution
node_execution -.->|"dry-run orders"| node_sandbox
node_execution -.->|"shadow orders"| node_live_shadow
node_execution -->|"live orders"| node_dmarket_client
node_execution -->|"opens and manages positions"| node_position_guard
node_position_guard -->|"exit actions"| node_execution
node_execution -->|"persists positions"| node_price_history
node_dmarket_client -->|"throttles requests"| node_rate_limiter
node_dmarket_client -->|"signs requests"| node_rust_signing
node_application -->|"operator notifications"| node_telegram_bot
node_application -->|"emits metrics"| node_metrics
node_application -->|"serves health"| node_health_server

click node_application "https://github.com/dykij/dmarket_bot/blob/main/src/core/application.py"
click node_initialization "https://github.com/dykij/dmarket_bot/blob/main/src/core/app_initialization.py"
click node_lifecycle "https://github.com/dykij/dmarket_bot/blob/main/src/core/app_lifecycle.py"
click node_target_cycle "https://github.com/dykij/dmarket_bot/blob/main/src/core/target_sniping/cycle_orchestrator.py"
click node_scanner "https://github.com/dykij/dmarket_bot/blob/main/src/core/target_sniping/scanner.py"
click node_microstructure "https://github.com/dykij/dmarket_bot/blob/main/src/core/target_sniping/microstructure_pipeline.py"
click node_strategy "https://github.com/dykij/dmarket_bot/blob/main/src/core/target_sniping/demand_strategy.py"
click node_pricing "https://github.com/dykij/dmarket_bot/blob/main/src/core/target_sniping/pricing.py"
click node_execution "https://github.com/dykij/dmarket_bot/blob/main/src/core/target_sniping/execution.py"
click node_position_guard "https://github.com/dykij/dmarket_bot/blob/main/src/core/target_sniping/position_guard.py"
click node_risk_manager "https://github.com/dykij/dmarket_bot/blob/main/src/risk/risk_manager.py"
click node_price_history "https://github.com/dykij/dmarket_bot/blob/main/src/db/price_history/core.py"
click node_dmarket_client "https://github.com/dykij/dmarket_bot/blob/main/src/api/dmarket_api_client/core.py"
click node_rate_limiter "https://github.com/dykij/dmarket_bot/blob/main/src/api/dmarket_api_client/rate_limiter.py"
click node_rust_signing "https://github.com/dykij/dmarket_bot/blob/main/src/rust_core/src/lib.rs"
click node_sandbox "https://github.com/dykij/dmarket_bot/blob/main/src/core/target_sniping/sandbox.py"
click node_live_shadow "https://github.com/dykij/dmarket_bot/blob/main/src/core/live_shadow.py"
click node_telegram_bot "https://github.com/dykij/dmarket_bot/blob/main/src/telegram/control_bot/bot.py"
click node_metrics "https://github.com/dykij/dmarket_bot/blob/main/src/monitoring/prometheus_metrics.py"
click node_health_server "https://github.com/dykij/dmarket_bot/blob/main/src/utils/health_server.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_application,node_initialization,node_lifecycle,node_sandbox,node_live_shadow toneBlue
class node_target_cycle,node_scanner,node_microstructure,node_strategy,node_pricing,node_execution toneAmber
class node_dmarket_client,node_rate_limiter,node_rust_signing,node_telegram_bot,node_metrics,node_health_server toneMint
class node_position_guard,node_risk_manager,node_price_history toneRose
```

## Components

### Runtime & Control

- [Application](https://github.com/dykij/dmarket_bot/blob/main/src/core/application.py): Python orchestrator · Owns startup, recovery, scheduling, and safe shutdown. · `src/core/application.py`
- [Initialization](https://github.com/dykij/dmarket_bot/blob/main/src/core/app_initialization.py): composition · `src/core/app_initialization.py`
- [Lifecycle & recovery](https://github.com/dykij/dmarket_bot/blob/main/src/core/app_lifecycle.py): lifecycle · `src/core/app_lifecycle.py`
- [Sandbox](https://github.com/dykij/dmarket_bot/blob/main/src/core/target_sniping/sandbox.py): dry-run execution · `src/core/target_sniping/sandbox.py`
- [Live shadow](https://github.com/dykij/dmarket_bot/blob/main/src/core/live_shadow.py): non-production boundary · `src/core/live_shadow.py`

### Target-Sniping Pipeline

- [Target cycle](https://github.com/dykij/dmarket_bot/blob/main/src/core/target_sniping/cycle_orchestrator.py): cycle orchestrator · `src/core/target_sniping/cycle_orchestrator.py`
- [Market scanner](https://github.com/dykij/dmarket_bot/blob/main/src/core/target_sniping/scanner.py): candidate discovery · `src/core/target_sniping/scanner.py`
- [Microstructure signals](https://github.com/dykij/dmarket_bot/blob/main/src/core/target_sniping/microstructure_pipeline.py): OBI and volatility · `src/core/target_sniping/microstructure_pipeline.py`
- [Demand strategy](https://github.com/dykij/dmarket_bot/blob/main/src/core/target_sniping/demand_strategy.py): adaptive thresholds · `src/core/target_sniping/demand_strategy.py`
- [Pricing & fair value](https://github.com/dykij/dmarket_bot/blob/main/src/core/target_sniping/pricing.py): valuation · `src/core/target_sniping/pricing.py`
- [Guarded execution](https://github.com/dykij/dmarket_bot/blob/main/src/core/target_sniping/execution.py): purchase and resale · `src/core/target_sniping/execution.py`

### Market & Operations

- [DMarket client](https://github.com/dykij/dmarket_bot/blob/main/src/api/dmarket_api_client/core.py): signed REST v2 client · Handles market, offers, targets, fees, retries, and rate limits. · `src/api/dmarket_api_client/core.py`
- [Rate limiter](https://github.com/dykij/dmarket_bot/blob/main/src/api/dmarket_api_client/rate_limiter.py): API throttling · `src/api/dmarket_api_client/rate_limiter.py`
- [Rust signing core](https://github.com/dykij/dmarket_bot/blob/main/src/rust_core/src/lib.rs): PyO3 Ed25519 · `src/rust_core/src/lib.rs`
- [Telegram control](https://github.com/dykij/dmarket_bot/blob/main/src/telegram/control_bot/bot.py): operator bot · `src/telegram/control_bot/bot.py`
- [Prometheus metrics](https://github.com/dykij/dmarket_bot/blob/main/src/monitoring/prometheus_metrics.py): observability · `src/monitoring/prometheus_metrics.py`
- [Health server](https://github.com/dykij/dmarket_bot/blob/main/src/utils/health_server.py): health endpoint · `src/utils/health_server.py`

### Risk & State

- [Position guard](https://github.com/dykij/dmarket_bot/blob/main/src/core/target_sniping/position_guard.py): exit controls · `src/core/target_sniping/position_guard.py`
- [Risk manager](https://github.com/dykij/dmarket_bot/blob/main/src/risk/risk_manager.py): entry and portfolio gate · `src/risk/risk_manager.py`
- [SQLite state](https://github.com/dykij/dmarket_bot/blob/main/src/db/price_history/core.py): WAL persistence · Persists prices, inventory, targets, and analytics across restarts. · `src/db/price_history/core.py`

## Connections

- Application → Initialization: initializes
- Application → Lifecycle & recovery: manages
- Initialization → DMarket client: configures
- Initialization → Risk manager: configures
- Application → Target cycle: runs cycles
- Lifecycle & recovery → SQLite state: recovers state
- Target cycle → Market scanner: scans
- Market scanner → DMarket client: fetches listings and books
- Market scanner → Microstructure signals: candidate market data
- Microstructure signals → Demand strategy: demand signals
- Demand strategy → Pricing & fair value: eligible candidates
- Pricing & fair value → Risk manager: valued targets
- Risk manager → Guarded execution: approved targets
- Guarded execution → Sandbox: dry-run orders
- Guarded execution → Live shadow: shadow orders
- Guarded execution → DMarket client: live orders
- Guarded execution → Position guard: opens and manages positions
- Position guard → Guarded execution: exit actions
- Guarded execution → SQLite state: persists positions
- DMarket client → Rate limiter: throttles requests
- DMarket client → Rust signing core: signs requests
- Application → Telegram control: operator notifications
- Application → Prometheus metrics: emits metrics
- Application → Health server: serves health