# meet252501/yeno-volume-bot-challenge- architecture

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

- Interactive diagram: https://gitdiagram.com/meet252501/yeno-volume-bot-challenge-
- Repository: https://github.com/meet252501/yeno-volume-bot-challenge-

## Overview

YeNo Volume Bot is a simulated trading agent for BTC five-minute Up/Down markets. Its main workflow accepts market, account, reference-price, and order-book state, then returns HOLD, BUY, or SELL; the strategy must manage fees, risk, completed-cycle volume, and finishing flat. The repository has a modular reference /decide implementation and a separate, more elaborate Velocity bot in bot.py. Replay reporting is present, but replay execution is explicitly unimplemented. The architecture below reflects sampled code and README capabilities; some documented strategy subsystems have no sampled implementation wiring.

Main entry points: [`src/api/server.py`](https://github.com/meet252501/yeno-volume-bot-challenge-/blob/main/src/api/server.py) (Reference API), [`src/decision.py`](https://github.com/meet252501/yeno-volume-bot-challenge-/blob/main/src/decision.py) (Decision engine), [`bot.py`](https://github.com/meet252501/yeno-volume-bot-challenge-/blob/main/bot.py) (Velocity HTTP handler), [`src/backtest/replay.py`](https://github.com/meet252501/yeno-volume-bot-challenge-/blob/main/src/backtest/replay.py) (Replay harness)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["Decision interfaces"]
  node_request["Decision request<br/>[models.py]"]
  node_endpoint["Reference API<br/>[server.py]"]
  node_response["Decision response<br/>[models.py]"]
  node_velocity_http["Velocity HTTP handler<br/>[bot.py]"]
  node_health["Health status<br/>[server.py]"]
end

subgraph group_strategy["Trading strategy"]
  node_velocity["Velocity bot<br/>[bot.py]"]
  node_decision["Decision engine<br/>[decision.py]"]
  node_fees["Fee model<br/>[fees.py]"]
end

subgraph group_accounting["Risk and accounting"]
  node_risk["Risk controls<br/>[risk.py]"]
  node_tracker["Cycle tracker<br/>[cycle_tracker.py]"]
end

subgraph group_replay["Replay evaluation"]
  node_replay_input["Replay paths"]
  node_replay_runner["Replay harness<br/>[replay.py]"]
  node_replay_report["Replay report<br/>[report.py]"]
end

node_evaluator(("Challenge evaluator"))

node_evaluator -->|"calls /decide"| node_endpoint
node_endpoint -->|"validates as"| node_request
node_endpoint -->|"calls"| node_decision
node_endpoint -->|"passes state"| node_tracker
node_decision -->|"checks sizing"| node_risk
node_decision -->|"scores price"| node_fees
node_decision -->|"checks flatness"| node_tracker
node_decision -->|"returns action"| node_response
node_endpoint -->|"reports volume"| node_health
node_evaluator -.->|"posts observation"| node_velocity_http
node_velocity_http -->|"calls decide"| node_velocity
node_replay_input -->|"loads paths"| node_replay_runner
node_replay_runner -->|"builds report"| node_replay_report

click node_request "https://github.com/meet252501/yeno-volume-bot-challenge-/blob/main/src/models.py"
click node_endpoint "https://github.com/meet252501/yeno-volume-bot-challenge-/blob/main/src/api/server.py"
click node_response "https://github.com/meet252501/yeno-volume-bot-challenge-/blob/main/src/models.py"
click node_velocity_http "https://github.com/meet252501/yeno-volume-bot-challenge-/blob/main/bot.py"
click node_velocity "https://github.com/meet252501/yeno-volume-bot-challenge-/blob/main/bot.py"
click node_decision "https://github.com/meet252501/yeno-volume-bot-challenge-/blob/main/src/decision.py"
click node_fees "https://github.com/meet252501/yeno-volume-bot-challenge-/blob/main/src/fees.py"
click node_risk "https://github.com/meet252501/yeno-volume-bot-challenge-/blob/main/src/risk.py"
click node_tracker "https://github.com/meet252501/yeno-volume-bot-challenge-/blob/main/src/cycle_tracker.py"
click node_health "https://github.com/meet252501/yeno-volume-bot-challenge-/blob/main/src/api/server.py"
click node_replay_input "https://github.com/meet252501/yeno-volume-bot-challenge-/tree/main/data/replay"
click node_replay_runner "https://github.com/meet252501/yeno-volume-bot-challenge-/blob/main/src/backtest/replay.py"
click node_replay_report "https://github.com/meet252501/yeno-volume-bot-challenge-/blob/main/src/backtest/report.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_request,node_endpoint,node_response,node_velocity_http,node_health toneBlue
class node_velocity,node_decision,node_fees toneAmber
class node_risk,node_tracker toneMint
class node_replay_input,node_replay_runner,node_replay_report toneRose
class node_evaluator toneIndigo
```

## Components

### Decision interfaces

- [Decision request](https://github.com/meet252501/yeno-volume-bot-challenge-/blob/main/src/models.py): `src/models.py`
- [Reference API](https://github.com/meet252501/yeno-volume-bot-challenge-/blob/main/src/api/server.py): `src/api/server.py`
- [Decision response](https://github.com/meet252501/yeno-volume-bot-challenge-/blob/main/src/models.py): `src/models.py`
- [Velocity HTTP handler](https://github.com/meet252501/yeno-volume-bot-challenge-/blob/main/bot.py): `bot.py`
- [Health status](https://github.com/meet252501/yeno-volume-bot-challenge-/blob/main/src/api/server.py): `src/api/server.py`

### Trading strategy

- [Velocity bot](https://github.com/meet252501/yeno-volume-bot-challenge-/blob/main/bot.py): `bot.py`
- [Decision engine](https://github.com/meet252501/yeno-volume-bot-challenge-/blob/main/src/decision.py): `src/decision.py`
- [Fee model](https://github.com/meet252501/yeno-volume-bot-challenge-/blob/main/src/fees.py): `src/fees.py`

### Risk and accounting

- [Risk controls](https://github.com/meet252501/yeno-volume-bot-challenge-/blob/main/src/risk.py): `src/risk.py`
- [Cycle tracker](https://github.com/meet252501/yeno-volume-bot-challenge-/blob/main/src/cycle_tracker.py): `src/cycle_tracker.py`

### Replay evaluation

- [Replay paths](https://github.com/meet252501/yeno-volume-bot-challenge-/tree/main/data/replay): `data/replay`
- [Replay harness](https://github.com/meet252501/yeno-volume-bot-challenge-/blob/main/src/backtest/replay.py): `src/backtest/replay.py`
- [Replay report](https://github.com/meet252501/yeno-volume-bot-challenge-/blob/main/src/backtest/report.py): `src/backtest/report.py`

### Other components

- **Challenge evaluator**

## Connections

- Challenge evaluator → Reference API: calls /decide
- Reference API → Decision request: validates as
- Reference API → Decision engine: calls
- Reference API → Cycle tracker: passes state
- Decision engine → Risk controls: checks sizing
- Decision engine → Fee model: scores price
- Decision engine → Cycle tracker: checks flatness
- Decision engine → Decision response: returns action
- Reference API → Health status: reports volume
- Challenge evaluator → Velocity HTTP handler: posts observation
- Velocity HTTP handler → Velocity bot: calls decide
- Replay paths → Replay harness: loads paths
- Replay harness → Replay report: builds report