# nirodhauwanpriya/fleet-tracking-platform architecture

> Architecture diagram of the GitHub repository nirodhauwanpriya/fleet-tracking-platform, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nirodhauwanpriya/fleet-tracking-platform
- Repository: https://github.com/nirodhauwanpriya/fleet-tracking-platform

## Overview

1. **What this repository is**
   - A distributed telemetry pipeline for real-time fleet tracking.
   - It is split into four runtime components: a Python simulator, a Go ingestion gateway, a Go stream processor/UI server, and a Go storage worker.
   - Kafka is the central event bus; PostgreSQL is the durable sink.

2. **Core data model and contract**
   - The system revolves around a `telemetry.proto` gRPC/Protobuf contract in `gateway/proto`.
   - Generated Go and Python bindings (`telemetry.pb.go`, `telemetry_grpc.pb.go`, `telemetry_pb2.py`, `telemetry_pb2_grpc.py`) show that the message schema is shared across producer and consumer sides.
   - This contract is the boundary between the simulator and the gateway.

3. **Edge ingestion boundary: `simulator` → `gateway`**
   - `simulator/sim.py` acts as an IoT fleet emitter, sending vehicle telemetry over gRPC.
   - `gateway/main.go` is the ingestion entrypoint; it accepts binary gRPC traffic and converts it into asynchronous stream events.
   - The gateway is the system’s decoupling point between low-latency edge ingestion and downstream processing.

4. **Event backbone: Kafka**
   - The README identifies Kafka topic `raw_positions` as the central stream.
   - The topic is partitioned, and the gateway distributes messages using vehicle-based hashing so related events stay ordered by `vehicle_id`.
   - This enables independent scaling of consumers and separates ingestion from processing/storage latency.

5. **Stream processing / CEP subsystem: `processor`**
   - `processor/main.go` is the real-time analytics and control-plane service.
   - It consumes from Kafka as its own consumer group, which means it can evolve independently from storage.
   - This component is the “live” view layer: it likely maintains in-memory state for fleet tracking and computes operational insights before serving them to users.

6. **User-facing visualization boundary**
   - The processor also serves `processor/index.html`, which is the browser dashboard.
   - The README describes a Leaflet.js-based map and WebSocket updates, so the processor bridges stream state to the UI in near real time.
   - This is the only directly user-facing runtime in the architecture.

7. **Persistence subsystem: `storage-worker`**
   - `storage-worker/main.go` is the durable sink consumer.
   - It reads the same Kafka topic via a separate consumer group, so persistence is isolated from live analytics.
   - Its job is to transform stream records into PostgreSQL rows for history, audit, and reporting.

8. **Durable store: PostgreSQL**
   - PostgreSQL is used for permanent telemetry history.
   - The README indicates a `fleet_telemetry` database accessed with application credentials, implying the storage worker owns the write path.
   - This separates operational stream traffic from queryable long-term storage.

9. **Infrastructure and local orchestration**
   - `docker-compose.yml` provisions the supporting infrastructure: Kafka, PostgreSQL, and Kafdrop for Kafka inspection.
   - This makes the pipeline runnable locally as a multi-service system rather than a monolith.
   - The repository is therefore organized around runtime boundaries more than shared application code.

10. **Build/tooling boundaries**
   - The Go services are independent modules (`gateway`, `processor`, `storage-worker` each have their own `go.mod`), which reinforces service-level deployment.
   - `gateway` also includes Buf configuration (`buf.yaml`, `buf.gen.yaml`), indicating Protobuf code generation is part of the build workflow.
   - The Python simulator is separate from the Go runtime, emphasizing polyglot integration through the gRPC contract.

11. **Primary end-to-end data flow**
   - Telemetry originates in the simulator.
   - It enters the gateway over gRPC, is serialized into Kafka events, then fans out to two consumers:
     - processor for real-time tracking/UI,
     - storage-worker for PostgreSQL persistence.
   - This is the main architecture diagram axis: edge ingestion → event bus → parallel downstream consumers.

12. **Architectural takeaway**
   - The main design pattern is event-driven fan-out with clear separation of concerns.
   - Ingestion, live analytics, and persistence are intentionally decoupled so each can scale or fail independently.
   - For an architecture diagram, the key boundaries are: simulator, gRPC gateway, Kafka topic/consumer groups, processor/UI, storage worker, and PostgreSQL.

Main entry points: [`gateway/proto/telemetry.proto`](https://github.com/nirodhauwanpriya/fleet-tracking-platform/blob/main/gateway/proto/telemetry.proto) (Telemetry proto), [`docker-compose.yml`](https://github.com/nirodhauwanpriya/fleet-tracking-platform/blob/main/docker-compose.yml) (Kafka), [`gateway/main.go`](https://github.com/nirodhauwanpriya/fleet-tracking-platform/blob/main/gateway/main.go) (Gateway), [`processor/main.go`](https://github.com/nirodhauwanpriya/fleet-tracking-platform/blob/main/processor/main.go) (Processor)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_contract["Contract"]
  node_node_sim_pb2["Py bindings<br/>protobuf stubs<br/>[telemetry_pb2.py]"]
  node_node_sim_pb2_grpc["Py gRPC<br/>grpc stubs"]
  node_node_telemetry_proto["Telemetry proto<br/>contract<br/>[telemetry.proto]"]
  node_node_go_pb["Go bindings<br/>protobuf stubs<br/>[telemetry.pb.go]"]
  node_node_go_grpc["Go gRPC<br/>grpc stubs"]
  node_node_buf_yaml["Buf config<br/>codegen config<br/>[buf.yaml]"]
  node_node_buf_gen["Buf gen<br/>codegen config<br/>[buf.gen.yaml]"]
end

subgraph group_group_runtimes["Runtimes"]
  node_node_simulator["Simulator<br/>python emitter<br/>[sim.py]"]
  node_node_gateway["Gateway<br/>ingestion service<br/>[main.go]"]
  node_node_processor["Processor<br/>stream analytics<br/>[main.go]"]
  node_node_dashboard["Dashboard<br/>web UI<br/>[index.html]"]
  node_node_storage_worker["Storage worker<br/>sink consumer<br/>[main.go]"]
end

subgraph group_group_infra["Infrastructure"]
  node_node_kafka[("Kafka<br/>event bus<br/>[docker-compose.yml]")]
  node_node_raw_positions["raw_positions<br/>topic"]
  node_node_postgres[("PostgreSQL<br/>durable store<br/>[docker-compose.yml]")]
  node_node_docker_compose["Compose stack<br/>local orchestration<br/>[docker-compose.yml]"]
end

node_node_simulator -->|"uses"| node_node_sim_pb2_grpc
node_node_simulator -->|"implements"| node_node_telemetry_proto
node_node_telemetry_proto -->|"generates"| node_node_go_pb
node_node_telemetry_proto -->|"generates"| node_node_go_grpc
node_node_telemetry_proto -->|"generates"| node_node_sim_pb2
node_node_telemetry_proto -->|"generates"| node_node_sim_pb2_grpc
node_node_buf_yaml -.->|"configures"| node_node_telemetry_proto
node_node_buf_gen -.->|"generates"| node_node_go_pb
node_node_gateway -->|"uses"| node_node_go_grpc
node_node_gateway -->|"publishes"| node_node_kafka
node_node_kafka -->|"hosts"| node_node_raw_positions
node_node_gateway -->|"writes"| node_node_raw_positions
node_node_raw_positions -->|"consumed by"| node_node_processor
node_node_raw_positions -->|"consumed by"| node_node_storage_worker
node_node_processor -->|"serves"| node_node_dashboard
node_node_processor -->|"subscribes"| node_node_kafka
node_node_storage_worker -->|"persists"| node_node_postgres
node_node_docker_compose -.->|"provisions"| node_node_kafka
node_node_docker_compose -.->|"provisions"| node_node_postgres

click node_node_simulator "https://github.com/nirodhauwanpriya/fleet-tracking-platform/blob/main/simulator/sim.py"
click node_node_sim_pb2 "https://github.com/nirodhauwanpriya/fleet-tracking-platform/blob/main/simulator/telemetry_pb2.py"
click node_node_sim_pb2_grpc "https://github.com/nirodhauwanpriya/fleet-tracking-platform/blob/main/simulator/telemetry_pb2_grpc.py"
click node_node_telemetry_proto "https://github.com/nirodhauwanpriya/fleet-tracking-platform/blob/main/gateway/proto/telemetry.proto"
click node_node_go_pb "https://github.com/nirodhauwanpriya/fleet-tracking-platform/blob/main/gateway/telemetry.pb.go"
click node_node_go_grpc "https://github.com/nirodhauwanpriya/fleet-tracking-platform/blob/main/gateway/telemetry_grpc.pb.go"
click node_node_gateway "https://github.com/nirodhauwanpriya/fleet-tracking-platform/blob/main/gateway/main.go"
click node_node_kafka "https://github.com/nirodhauwanpriya/fleet-tracking-platform/blob/main/docker-compose.yml"
click node_node_processor "https://github.com/nirodhauwanpriya/fleet-tracking-platform/blob/main/processor/main.go"
click node_node_dashboard "https://github.com/nirodhauwanpriya/fleet-tracking-platform/blob/main/processor/index.html"
click node_node_storage_worker "https://github.com/nirodhauwanpriya/fleet-tracking-platform/blob/main/storage-worker/main.go"
click node_node_postgres "https://github.com/nirodhauwanpriya/fleet-tracking-platform/blob/main/docker-compose.yml"
click node_node_docker_compose "https://github.com/nirodhauwanpriya/fleet-tracking-platform/blob/main/docker-compose.yml"
click node_node_buf_yaml "https://github.com/nirodhauwanpriya/fleet-tracking-platform/blob/main/gateway/buf.yaml"
click node_node_buf_gen "https://github.com/nirodhauwanpriya/fleet-tracking-platform/blob/main/gateway/buf.gen.yaml"

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_node_sim_pb2,node_node_sim_pb2_grpc,node_node_telemetry_proto,node_node_go_pb,node_node_go_grpc,node_node_buf_yaml,node_node_buf_gen toneBlue
class node_node_simulator,node_node_gateway,node_node_processor,node_node_dashboard,node_node_storage_worker toneAmber
class node_node_kafka,node_node_raw_positions,node_node_postgres,node_node_docker_compose toneMint
```

## Components

### Contract

Shared telemetry schema and generated bindings

- [Py bindings](https://github.com/nirodhauwanpriya/fleet-tracking-platform/blob/main/simulator/telemetry_pb2.py): protobuf stubs · Python client bindings generated from the telemetry contract · `simulator/telemetry_pb2.py`
- [Py gRPC](https://github.com/nirodhauwanpriya/fleet-tracking-platform/blob/main/simulator/telemetry_pb2_grpc.py): grpc stubs · Python gRPC service bindings for the simulator side · `simulator/telemetry_pb2_grpc.py`
- [Telemetry proto](https://github.com/nirodhauwanpriya/fleet-tracking-platform/blob/main/gateway/proto/telemetry.proto): contract · Shared gRPC/Protobuf schema for telemetry exchange · `gateway/proto/telemetry.proto`
- [Go bindings](https://github.com/nirodhauwanpriya/fleet-tracking-platform/blob/main/gateway/telemetry.pb.go): protobuf stubs · Go bindings generated from the telemetry contract · `gateway/telemetry.pb.go`
- [Go gRPC](https://github.com/nirodhauwanpriya/fleet-tracking-platform/blob/main/gateway/telemetry_grpc.pb.go): grpc stubs · Go gRPC service bindings for the gateway · `gateway/telemetry_grpc.pb.go`
- [Buf config](https://github.com/nirodhauwanpriya/fleet-tracking-platform/blob/main/gateway/buf.yaml): codegen config · Protobuf build configuration for the gateway service · `gateway/buf.yaml`
- [Buf gen](https://github.com/nirodhauwanpriya/fleet-tracking-platform/blob/main/gateway/buf.gen.yaml): codegen config · Protobuf generation settings for Go bindings · `gateway/buf.gen.yaml`

### Runtimes

Core services that ingest, process, visualize, and persist telemetry

- [Simulator](https://github.com/nirodhauwanpriya/fleet-tracking-platform/blob/main/simulator/sim.py): python emitter · Synthesizes fleet telemetry and sends it over gRPC · `simulator/sim.py`
- [Gateway](https://github.com/nirodhauwanpriya/fleet-tracking-platform/blob/main/gateway/main.go): ingestion service · Accepts gRPC telemetry and publishes normalized events to Kafka · `gateway/main.go`
- [Processor](https://github.com/nirodhauwanpriya/fleet-tracking-platform/blob/main/processor/main.go): stream analytics · Consumes telemetry for live tracking and near-real-time control logic · `processor/main.go`
- [Dashboard](https://github.com/nirodhauwanpriya/fleet-tracking-platform/blob/main/processor/index.html): web UI · Browser map and live updates served by the processor · `processor/index.html`
- [Storage worker](https://github.com/nirodhauwanpriya/fleet-tracking-platform/blob/main/storage-worker/main.go): sink consumer · Consumes telemetry and writes durable records to PostgreSQL · `storage-worker/main.go`

### Infrastructure

Supporting event bus and durable storage

- [Kafka](https://github.com/nirodhauwanpriya/fleet-tracking-platform/blob/main/docker-compose.yml): event bus · Central topic backbone for raw telemetry fan-out · `docker-compose.yml`
- **raw_positions**: topic · Partitioned telemetry stream keyed to preserve vehicle ordering
- [PostgreSQL](https://github.com/nirodhauwanpriya/fleet-tracking-platform/blob/main/docker-compose.yml): durable store · Persistent fleet telemetry database · `docker-compose.yml`
- [Compose stack](https://github.com/nirodhauwanpriya/fleet-tracking-platform/blob/main/docker-compose.yml): local orchestration · Brings up Kafka, PostgreSQL, and inspection tooling locally · `docker-compose.yml`

## Connections

- Simulator → Py gRPC: uses · Simulator calls the generated Python gRPC client surface
- Simulator → Telemetry proto: implements · Simulator produces messages defined by the shared telemetry schema
- Telemetry proto → Go bindings: generates · Telemetry schema generates Go message bindings
- Telemetry proto → Go gRPC: generates · Telemetry schema generates Go service bindings
- Telemetry proto → Py bindings: generates · Telemetry schema generates Python message bindings
- Telemetry proto → Py gRPC: generates · Telemetry schema generates Python service bindings
- Buf config → Telemetry proto: configures · Buf configuration governs contract compilation
- Buf gen → Go bindings: generates · Buf generation produces Go protobuf artifacts
- Gateway → Go gRPC: uses · Gateway uses generated Go gRPC server bindings
- Gateway → Kafka: publishes · Gateway serializes inbound telemetry into Kafka events
- Kafka → raw_positions: hosts · Kafka carries the raw telemetry topic
- Gateway → raw_positions: writes · Gateway produces partitioned raw position events
- raw_positions → Processor: consumed by · Processor reads the topic in its own consumer group
- raw_positions → Storage worker: consumed by · Storage worker reads the topic independently for persistence
- Processor → Dashboard: serves · Processor serves the browser dashboard and live updates
- Processor → Kafka: subscribes · Processor consumes telemetry from Kafka for live tracking
- Storage worker → PostgreSQL: persists · Storage worker writes telemetry history to PostgreSQL
- Compose stack → Kafka: provisions · Compose brings up Kafka for local runs
- Compose stack → PostgreSQL: provisions · Compose brings up PostgreSQL for local runs
