# luckypant10307-coder/mcx architecture

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

- Interactive diagram: https://gitdiagram.com/luckypant10307-coder/mcx
- Repository: https://github.com/luckypant10307-coder/mcx

## Overview

MCX Gold Spread Monitor ingests settlement and margin data, normalizes contracts and estimates relative-value signals, applies trading and risk gates, and simulates outcomes without placing orders. The nightly pipeline publishes a JSON snapshot; the API serves it to the dashboard and supports signed-in assistant and notification features. The README also documents timestamped attestations and circular monitoring. Edges are limited to relationships visible in excerpts, the source index, or README; some unsampled UI and integration links are therefore left dashed or omitted.

Main entry points: [`mcxrv/pipeline.py`](https://github.com/luckypant10307-coder/mcx/blob/main/mcxrv/pipeline.py) (Analysis pipeline), [`api/main.py`](https://github.com/luckypant10307-coder/mcx/blob/main/api/main.py) (FastAPI routes), [`api/service.py`](https://github.com/luckypant10307-coder/mcx/blob/main/api/service.py) (Snapshot API service), [`mcxrv/sources`](https://github.com/luckypant10307-coder/mcx/tree/main/mcxrv/sources) (Market sources)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_intake["Data intake"]
  node_sources["Market sources"]
  node_published["Published margins"]
  node_intake_validation["Validation and calendar<br/>[validation.py]"]
  node_specs["Contract specifications<br/>[specs.py]"]
  node_anomaly["Anomaly review<br/>[anomaly.py]"]
end

subgraph group_engine["Signal engine"]
  node_normalize["Price normalization<br/>[normalize.py]"]
  node_carry["Carry and residuals<br/>[half_life.py]"]
  node_pairs["Pair matching<br/>[pair_match.py]"]
  node_zscore["Pair signals<br/>[z_score.py]"]
  node_pipeline["Analysis pipeline<br/>[pipeline.py]"]
end

subgraph group_risk["Gates and simulation"]
  node_costs["Liquidity and costs<br/>[liquidity_cost.py]"]
  node_margin["Margin and capital<br/>[margin_capital.py]"]
  node_riskboard["Risk board<br/>[risk.py]"]
  node_replay["Walk-forward replay<br/>[replay_driver.py]"]
end

subgraph group_app["API and dashboard"]
  node_snapshot["Published snapshot<br/>[snapshot.py]"]
  node_service["Snapshot API service<br/>[service.py]"]
  node_api["FastAPI routes<br/>[main.py]"]
  node_dashboard["Dashboard pages<br/>[main.tsx]"]
end

subgraph group_services["User services"]
  node_assistant["Read-only assistant<br/>[assistant.py]"]
  node_circulars["Circular monitoring<br/>[circulars.py]"]
  node_notifications["Notifications<br/>[notify.py]"]
  node_attest["Timestamped attestations<br/>[attest.py]"]
end

node_operator(("Nightly job"))
node_market[("MCX settlement data")]
node_user(("Signed-in user"))

node_operator -.->|"runs nightly"| node_pipeline
node_market -->|"provides prices"| node_sources
node_sources -->|"supplies input"| node_pipeline
node_published -->|"supplies margin rates"| node_pipeline
node_pipeline -->|"validates data"| node_intake_validation
node_intake_validation -->|"uses contract rules"| node_specs
node_pipeline -->|"includes review"| node_anomaly
node_pipeline -->|"normalizes prices"| node_normalize
node_pipeline -->|"fits carry"| node_carry
node_pipeline -->|"matches contracts"| node_pairs
node_pipeline -->|"computes signals"| node_zscore
node_pipeline -->|"prices trading costs"| node_costs
node_pipeline -->|"loads margin model"| node_margin
node_pipeline -->|"builds risk board"| node_riskboard
node_pipeline -->|"runs backtest"| node_replay
node_pipeline -.->|"builds snapshot"| node_snapshot
node_snapshot -->|"loads snapshot"| node_service
node_api -->|"routes requests"| node_service
node_dashboard -.->|"requests dashboard data"| node_api
node_api -->|"answers questions"| node_assistant
node_service -->|"checks on demand"| node_circulars
node_pipeline -.->|"drives alerting"| node_notifications
node_pipeline -.->|"records decisions"| node_attest
node_user -->|"views results"| node_dashboard
node_user -->|"asks questions"| node_assistant

click node_sources "https://github.com/luckypant10307-coder/mcx/tree/main/mcxrv/sources"
click node_published "https://github.com/luckypant10307-coder/mcx/blob/main/mcxrv/published_margins.py"
click node_intake_validation "https://github.com/luckypant10307-coder/mcx/blob/main/mcxrv/stage1_intake/validation.py"
click node_specs "https://github.com/luckypant10307-coder/mcx/blob/main/mcxrv/stage1_intake/specs.py"
click node_anomaly "https://github.com/luckypant10307-coder/mcx/blob/main/mcxrv/stage1_intake/anomaly.py"
click node_normalize "https://github.com/luckypant10307-coder/mcx/blob/main/mcxrv/stage2_normalize_signal/normalize.py"
click node_carry "https://github.com/luckypant10307-coder/mcx/blob/main/mcxrv/stage2_normalize_signal/half_life.py"
click node_pairs "https://github.com/luckypant10307-coder/mcx/blob/main/mcxrv/stage2_normalize_signal/pair_match.py"
click node_zscore "https://github.com/luckypant10307-coder/mcx/blob/main/mcxrv/stage2_normalize_signal/z_score.py"
click node_pipeline "https://github.com/luckypant10307-coder/mcx/blob/main/mcxrv/pipeline.py"
click node_costs "https://github.com/luckypant10307-coder/mcx/blob/main/mcxrv/stage3_gates_decision/liquidity_cost.py"
click node_margin "https://github.com/luckypant10307-coder/mcx/blob/main/mcxrv/stage3_gates_decision/margin_capital.py"
click node_riskboard "https://github.com/luckypant10307-coder/mcx/blob/main/mcxrv/stage3_gates_decision/risk.py"
click node_replay "https://github.com/luckypant10307-coder/mcx/blob/main/mcxrv/stage4_simulate_deliver/replay_driver.py"
click node_snapshot "https://github.com/luckypant10307-coder/mcx/blob/main/mcxrv/snapshot.py"
click node_service "https://github.com/luckypant10307-coder/mcx/blob/main/api/service.py"
click node_api "https://github.com/luckypant10307-coder/mcx/blob/main/api/main.py"
click node_dashboard "https://github.com/luckypant10307-coder/mcx/blob/main/frontend/src/main.tsx"
click node_assistant "https://github.com/luckypant10307-coder/mcx/blob/main/mcxrv/assistant.py"
click node_circulars "https://github.com/luckypant10307-coder/mcx/blob/main/mcxrv/circulars.py"
click node_notifications "https://github.com/luckypant10307-coder/mcx/blob/main/mcxrv/notify.py"
click node_attest "https://github.com/luckypant10307-coder/mcx/blob/main/mcxrv/attest.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_sources,node_published,node_intake_validation,node_specs,node_anomaly,node_user toneBlue
class node_normalize,node_carry,node_pairs,node_zscore,node_pipeline,node_market toneAmber
class node_costs,node_margin,node_riskboard,node_replay toneMint
class node_snapshot,node_service,node_api,node_dashboard toneRose
class node_assistant,node_circulars,node_notifications,node_attest,node_operator toneIndigo
```

## Components

### Data intake

- [Market sources](https://github.com/luckypant10307-coder/mcx/tree/main/mcxrv/sources): `mcxrv/sources`
- [Published margins](https://github.com/luckypant10307-coder/mcx/blob/main/mcxrv/published_margins.py): `mcxrv/published_margins.py`
- [Validation and calendar](https://github.com/luckypant10307-coder/mcx/blob/main/mcxrv/stage1_intake/validation.py): `mcxrv/stage1_intake/validation.py`
- [Contract specifications](https://github.com/luckypant10307-coder/mcx/blob/main/mcxrv/stage1_intake/specs.py): `mcxrv/stage1_intake/specs.py`
- [Anomaly review](https://github.com/luckypant10307-coder/mcx/blob/main/mcxrv/stage1_intake/anomaly.py): `mcxrv/stage1_intake/anomaly.py`

### Signal engine

- [Price normalization](https://github.com/luckypant10307-coder/mcx/blob/main/mcxrv/stage2_normalize_signal/normalize.py): `mcxrv/stage2_normalize_signal/normalize.py`
- [Carry and residuals](https://github.com/luckypant10307-coder/mcx/blob/main/mcxrv/stage2_normalize_signal/half_life.py): `mcxrv/stage2_normalize_signal/half_life.py`
- [Pair matching](https://github.com/luckypant10307-coder/mcx/blob/main/mcxrv/stage2_normalize_signal/pair_match.py): `mcxrv/stage2_normalize_signal/pair_match.py`
- [Pair signals](https://github.com/luckypant10307-coder/mcx/blob/main/mcxrv/stage2_normalize_signal/z_score.py): `mcxrv/stage2_normalize_signal/z_score.py`
- [Analysis pipeline](https://github.com/luckypant10307-coder/mcx/blob/main/mcxrv/pipeline.py): `mcxrv/pipeline.py`

### Gates and simulation

- [Liquidity and costs](https://github.com/luckypant10307-coder/mcx/blob/main/mcxrv/stage3_gates_decision/liquidity_cost.py): `mcxrv/stage3_gates_decision/liquidity_cost.py`
- [Margin and capital](https://github.com/luckypant10307-coder/mcx/blob/main/mcxrv/stage3_gates_decision/margin_capital.py): `mcxrv/stage3_gates_decision/margin_capital.py`
- [Risk board](https://github.com/luckypant10307-coder/mcx/blob/main/mcxrv/stage3_gates_decision/risk.py): `mcxrv/stage3_gates_decision/risk.py`
- [Walk-forward replay](https://github.com/luckypant10307-coder/mcx/blob/main/mcxrv/stage4_simulate_deliver/replay_driver.py): `mcxrv/stage4_simulate_deliver/replay_driver.py`

### API and dashboard

- [Published snapshot](https://github.com/luckypant10307-coder/mcx/blob/main/mcxrv/snapshot.py): `mcxrv/snapshot.py`
- [Snapshot API service](https://github.com/luckypant10307-coder/mcx/blob/main/api/service.py): `api/service.py`
- [FastAPI routes](https://github.com/luckypant10307-coder/mcx/blob/main/api/main.py): `api/main.py`
- [Dashboard pages](https://github.com/luckypant10307-coder/mcx/blob/main/frontend/src/main.tsx): `frontend/src/main.tsx`

### User services

- [Read-only assistant](https://github.com/luckypant10307-coder/mcx/blob/main/mcxrv/assistant.py): `mcxrv/assistant.py`
- [Circular monitoring](https://github.com/luckypant10307-coder/mcx/blob/main/mcxrv/circulars.py): `mcxrv/circulars.py`
- [Notifications](https://github.com/luckypant10307-coder/mcx/blob/main/mcxrv/notify.py): `mcxrv/notify.py`
- [Timestamped attestations](https://github.com/luckypant10307-coder/mcx/blob/main/mcxrv/attest.py): `mcxrv/attest.py`

### Other components

- **Nightly job**
- **MCX settlement data**
- **Signed-in user**

## Connections

- Nightly job → Analysis pipeline: runs nightly
- MCX settlement data → Market sources: provides prices
- Market sources → Analysis pipeline: supplies input (evidence: `mcxrv/pipeline.py`)
- Published margins → Analysis pipeline: supplies margin rates (evidence: `mcxrv/pipeline.py`)
- Analysis pipeline → Validation and calendar: validates data (evidence: `mcxrv/pipeline.py`)
- Validation and calendar → Contract specifications: uses contract rules (evidence: `mcxrv/stage1_intake/validation.py`)
- Analysis pipeline → Anomaly review: includes review (evidence: `mcxrv/pipeline.py`)
- Analysis pipeline → Price normalization: normalizes prices (evidence: `mcxrv/pipeline.py`)
- Analysis pipeline → Carry and residuals: fits carry (evidence: `mcxrv/pipeline.py`)
- Analysis pipeline → Pair matching: matches contracts (evidence: `mcxrv/pipeline.py`)
- Analysis pipeline → Pair signals: computes signals (evidence: `mcxrv/pipeline.py`)
- Analysis pipeline → Liquidity and costs: prices trading costs (evidence: `mcxrv/pipeline.py`)
- Analysis pipeline → Margin and capital: loads margin model (evidence: `mcxrv/pipeline.py`)
- Analysis pipeline → Risk board: builds risk board (evidence: `mcxrv/pipeline.py`)
- Analysis pipeline → Walk-forward replay: runs backtest (evidence: `mcxrv/pipeline.py`)
- Analysis pipeline → Published snapshot: builds snapshot
- Published snapshot → Snapshot API service: loads snapshot (evidence: `api/service.py`)
- FastAPI routes → Snapshot API service: routes requests (evidence: `api/main.py`)
- Dashboard pages → FastAPI routes: requests dashboard data
- FastAPI routes → Read-only assistant: answers questions (evidence: `api/main.py`)
- Snapshot API service → Circular monitoring: checks on demand (evidence: `api/service.py`)
- Analysis pipeline → Notifications: drives alerting
- Analysis pipeline → Timestamped attestations: records decisions
- Signed-in user → Dashboard pages: views results
- Signed-in user → Read-only assistant: asks questions