# allanfoulo/hft-sys architecture

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

## Overview

jev-loop is a continuously runnable paper-trading harness. A user selects a crypto pair or equity; the loop resolves asset rules, reads Alpaca market data, builds deterministic state, asks Jev’s seven-question battery (or uses a mock client), composes a strategy action, applies an independent hard-risk veto, then prices and executes quotes. The loop tracks fills and inventory and publishes logs/latest state for the dashboard; calibration evaluates logged decisions. README documents these capabilities, but pricing, risk, serving, and several loop call sites were not sampled, so uncertain wiring is omitted.

Main entry points: [`jevloop/loop.py`](https://github.com/allanfoulo/hft-sys/blob/main/jevloop/loop.py) (Tick loop), [`jevloop/__main__.py`](https://github.com/allanfoulo/hft-sys/blob/main/jevloop/__main__.py) (CLI entry), [`jevloop/battery.py`](https://github.com/allanfoulo/hft-sys/blob/main/jevloop/battery.py) (Jev battery), [`jevloop/execution/alpaca.py`](https://github.com/allanfoulo/hft-sys/blob/main/jevloop/execution/alpaca.py) (Order execution)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cycle["Trading cycle"]
  node_cli["CLI entry<br/>[__main__.py]"]
  node_loop["Tick loop<br/>[loop.py]"]
end

subgraph group_decisions["Judgment and policy"]
  node_battery["Jev battery<br/>[battery.py]"]
  node_split["Question guard<br/>[split.py]"]
  node_client["Decision client<br/>[client.py]"]
  node_policy["Policy engine<br/>[policy.py]"]
  node_strategy["Strategy hook<br/>[strategy.py]"]
  node_ladder["Fallback ladder<br/>[ladder.py]"]
  node_pricing["Quote pricing<br/>[pricing.py]"]
  node_risk["Risk veto<br/>[risk.py]"]
  node_limits["Hard limits<br/>[limits.py]"]
end

subgraph group_venue["Venue integration"]
  node_assets["Asset resolver<br/>[assets.py]"]
  node_alpaca["Alpaca client<br/>[alpaca.py]"]
  node_execution["Order execution<br/>[alpaca.py]"]
end

subgraph group_observability["State and monitoring"]
  node_snapshot["State snapshot<br/>[state.py]"]
  node_state["Inventory state<br/>[state.py]"]
  node_logs[("Tick logs<br/>[loop.py]")]
  node_dashboard["Dashboard server<br/>[serve.py]"]
  node_web["Dashboard UI<br/>[index.html]"]
  node_wall["Wall display<br/>[wall.html]"]
  node_calibrate["Calibration<br/>[calibrate.py]"]
end

node_user(("Trader"))
node_market["Alpaca services"]
node_jev["Jev APIs"]

node_user -->|"starts run"| node_cli
node_cli -->|"starts ticks"| node_loop
node_cli -->|"resolves symbol"| node_assets
node_loop -->|"reads market data"| node_alpaca
node_alpaca -->|"requests data"| node_market
node_loop -->|"builds state"| node_snapshot
node_snapshot -->|"updates inventory"| node_state
node_loop -->|"requests judgments"| node_battery
node_battery -->|"validates questions"| node_split
node_battery -->|"asks questions"| node_client
node_client -->|"sends request"| node_jev
node_loop -->|"selects rung"| node_ladder
node_loop -->|"composes action"| node_policy
node_policy -->|"applies hook"| node_strategy
node_loop -->|"prices quotes"| node_pricing
node_loop -->|"checks action"| node_risk
node_risk -->|"reads caps"| node_limits
node_loop -->|"submits orders"| node_execution
node_execution -->|"places orders"| node_market
node_execution -->|"records fills"| node_state
node_loop -->|"writes ticks"| node_logs
node_dashboard -->|"reads latest"| node_logs
node_web -->|"served by"| node_dashboard
node_wall -->|"served by"| node_dashboard
node_calibrate -->|"reads history"| node_logs

click node_cli "https://github.com/allanfoulo/hft-sys/blob/main/jevloop/__main__.py"
click node_loop "https://github.com/allanfoulo/hft-sys/blob/main/jevloop/loop.py"
click node_assets "https://github.com/allanfoulo/hft-sys/blob/main/jevloop/assets.py"
click node_alpaca "https://github.com/allanfoulo/hft-sys/blob/main/jevloop/execution/alpaca.py"
click node_snapshot "https://github.com/allanfoulo/hft-sys/blob/main/jevloop/state.py"
click node_battery "https://github.com/allanfoulo/hft-sys/blob/main/jevloop/battery.py"
click node_split "https://github.com/allanfoulo/hft-sys/blob/main/jevloop/split.py"
click node_client "https://github.com/allanfoulo/hft-sys/blob/main/jevloop/client.py"
click node_policy "https://github.com/allanfoulo/hft-sys/blob/main/jevloop/policy.py"
click node_strategy "https://github.com/allanfoulo/hft-sys/blob/main/jevloop/strategy.py"
click node_ladder "https://github.com/allanfoulo/hft-sys/blob/main/jevloop/ladder.py"
click node_pricing "https://github.com/allanfoulo/hft-sys/blob/main/jevloop/pricing.py"
click node_risk "https://github.com/allanfoulo/hft-sys/blob/main/jevloop/risk.py"
click node_limits "https://github.com/allanfoulo/hft-sys/blob/main/jevloop/limits.py"
click node_execution "https://github.com/allanfoulo/hft-sys/blob/main/jevloop/execution/alpaca.py"
click node_state "https://github.com/allanfoulo/hft-sys/blob/main/jevloop/state.py"
click node_logs "https://github.com/allanfoulo/hft-sys/blob/main/jevloop/loop.py"
click node_dashboard "https://github.com/allanfoulo/hft-sys/blob/main/jevloop/serve.py"
click node_web "https://github.com/allanfoulo/hft-sys/blob/main/dashboard/index.html"
click node_wall "https://github.com/allanfoulo/hft-sys/blob/main/dashboard/wall.html"
click node_calibrate "https://github.com/allanfoulo/hft-sys/blob/main/jevloop/calibrate.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_cli,node_loop toneBlue
class node_battery,node_split,node_client,node_policy,node_strategy,node_ladder,node_pricing,node_risk,node_limits toneAmber
class node_assets,node_alpaca,node_execution,node_jev toneMint
class node_snapshot,node_state,node_logs,node_dashboard,node_web,node_wall,node_calibrate toneRose
class node_user,node_market toneIndigo
```

## Components

### Trading cycle

- [CLI entry](https://github.com/allanfoulo/hft-sys/blob/main/jevloop/__main__.py): `jevloop/__main__.py`
- [Tick loop](https://github.com/allanfoulo/hft-sys/blob/main/jevloop/loop.py): `jevloop/loop.py`

### Judgment and policy

- [Jev battery](https://github.com/allanfoulo/hft-sys/blob/main/jevloop/battery.py): `jevloop/battery.py`
- [Question guard](https://github.com/allanfoulo/hft-sys/blob/main/jevloop/split.py): `jevloop/split.py`
- [Decision client](https://github.com/allanfoulo/hft-sys/blob/main/jevloop/client.py): `jevloop/client.py`
- [Policy engine](https://github.com/allanfoulo/hft-sys/blob/main/jevloop/policy.py): `jevloop/policy.py`
- [Strategy hook](https://github.com/allanfoulo/hft-sys/blob/main/jevloop/strategy.py): `jevloop/strategy.py`
- [Fallback ladder](https://github.com/allanfoulo/hft-sys/blob/main/jevloop/ladder.py): `jevloop/ladder.py`
- [Quote pricing](https://github.com/allanfoulo/hft-sys/blob/main/jevloop/pricing.py): `jevloop/pricing.py`
- [Risk veto](https://github.com/allanfoulo/hft-sys/blob/main/jevloop/risk.py): `jevloop/risk.py`
- [Hard limits](https://github.com/allanfoulo/hft-sys/blob/main/jevloop/limits.py): `jevloop/limits.py`

### Venue integration

- [Asset resolver](https://github.com/allanfoulo/hft-sys/blob/main/jevloop/assets.py): `jevloop/assets.py`
- [Alpaca client](https://github.com/allanfoulo/hft-sys/blob/main/jevloop/execution/alpaca.py): `jevloop/execution/alpaca.py`
- [Order execution](https://github.com/allanfoulo/hft-sys/blob/main/jevloop/execution/alpaca.py): `jevloop/execution/alpaca.py`

### State and monitoring

- [State snapshot](https://github.com/allanfoulo/hft-sys/blob/main/jevloop/state.py): `jevloop/state.py`
- [Inventory state](https://github.com/allanfoulo/hft-sys/blob/main/jevloop/state.py): `jevloop/state.py`
- [Tick logs](https://github.com/allanfoulo/hft-sys/blob/main/jevloop/loop.py): `jevloop/loop.py`
- [Dashboard server](https://github.com/allanfoulo/hft-sys/blob/main/jevloop/serve.py): `jevloop/serve.py`
- [Dashboard UI](https://github.com/allanfoulo/hft-sys/blob/main/dashboard/index.html): `dashboard/index.html`
- [Wall display](https://github.com/allanfoulo/hft-sys/blob/main/dashboard/wall.html): `dashboard/wall.html`
- [Calibration](https://github.com/allanfoulo/hft-sys/blob/main/jevloop/calibrate.py): `jevloop/calibrate.py`

### Other components

- **Trader**
- **Alpaca services**
- **Jev APIs**

## Connections

- Trader → CLI entry: starts run
- CLI entry → Tick loop: starts ticks
- CLI entry → Asset resolver: resolves symbol
- Tick loop → Alpaca client: reads market data
- Alpaca client → Alpaca services: requests data
- Tick loop → State snapshot: builds state
- State snapshot → Inventory state: updates inventory
- Tick loop → Jev battery: requests judgments
- Jev battery → Question guard: validates questions
- Jev battery → Decision client: asks questions
- Decision client → Jev APIs: sends request
- Tick loop → Fallback ladder: selects rung
- Tick loop → Policy engine: composes action
- Policy engine → Strategy hook: applies hook
- Tick loop → Quote pricing: prices quotes
- Tick loop → Risk veto: checks action
- Risk veto → Hard limits: reads caps
- Tick loop → Order execution: submits orders
- Order execution → Alpaca services: places orders
- Order execution → Inventory state: records fills
- Tick loop → Tick logs: writes ticks
- Dashboard server → Tick logs: reads latest
- Dashboard UI → Dashboard server: served by
- Wall display → Dashboard server: served by
- Calibration → Tick logs: reads history