How wnndgws/simba works
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: udp_processor.py UDP processor · cached_values.py Cached values · udp_collector.py UDP collector · udp_protocol.py UDP protocol
Components 18
Telemetry pipeline
UDP ingestion, collection, decoding, and shared state.
- UDP receiver · Listens for incoming telemetry packets from the simulator.
src/utils/udp_receiver.py - UDP collector · Aggregates and normalizes raw telemetry frames.
src/utils/udp_collector.py - UDP processor · Transforms collected telemetry into structured application state.
src/utils/udp_processor.py - Cached values · Stores the latest usable telemetry and derived values.
src/config/cached_values.py - UDP protocol · Defines the packet structure and telemetry fields.
src/models/udp_protocol.py - Decode maps · Lookup tables for protocol enums and numeric codes.
src/models/decode_dictionaries.py - Collected model · Intermediate object for raw collected telemetry data.
src/models/udp_collected.py - Car SVG · Represents car-specific visual or rendering data.
src/models/car_svg.py
Presentation
HTML templates and static styling for the dashboard.
- Main view · Primary dashboard page template.
templates/main.html - Base layout · Shared page shell for rendered views.
templates/shared/_base.html - Main CSS · Styles for the telemetry dashboard UI.
templates/static/css/main.css
Package support
Project packaging, core package anchor, and tests.
- Core package · Core package boundary and expansion point.
src/core/__init__.py - Models package · Namespace for telemetry and visualization models.
src/models/__init__.py - Utils package · Namespace for receiver, collector, and processor utilities.
src/utils/__init__.py - Config package · Namespace for shared configuration and runtime state.
src/config/__init__.py - Test config · Pytest configuration for telemetry and state behavior.
src/tests/pytest.toml - Pyproject · Project metadata and dependency management entry point.
pyproject.toml - Uv lock · Resolved dependency lockfile for the uv toolchain.
uv.lock
Connections 18
- 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.