# parv-065040/racepulse architecture

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

- Interactive diagram: https://gitdiagram.com/parv-065040/racepulse
- Repository: https://github.com/parv-065040/racepulse

## Overview

RACEPULSE simulates and publishes race-domain events, validates and analyzes Kafka streams, then persists KPIs and emits alerts for Grafana-oriented operations and commercial dashboards. The graph emphasizes the sampled performance and windowed paths; broader event domains and dashboard capabilities are documented in the README, but their wiring is not fully evidenced in the excerpts.

Main entry points: [`consumers/performance/timing_consumer.py`](https://github.com/parv-065040/racepulse/blob/main/consumers/performance/timing_consumer.py) (Performance Consumer), [`consumers/windowed/windowed_consumer.py`](https://github.com/parv-065040/racepulse/blob/main/consumers/windowed/windowed_consumer.py) (Windowed Consumer), [`simulator/simulator.py`](https://github.com/parv-065040/racepulse/blob/main/simulator/simulator.py) (Race Simulator), [`engine/alerts/alert_engine.py`](https://github.com/parv-065040/racepulse/blob/main/engine/alerts/alert_engine.py) (Alert Engine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_generation["Race Generation"]
  node_sim["Race Simulator<br/>[simulator.py]"]
  node_state["Race State<br/>[state.py]"]
  node_scenarios["Race Scenarios<br/>[scenario.py]"]
  node_producers["Domain Producers"]
end

subgraph group_streaming["Event Streaming"]
  node_kafka["Kafka Topics"]
  node_performance["Performance Consumer<br/>[timing_consumer.py]"]
  node_windowed["Windowed Consumer"]
  node_commercial["Commercial Consumer"]
  node_racecontrol["Race Control Consumer"]
  node_strategy["Strategy Consumer"]
end

subgraph group_analysis["Validation &amp; Analytics"]
  node_validation["Validation Gate<br/>[gate.py]"]
  node_config["Live Configuration<br/>[loader.py]"]
  node_formulas["Performance Formulas"]
  node_windows["Window Analytics"]
  node_severity["Severity Rules<br/>[severity_rules.py]"]
end

subgraph group_operations["Persistence &amp; Alerts"]
  node_mysql[("MySQL")]
  node_writer["KPI Writer<br/>[writer.py]"]
  node_alerts["Alert Engine<br/>[alert_engine.py]"]
  node_dlq["Dead Letter Queue<br/>[dlq.py]"]
  node_monitor["Stream Health Monitor"]
end

subgraph group_decision["Decision Support"]
  node_grafana["Grafana Dashboards"]
end

node_operator(("Race Operator"))
node_team(("Race Team"))
node_business(("Commercial Users"))

node_operator -->|"selects scenario"| node_sim
node_sim -->|"applies scenarios"| node_scenarios
node_sim -->|"advances race state"| node_state
node_producers -->|"generate from"| node_sim
node_producers -.->|"publish events"| node_kafka
node_kafka -->|"timing events"| node_performance
node_kafka -->|"telemetry events"| node_windowed
node_kafka -.->|"business events"| node_commercial
node_kafka -.->|"incident events"| node_racecontrol
node_kafka -.->|"race events"| node_strategy
node_performance -->|"validates via"| node_validation
node_windowed -->|"validates via"| node_validation
node_validation -->|"routes rejects"| node_dlq
node_performance -->|"starts watcher"| node_config
node_performance -->|"computes KPIs"| node_formulas
node_performance -->|"persists results"| node_writer
node_performance -->|"raises alerts"| node_alerts
node_performance -->|"checks stale cars"| node_monitor
node_windowed -->|"accumulates windows"| node_windows
node_windowed -->|"computes average"| node_formulas
node_windowed -->|"saves window KPI"| node_writer
node_formulas -->|"classifies results"| node_severity
node_writer -->|"writes KPI rows"| node_mysql
node_alerts -->|"publishes alerts"| node_kafka
node_alerts -->|"stores alerts"| node_mysql
node_mysql -.->|"dashboard queries"| node_grafana
node_grafana -->|"presents decisions"| node_team
node_grafana -->|"presents metrics"| node_business

click node_sim "https://github.com/parv-065040/racepulse/blob/main/simulator/simulator.py"
click node_state "https://github.com/parv-065040/racepulse/blob/main/simulator/state.py"
click node_scenarios "https://github.com/parv-065040/racepulse/blob/main/simulator/scenario.py"
click node_producers "https://github.com/parv-065040/racepulse/tree/main/producers"
click node_performance "https://github.com/parv-065040/racepulse/blob/main/consumers/performance/timing_consumer.py"
click node_windowed "https://github.com/parv-065040/racepulse/blob/main/consumers/windowed/windowed_consumer.py"
click node_commercial "https://github.com/parv-065040/racepulse/blob/main/consumers/commercial/commercial_consumer.py"
click node_racecontrol "https://github.com/parv-065040/racepulse/blob/main/consumers/race_control/race_control_consumer.py"
click node_strategy "https://github.com/parv-065040/racepulse/blob/main/consumers/strategy/strategy_consumer.py"
click node_validation "https://github.com/parv-065040/racepulse/blob/main/engine/validation/gate.py"
click node_config "https://github.com/parv-065040/racepulse/blob/main/engine/config/loader.py"
click node_formulas "https://github.com/parv-065040/racepulse/tree/main/engine/formulas"
click node_windows "https://github.com/parv-065040/racepulse/tree/main/engine/windows"
click node_severity "https://github.com/parv-065040/racepulse/blob/main/engine/rules/severity_rules.py"
click node_writer "https://github.com/parv-065040/racepulse/blob/main/database/writer.py"
click node_alerts "https://github.com/parv-065040/racepulse/blob/main/engine/alerts/alert_engine.py"
click node_dlq "https://github.com/parv-065040/racepulse/blob/main/engine/validation/dlq.py"
click node_monitor "https://github.com/parv-065040/racepulse/blob/main/engine/alerts/stale_stream_monitor.py"
click node_grafana "https://github.com/parv-065040/racepulse/tree/main/tools/dashboard_builder"

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_sim,node_state,node_scenarios,node_producers,node_business toneBlue
class node_kafka,node_performance,node_windowed,node_commercial,node_racecontrol,node_strategy toneAmber
class node_validation,node_config,node_formulas,node_windows,node_severity toneMint
class node_mysql,node_writer,node_alerts,node_dlq,node_monitor toneRose
class node_grafana,node_operator,node_team toneIndigo
```

## Components

### Race Generation

- [Race Simulator](https://github.com/parv-065040/racepulse/blob/main/simulator/simulator.py): `simulator/simulator.py`
- [Race State](https://github.com/parv-065040/racepulse/blob/main/simulator/state.py): `simulator/state.py`
- [Race Scenarios](https://github.com/parv-065040/racepulse/blob/main/simulator/scenario.py): `simulator/scenario.py`
- [Domain Producers](https://github.com/parv-065040/racepulse/tree/main/producers): `producers`

### Event Streaming

- **Kafka Topics**
- [Performance Consumer](https://github.com/parv-065040/racepulse/blob/main/consumers/performance/timing_consumer.py): `consumers/performance/timing_consumer.py`
- [Windowed Consumer](https://github.com/parv-065040/racepulse/blob/main/consumers/windowed/windowed_consumer.py): `consumers/windowed/windowed_consumer.py`
- [Commercial Consumer](https://github.com/parv-065040/racepulse/blob/main/consumers/commercial/commercial_consumer.py): `consumers/commercial/commercial_consumer.py`
- [Race Control Consumer](https://github.com/parv-065040/racepulse/blob/main/consumers/race_control/race_control_consumer.py): `consumers/race_control/race_control_consumer.py`
- [Strategy Consumer](https://github.com/parv-065040/racepulse/blob/main/consumers/strategy/strategy_consumer.py): `consumers/strategy/strategy_consumer.py`

### Validation & Analytics

- [Validation Gate](https://github.com/parv-065040/racepulse/blob/main/engine/validation/gate.py): `engine/validation/gate.py`
- [Live Configuration](https://github.com/parv-065040/racepulse/blob/main/engine/config/loader.py): `engine/config/loader.py`
- [Performance Formulas](https://github.com/parv-065040/racepulse/tree/main/engine/formulas): `engine/formulas`
- [Window Analytics](https://github.com/parv-065040/racepulse/tree/main/engine/windows): `engine/windows`
- [Severity Rules](https://github.com/parv-065040/racepulse/blob/main/engine/rules/severity_rules.py): `engine/rules/severity_rules.py`

### Persistence & Alerts

- **MySQL**
- [KPI Writer](https://github.com/parv-065040/racepulse/blob/main/database/writer.py): `database/writer.py`
- [Alert Engine](https://github.com/parv-065040/racepulse/blob/main/engine/alerts/alert_engine.py): `engine/alerts/alert_engine.py`
- [Dead Letter Queue](https://github.com/parv-065040/racepulse/blob/main/engine/validation/dlq.py): `engine/validation/dlq.py`
- [Stream Health Monitor](https://github.com/parv-065040/racepulse/blob/main/engine/alerts/stale_stream_monitor.py): `engine/alerts/stale_stream_monitor.py`

### Decision Support

- [Grafana Dashboards](https://github.com/parv-065040/racepulse/tree/main/tools/dashboard_builder): `tools/dashboard_builder`

### Other components

- **Race Operator**
- **Race Team**
- **Commercial Users**

## Connections

- Race Operator → Race Simulator: selects scenario
- Race Simulator → Race Scenarios: applies scenarios (evidence: `simulator/simulator.py`)
- Race Simulator → Race State: advances race state (evidence: `simulator/simulator.py`)
- Domain Producers → Race Simulator: generate from (evidence: `producers/fans/producer.py`)
- Domain Producers → Kafka Topics: publish events
- Kafka Topics → Performance Consumer: timing events
- Kafka Topics → Windowed Consumer: telemetry events (evidence: `consumers/windowed/windowed_consumer.py`)
- Kafka Topics → Commercial Consumer: business events
- Kafka Topics → Race Control Consumer: incident events
- Kafka Topics → Strategy Consumer: race events
- Performance Consumer → Validation Gate: validates via (evidence: `consumers/performance/timing_consumer.py`)
- Windowed Consumer → Validation Gate: validates via (evidence: `consumers/windowed/windowed_consumer.py`)
- Validation Gate → Dead Letter Queue: routes rejects (evidence: `engine/validation/gate.py`)
- Performance Consumer → Live Configuration: starts watcher (evidence: `consumers/performance/timing_consumer.py`)
- Performance Consumer → Performance Formulas: computes KPIs (evidence: `consumers/performance/timing_consumer.py`)
- Performance Consumer → KPI Writer: persists results (evidence: `consumers/performance/timing_consumer.py`)
- Performance Consumer → Alert Engine: raises alerts (evidence: `consumers/performance/timing_consumer.py`)
- Performance Consumer → Stream Health Monitor: checks stale cars (evidence: `consumers/performance/timing_consumer.py`)
- Windowed Consumer → Window Analytics: accumulates windows (evidence: `consumers/windowed/windowed_consumer.py`)
- Windowed Consumer → Performance Formulas: computes average (evidence: `consumers/windowed/windowed_consumer.py`)
- Windowed Consumer → KPI Writer: saves window KPI (evidence: `consumers/windowed/windowed_consumer.py`)
- Performance Formulas → Severity Rules: classifies results (evidence: `engine/formulas/gap_trend.py`)
- KPI Writer → MySQL: writes KPI rows (evidence: `database/writer.py`)
- Alert Engine → Kafka Topics: publishes alerts (evidence: `engine/alerts/alert_engine.py`)
- Alert Engine → MySQL: stores alerts (evidence: `engine/alerts/alert_engine.py`)
- MySQL → Grafana Dashboards: dashboard queries
- Grafana Dashboards → Race Team: presents decisions
- Grafana Dashboards → Commercial Users: presents metrics
