# wnndgws/simba architecture

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

- Interactive diagram: https://gitdiagram.com/wnndgws/simba
- Repository: https://github.com/wnndgws/simba

## Overview

1. **Project shape**
   - This is a small Python telemetry application named `simba`, aimed at consuming racing-sim telemetry for F1 25 and displaying a focused dashboard of useful racing information.
   - The repo is organized as a package under `src/`, with a separate `templates/` tree for the UI.

2. **Runtime and packaging**
   - The project is Python-based and managed with `pyproject.toml` plus `uv.lock`, so dependency resolution and execution are likely handled with the `uv` toolchain.
   - There is a dedicated `src/tests` area, suggesting the code is intended to be testable as a library/application package rather than a one-off script.

3. **Telemetry ingestion boundary**
   - `src/utils/udp_receiver.py` is the entry point for external telemetry traffic.
   - The name strongly indicates the app listens for incoming UDP packets from the game or sim host, making UDP the primary integration boundary with the external racing simulator.

4. **Collection and buffering**
   - `src/utils/udp_collector.py` likely sits between raw packet reception and higher-level processing.
   - This layer probably groups, stores, or normalizes incoming telemetry frames before they are decoded into app-level models.

5. **Telemetry processing**
   - `src/utils/udp_processor.py` appears to transform raw collected UDP data into structured, consumable state.
   - This is the main translation layer from protocol-specific telemetry into internal application data.

6. **Protocol and decoding models**
   - `src/models/udp_protocol.py` and `src/models/decode_dictionaries.py` indicate the app understands a defined packet structure and uses lookup tables to decode enumerations or numeric fields.
   - `src/models/udp_collected.py` likely represents the intermediate/raw collected telemetry object, while `src/models/car_svg.py` suggests a model for visualizing car state or car-specific rendering data.

7. **Shared state and cached values**
   - `src/config/cached_values.py` points to an internal cache of the latest telemetry or derived values.
   - This is likely the main state boundary in the app: receiver/collector update the cache, processor derives useful fields, and the UI reads from the cached state.

8. **Presentation layer**
   - `templates/main.html` and `templates/shared/_base.html` show a templated HTML frontend with shared layout composition.
   - `templates/static/css/main.css` provides styling, so the user-facing output is a lightweight rendered interface rather than a heavy client-side app.

9. **Core package boundary**
   - `src/core/__init__.py` exists but no additional core modules are visible in the tree, suggesting the “core” layer may be small or mostly composed elsewhere.
   - Architecturally, the main boundary appears to be between telemetry processing logic and presentation, with `core` acting as a package anchor or future expansion point.

10. **Testing and validation**
   - `src/tests/pytest.toml` shows pytest-based testing configuration.
   - Given the presence of UDP parsing and decoding modules, the likely test focus is protocol decoding, collector/processor behavior, and cached-state updates.

11. **Likely end-to-end data flow**
   - External simulator sends UDP telemetry → `udp_receiver` accepts packets → `udp_collector` aggregates/normalizes them → `udp_processor` decodes fields using model definitions and dictionaries → `cached_values` stores the latest usable state → templates render the telemetry dashboard.

12. **What to show in an architecture diagram**
   - Emphasize three main subsystems: telemetry input, telemetry transformation/state, and UI rendering.
   - Show UDP as the only external data ingress, cached values as the central internal state boundary, and the templates/CSS as the presentation layer consuming processed telemetry.

Main entry points: [`src/utils/udp_processor.py`](https://github.com/wnndgws/simba/blob/main/src/utils/udp_processor.py) (UDP processor), [`src/config/cached_values.py`](https://github.com/wnndgws/simba/blob/main/src/config/cached_values.py) (Cached values), [`src/utils/udp_collector.py`](https://github.com/wnndgws/simba/blob/main/src/utils/udp_collector.py) (UDP collector), [`src/models/udp_protocol.py`](https://github.com/wnndgws/simba/blob/main/src/models/udp_protocol.py) (UDP protocol)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_g1["Telemetry pipeline"]
  node_n1(("UDP receiver<br/>ingest<br/>[udp_receiver.py]"))
  node_n2["UDP collector<br/>buffer<br/>[udp_collector.py]"]
  node_n3["UDP processor<br/>decode<br/>[udp_processor.py]"]
  node_n4[("Cached values<br/>state<br/>[cached_values.py]")]
  node_n5["UDP protocol<br/>schema<br/>[udp_protocol.py]"]
  node_n6["Decode maps<br/>lookup"]
  node_n7["Collected model<br/>telemetry model<br/>[udp_collected.py]"]
  node_n8["Car SVG<br/>visual model<br/>[car_svg.py]"]
end

subgraph group_g2["Presentation"]
  node_n9["Main view<br/>template<br/>[main.html]"]
  node_n10["Base layout<br/>template<br/>[_base.html]"]
  node_n11["Main CSS<br/>style<br/>[main.css]"]
end

subgraph group_g3["Package support"]
  node_n12["Core package<br/>[__init__.py]"]
  node_n13["Models package<br/>[__init__.py]"]
  node_n14["Utils package<br/>[__init__.py]"]
  node_n15["Config package<br/>[__init__.py]"]
  node_n16["Test config<br/>[pytest.toml]"]
  node_n17["Pyproject<br/>build<br/>[pyproject.toml]"]
  node_n18["Uv lock<br/>lockfile<br/>[uv.lock]"]
end

node_n1 -->|"packets"| node_n2
node_n2 -->|"frames"| node_n3
node_n3 -->|"latest state"| node_n4
node_n3 -->|"parse"| node_n5
node_n3 -->|"decode"| node_n6
node_n2 -->|"buffer"| node_n7
node_n7 -->|"input"| node_n3
node_n5 -->|"shape"| node_n7
node_n8 -->|"derive"| node_n4
node_n4 -->|"render"| node_n9
node_n10 -->|"layout"| node_n9
node_n11 -->|"style"| node_n9
node_n12 -->|"boundary"| node_n3
node_n13 -->|"exports"| node_n5
node_n14 -->|"hosts"| node_n1
node_n15 -->|"holds"| node_n4
node_n16 -.->|"validate"| node_n3
node_n17 -->|"pins"| node_n18

click node_n1 "https://github.com/wnndgws/simba/blob/main/src/utils/udp_receiver.py"
click node_n2 "https://github.com/wnndgws/simba/blob/main/src/utils/udp_collector.py"
click node_n3 "https://github.com/wnndgws/simba/blob/main/src/utils/udp_processor.py"
click node_n4 "https://github.com/wnndgws/simba/blob/main/src/config/cached_values.py"
click node_n5 "https://github.com/wnndgws/simba/blob/main/src/models/udp_protocol.py"
click node_n6 "https://github.com/wnndgws/simba/blob/main/src/models/decode_dictionaries.py"
click node_n7 "https://github.com/wnndgws/simba/blob/main/src/models/udp_collected.py"
click node_n8 "https://github.com/wnndgws/simba/blob/main/src/models/car_svg.py"
click node_n9 "https://github.com/wnndgws/simba/blob/main/templates/main.html"
click node_n10 "https://github.com/wnndgws/simba/blob/main/templates/shared/_base.html"
click node_n11 "https://github.com/wnndgws/simba/blob/main/templates/static/css/main.css"
click node_n12 "https://github.com/wnndgws/simba/blob/main/src/core/__init__.py"
click node_n13 "https://github.com/wnndgws/simba/blob/main/src/models/__init__.py"
click node_n14 "https://github.com/wnndgws/simba/blob/main/src/utils/__init__.py"
click node_n15 "https://github.com/wnndgws/simba/blob/main/src/config/__init__.py"
click node_n16 "https://github.com/wnndgws/simba/blob/main/src/tests/pytest.toml"
click node_n17 "https://github.com/wnndgws/simba/blob/main/pyproject.toml"
click node_n18 "https://github.com/wnndgws/simba/blob/main/uv.lock"

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_n1,node_n2,node_n3,node_n4,node_n5,node_n6,node_n7,node_n8 toneBlue
class node_n9,node_n10,node_n11 toneAmber
class node_n12,node_n13,node_n14,node_n15,node_n16,node_n17,node_n18 toneMint
```

## Components

### Telemetry pipeline

UDP ingestion, collection, decoding, and shared state.

- [UDP receiver](https://github.com/wnndgws/simba/blob/main/src/utils/udp_receiver.py): ingest · Listens for incoming telemetry packets from the simulator. · `src/utils/udp_receiver.py`
- [UDP collector](https://github.com/wnndgws/simba/blob/main/src/utils/udp_collector.py): buffer · Aggregates and normalizes raw telemetry frames. · `src/utils/udp_collector.py`
- [UDP processor](https://github.com/wnndgws/simba/blob/main/src/utils/udp_processor.py): decode · Transforms collected telemetry into structured application state. · `src/utils/udp_processor.py`
- [Cached values](https://github.com/wnndgws/simba/blob/main/src/config/cached_values.py): state · Stores the latest usable telemetry and derived values. · `src/config/cached_values.py`
- [UDP protocol](https://github.com/wnndgws/simba/blob/main/src/models/udp_protocol.py): schema · Defines the packet structure and telemetry fields. · `src/models/udp_protocol.py`
- [Decode maps](https://github.com/wnndgws/simba/blob/main/src/models/decode_dictionaries.py): lookup · Lookup tables for protocol enums and numeric codes. · `src/models/decode_dictionaries.py`
- [Collected model](https://github.com/wnndgws/simba/blob/main/src/models/udp_collected.py): telemetry model · Intermediate object for raw collected telemetry data. · `src/models/udp_collected.py`
- [Car SVG](https://github.com/wnndgws/simba/blob/main/src/models/car_svg.py): visual model · Represents car-specific visual or rendering data. · `src/models/car_svg.py`

### Presentation

HTML templates and static styling for the dashboard.

- [Main view](https://github.com/wnndgws/simba/blob/main/templates/main.html): template · Primary dashboard page template. · `templates/main.html`
- [Base layout](https://github.com/wnndgws/simba/blob/main/templates/shared/_base.html): template · Shared page shell for rendered views. · `templates/shared/_base.html`
- [Main CSS](https://github.com/wnndgws/simba/blob/main/templates/static/css/main.css): style · Styles for the telemetry dashboard UI. · `templates/static/css/main.css`

### Package support

Project packaging, core package anchor, and tests.

- [Core package](https://github.com/wnndgws/simba/blob/main/src/core/__init__.py): package · Core package boundary and expansion point. · `src/core/__init__.py`
- [Models package](https://github.com/wnndgws/simba/blob/main/src/models/__init__.py): package · Namespace for telemetry and visualization models. · `src/models/__init__.py`
- [Utils package](https://github.com/wnndgws/simba/blob/main/src/utils/__init__.py): package · Namespace for receiver, collector, and processor utilities. · `src/utils/__init__.py`
- [Config package](https://github.com/wnndgws/simba/blob/main/src/config/__init__.py): package · Namespace for shared configuration and runtime state. · `src/config/__init__.py`
- [Test config](https://github.com/wnndgws/simba/blob/main/src/tests/pytest.toml): test config · Pytest configuration for telemetry and state behavior. · `src/tests/pytest.toml`
- [Pyproject](https://github.com/wnndgws/simba/blob/main/pyproject.toml): build · Project metadata and dependency management entry point. · `pyproject.toml`
- [Uv lock](https://github.com/wnndgws/simba/blob/main/uv.lock): lockfile · Resolved dependency lockfile for the uv toolchain. · `uv.lock`

## Connections

- UDP receiver → UDP collector: packets · Raw UDP packets are handed to collection and normalization.
- UDP collector → UDP processor: frames · Collected telemetry is decoded into application-ready state.
- UDP processor → Cached values: latest state · Processed values are written into the shared cache.
- UDP processor → UDP protocol: parse · Processor interprets packets using the telemetry schema.
- UDP processor → Decode maps: decode · Processor resolves codes and enums through lookup tables.
- UDP collector → Collected model: buffer · Collector builds intermediate collected telemetry objects.
- Collected model → UDP processor: input · Collected model is the processor's main input.
- UDP protocol → Collected model: shape · Protocol definitions describe the collected telemetry structure.
- Car SVG → Cached values: derive · Car-specific display data can be derived from cached telemetry.
- Cached values → Main view: render · Templates read the shared cached state to render the dashboard.
- Base layout → Main view: layout · Main view composes the shared base layout.
- Main CSS → Main view: style · Dashboard view is styled by the main stylesheet.
- Core package → UDP processor: boundary · Core package anchors central application logic.
- Models package → UDP protocol: exports · Models package groups protocol and visualization definitions.
- Utils package → UDP receiver: hosts · Utilities package contains the UDP ingress path.
- Config package → Cached values: holds · Config package contains shared cached runtime values.
- Test config → UDP processor: validate · Tests likely cover decoding and processor behavior.
- Pyproject → Uv lock: pins · Project metadata is paired with the resolved lockfile.
