Architecture Decision Records
· 2 min read
This directory contains Architecture Decision Records (ADRs) for the CTA Public Transport Optimisation system. ADRs are generated by reverse-engineering the codebase as of 2026-03-12.
Index
| ADR | Title | Status |
|---|---|---|
| ADR-001 | Apache Kafka as the Central Event Bus | Accepted |
| ADR-002 | Avro Schemas + Confluent Schema Registry | Accepted |
| ADR-003 | Kafka Connect JDBC Source for PostgreSQL | Accepted |
| ADR-004 | Dual Stream Processing — Faust + KSQL | Accepted |
| ADR-005 | Kafka REST Proxy for Weather Producer | Accepted |
| ADR-006 | Tornado Async Web Server for Dashboard | Accepted |
System Architecture Overview
┌─────────────────────────────────────────────────────────────────────┐
│ PRODUCER LAYER │
│ │
│ simulation.py │
│ ├─ Line (Blue/Red/Green) │
│ │ ├─ Station ──────────────────► org.chicago.cta.station. │
│ │ │ (AvroProducer) arrivals.t001 │
│ │ └─ Turnstile ─────────────────► com.cta.stations. │
│ │ (AvroProducer) turnstile.entry │
│ └─ Weather ──────────────────────► org.chicago.cta.weather.v1 │
│ (REST Proxy HTTP POST) │
│ │
│ connector.py ──[JDBC Source]──► com.cta.stations.data.rawt001. │
│ (Kafka Connect) stations (from PostgreSQL) │
└────────────────────────────┬────────────────────────────────────────┘
│ Apache Kafka (+ Schema Registry)
┌────────────────────────────▼────────────────────────────────────────┐
│ STREAM PROCESSING LAYER │
│ │
│ faust_stream.py │
│ com.cta.stations.data.rawt001.stations │
│ ──[transform]──► org.chicago.cta.stations.table.v1t001 │
│ │
│ ksql.py │
│ com.cta.stations.turnstile.entry │
│ ──[GROUP BY station_id]──► TURNSTILE_SUMMARY (JSON) │
└────────────────────────────┬────────────────────────────────────────┘
│
┌────────────────────────────▼────────────────────────────────────────┐
│ CONSUMER / DASHBOARD LAYER │
│ │
│ server.py (Tornado, port 8888) │
│ KafkaConsumer × 4 ──► in-memory Weather + Lines state │
│ GET / ──► status.html │
└─────────────────────────────────────────────────────────────────────┘
Key Technology Choices
| Concern | Technology | ADR |
|---|---|---|
| Event streaming | Apache Kafka (Confluent 5.2.2) | ADR-001 |
| Schema enforcement | Apache Avro + Confluent Schema Registry | ADR-002 |
| DB-to-Kafka ingestion | Kafka Connect JDBC Source | ADR-003 |
| Station transformation | Faust (Python stream processor) | ADR-004 |
| Turnstile aggregation | KSQL | ADR-004 |
| HTTP-based produce path | Kafka REST Proxy | ADR-005 |
| Real-time web dashboard | Tornado async web server | ADR-006 |
| Infrastructure | Docker Compose (single-broker dev cluster) | ADR-001 |