# br-g/openf1 architecture

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

- Interactive diagram: https://gitdiagram.com/br-g/openf1
- Repository: https://github.com/br-g/openf1

## Overview

OpenF1 exposes real-time and historical Formula 1 data through a read-only JSON/CSV API. The principal workflow is timing-data ingestion into MongoDB, followed by parameterized API queries and returned results. Separate branches scrape schedule and session results, while live ingestion also supports MQTT publication and optional raw-data object-storage uploads. The graph reflects README capabilities and source-index references; some unsampled subsystem internals and wiring are represented only at directory level or omitted where evidence is insufficient.

Main entry points: [`src/openf1/util/db.py`](https://github.com/br-g/openf1/blob/main/src/openf1/util/db.py) (MongoDB access), [`src/openf1/services/ingestor_livetiming/real_time/processing.py`](https://github.com/br-g/openf1/blob/main/src/openf1/services/ingestor_livetiming/real_time/processing.py) (Live processor), [`src/openf1/services/query_api/app.py`](https://github.com/br-g/openf1/blob/main/src/openf1/services/query_api/app.py) (API routes), [`src/openf1/services/ingestor_livetiming/real_time/app.py`](https://github.com/br-g/openf1/blob/main/src/openf1/services/ingestor_livetiming/real_time/app.py) (Live orchestrator)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Timing ingestion"]
  node_realtime_app["Live orchestrator<br/>[app.py]"]
  node_recording["Raw recorder<br/>[recording.py]"]
  node_live_processing["Live processor<br/>[processing.py]"]
  node_decoder["Message decoder<br/>[decoding.py]"]
  node_message_model["Timing messages<br/>[objects.py]"]
  node_collection_router["Collection dispatcher<br/>[main.py]"]
  node_collections["Timing collections"]
  node_historical_ingest["Historical ingestor<br/>[main.py]"]
end

subgraph group_scrape["Historical scraping"]
  node_scrape_schedule["Schedule scraper<br/>[schedule.py]"]
  node_scrape_results["Session results<br/>[session_result.py]"]
  node_scrape_grid["Starting grid<br/>[starting_grid.py]"]
end

subgraph group_api["Query API"]
  node_api_app["API routes<br/>[app.py]"]
  node_query_params["Query filters<br/>[query_params.py]"]
  node_api_cache["Response cache<br/>[cache.py]"]
  node_csv_output["CSV responses<br/>[csv.py]"]
end

subgraph group_shared["Shared data services"]
  node_database[("MongoDB access<br/>[db.py]")]
  node_schedule_util["Schedule lookup<br/>[schedule.py]"]
end

subgraph group_integrations["External integrations"]
  node_mqtt["MQTT publisher<br/>[mqtt.py]"]
  node_object_storage["Object storage<br/>[storage.py]"]
  node_mqtt_service["MQTT broker"]
  node_s3_service[("S3-compatible storage")]
end

node_consumer(("API consumer"))

node_consumer -->|"requests data"| node_api_app
node_api_app -->|"parses filters"| node_query_params
node_api_app -->|"checks cache"| node_api_cache
node_api_app -->|"fetches documents"| node_database
node_api_app -->|"formats CSV"| node_csv_output
node_realtime_app -->|"records stream"| node_recording
node_realtime_app -->|"ingests file"| node_live_processing
node_realtime_app -->|"gets topics"| node_message_model
node_realtime_app -->|"uploads raw data"| node_object_storage
node_object_storage -->|"uploads files"| node_s3_service
node_live_processing -->|"decodes messages"| node_decoder
node_live_processing -->|"processes messages"| node_collection_router
node_collection_router -->|"maps topics"| node_message_model
node_collection_router -.->|"dispatches to"| node_collections
node_live_processing -.->|"writes documents"| node_database
node_live_processing -->|"publishes updates"| node_mqtt
node_mqtt -.->|"publishes messages"| node_mqtt_service
node_historical_ingest -->|"decodes archives"| node_decoder
node_historical_ingest -->|"processes messages"| node_collection_router
node_historical_ingest -.->|"writes history"| node_database
node_historical_ingest -->|"resolves sessions"| node_schedule_util
node_scrape_schedule -->|"stores schedule"| node_database
node_scrape_results -->|"stores results"| node_database
node_scrape_grid -->|"stores grid"| node_database
node_scrape_results -->|"uses schedule"| node_schedule_util
node_scrape_grid -->|"uses schedule"| node_schedule_util

click node_realtime_app "https://github.com/br-g/openf1/blob/main/src/openf1/services/ingestor_livetiming/real_time/app.py"
click node_recording "https://github.com/br-g/openf1/blob/main/src/openf1/services/ingestor_livetiming/real_time/recording.py"
click node_live_processing "https://github.com/br-g/openf1/blob/main/src/openf1/services/ingestor_livetiming/real_time/processing.py"
click node_decoder "https://github.com/br-g/openf1/blob/main/src/openf1/services/ingestor_livetiming/core/decoding.py"
click node_message_model "https://github.com/br-g/openf1/blob/main/src/openf1/services/ingestor_livetiming/core/objects.py"
click node_collection_router "https://github.com/br-g/openf1/blob/main/src/openf1/services/ingestor_livetiming/core/processing/main.py"
click node_collections "https://github.com/br-g/openf1/tree/main/src/openf1/services/ingestor_livetiming/core/processing/collections"
click node_historical_ingest "https://github.com/br-g/openf1/blob/main/src/openf1/services/ingestor_livetiming/historical/main.py"
click node_scrape_schedule "https://github.com/br-g/openf1/blob/main/src/openf1/services/f1_scraping/schedule.py"
click node_scrape_results "https://github.com/br-g/openf1/blob/main/src/openf1/services/f1_scraping/session_result.py"
click node_scrape_grid "https://github.com/br-g/openf1/blob/main/src/openf1/services/f1_scraping/starting_grid.py"
click node_api_app "https://github.com/br-g/openf1/blob/main/src/openf1/services/query_api/app.py"
click node_query_params "https://github.com/br-g/openf1/blob/main/src/openf1/services/query_api/query_params.py"
click node_api_cache "https://github.com/br-g/openf1/blob/main/src/openf1/services/query_api/cache.py"
click node_csv_output "https://github.com/br-g/openf1/blob/main/src/openf1/services/query_api/csv.py"
click node_database "https://github.com/br-g/openf1/blob/main/src/openf1/util/db.py"
click node_schedule_util "https://github.com/br-g/openf1/blob/main/src/openf1/util/schedule.py"
click node_mqtt "https://github.com/br-g/openf1/blob/main/src/openf1/util/mqtt.py"
click node_object_storage "https://github.com/br-g/openf1/blob/main/src/openf1/util/storage.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_realtime_app,node_recording,node_live_processing,node_decoder,node_message_model,node_collection_router,node_collections,node_historical_ingest toneBlue
class node_scrape_schedule,node_scrape_results,node_scrape_grid toneAmber
class node_api_app,node_query_params,node_api_cache,node_csv_output,node_consumer toneMint
class node_database,node_schedule_util toneRose
class node_mqtt,node_object_storage,node_mqtt_service,node_s3_service toneIndigo
```

## Components

### Timing ingestion

- [Live orchestrator](https://github.com/br-g/openf1/blob/main/src/openf1/services/ingestor_livetiming/real_time/app.py): `src/openf1/services/ingestor_livetiming/real_time/app.py`
- [Raw recorder](https://github.com/br-g/openf1/blob/main/src/openf1/services/ingestor_livetiming/real_time/recording.py): `src/openf1/services/ingestor_livetiming/real_time/recording.py`
- [Live processor](https://github.com/br-g/openf1/blob/main/src/openf1/services/ingestor_livetiming/real_time/processing.py): `src/openf1/services/ingestor_livetiming/real_time/processing.py`
- [Message decoder](https://github.com/br-g/openf1/blob/main/src/openf1/services/ingestor_livetiming/core/decoding.py): `src/openf1/services/ingestor_livetiming/core/decoding.py`
- [Timing messages](https://github.com/br-g/openf1/blob/main/src/openf1/services/ingestor_livetiming/core/objects.py): `src/openf1/services/ingestor_livetiming/core/objects.py`
- [Collection dispatcher](https://github.com/br-g/openf1/blob/main/src/openf1/services/ingestor_livetiming/core/processing/main.py): `src/openf1/services/ingestor_livetiming/core/processing/main.py`
- [Timing collections](https://github.com/br-g/openf1/tree/main/src/openf1/services/ingestor_livetiming/core/processing/collections): `src/openf1/services/ingestor_livetiming/core/processing/collections`
- [Historical ingestor](https://github.com/br-g/openf1/blob/main/src/openf1/services/ingestor_livetiming/historical/main.py): `src/openf1/services/ingestor_livetiming/historical/main.py`

### Historical scraping

- [Schedule scraper](https://github.com/br-g/openf1/blob/main/src/openf1/services/f1_scraping/schedule.py): `src/openf1/services/f1_scraping/schedule.py`
- [Session results](https://github.com/br-g/openf1/blob/main/src/openf1/services/f1_scraping/session_result.py): `src/openf1/services/f1_scraping/session_result.py`
- [Starting grid](https://github.com/br-g/openf1/blob/main/src/openf1/services/f1_scraping/starting_grid.py): `src/openf1/services/f1_scraping/starting_grid.py`

### Query API

- [API routes](https://github.com/br-g/openf1/blob/main/src/openf1/services/query_api/app.py): `src/openf1/services/query_api/app.py`
- [Query filters](https://github.com/br-g/openf1/blob/main/src/openf1/services/query_api/query_params.py): `src/openf1/services/query_api/query_params.py`
- [Response cache](https://github.com/br-g/openf1/blob/main/src/openf1/services/query_api/cache.py): `src/openf1/services/query_api/cache.py`
- [CSV responses](https://github.com/br-g/openf1/blob/main/src/openf1/services/query_api/csv.py): `src/openf1/services/query_api/csv.py`

### Shared data services

- [MongoDB access](https://github.com/br-g/openf1/blob/main/src/openf1/util/db.py): `src/openf1/util/db.py`
- [Schedule lookup](https://github.com/br-g/openf1/blob/main/src/openf1/util/schedule.py): `src/openf1/util/schedule.py`

### External integrations

- [MQTT publisher](https://github.com/br-g/openf1/blob/main/src/openf1/util/mqtt.py): `src/openf1/util/mqtt.py`
- [Object storage](https://github.com/br-g/openf1/blob/main/src/openf1/util/storage.py): `src/openf1/util/storage.py`
- **MQTT broker**
- **S3-compatible storage**

### Other components

- **API consumer**

## Connections

- API consumer → API routes: requests data (evidence: `README.md`)
- API routes → Query filters: parses filters (evidence: `src/openf1/services/query_api/app.py`)
- API routes → Response cache: checks cache (evidence: `src/openf1/services/query_api/app.py`)
- API routes → MongoDB access: fetches documents (evidence: `src/openf1/services/query_api/app.py`)
- API routes → CSV responses: formats CSV (evidence: `src/openf1/services/query_api/app.py`)
- Live orchestrator → Raw recorder: records stream (evidence: `src/openf1/services/ingestor_livetiming/real_time/app.py`)
- Live orchestrator → Live processor: ingests file (evidence: `src/openf1/services/ingestor_livetiming/real_time/app.py`)
- Live orchestrator → Timing messages: gets topics (evidence: `src/openf1/services/ingestor_livetiming/real_time/app.py`)
- Live orchestrator → Object storage: uploads raw data (evidence: `src/openf1/services/ingestor_livetiming/real_time/app.py`)
- Object storage → S3-compatible storage: uploads files (evidence: `src/openf1/util/storage.py`)
- Live processor → Message decoder: decodes messages (evidence: `src/openf1/services/ingestor_livetiming/real_time/processing.py`)
- Live processor → Collection dispatcher: processes messages (evidence: `src/openf1/services/ingestor_livetiming/real_time/processing.py`)
- Collection dispatcher → Timing messages: maps topics (evidence: `src/openf1/services/ingestor_livetiming/core/processing/main.py`)
- Collection dispatcher → Timing collections: dispatches to
- Live processor → MongoDB access: writes documents (evidence: `src/openf1/services/ingestor_livetiming/real_time/processing.py`)
- Live processor → MQTT publisher: publishes updates (evidence: `src/openf1/services/ingestor_livetiming/real_time/processing.py`)
- MQTT publisher → MQTT broker: publishes messages
- Historical ingestor → Message decoder: decodes archives (evidence: `src/openf1/services/ingestor_livetiming/historical/main.py`)
- Historical ingestor → Collection dispatcher: processes messages (evidence: `src/openf1/services/ingestor_livetiming/historical/main.py`)
- Historical ingestor → MongoDB access: writes history (evidence: `src/openf1/services/ingestor_livetiming/historical/main.py`)
- Historical ingestor → Schedule lookup: resolves sessions (evidence: `src/openf1/services/ingestor_livetiming/historical/main.py`)
- Schedule scraper → MongoDB access: stores schedule (evidence: `src/openf1/services/f1_scraping/schedule.py`)
- Session results → MongoDB access: stores results (evidence: `src/openf1/services/f1_scraping/session_result.py`)
- Starting grid → MongoDB access: stores grid (evidence: `src/openf1/services/f1_scraping/starting_grid.py`)
- Session results → Schedule lookup: uses schedule (evidence: `src/openf1/services/f1_scraping/session_result.py`)
- Starting grid → Schedule lookup: uses schedule (evidence: `src/openf1/services/f1_scraping/starting_grid.py`)
