Skip to content

Databús

Databús is a distributed GTFS transit-data platform. It ingests live vehicle telemetry over MQTT, maintains authoritative real-time state in Redis, computes vehicle progress against scheduled trips through server-side map-matching, and publishes standards-compliant GTFS Realtime feeds — alongside durable traces and analytics.

Work in Progress

Both Databús and its documentation are under active development. The estimated release date is August 2026. Pages describe the system as built today; where the legacy AGENTS.md / MODEL.md design docs disagree with the source, these docs follow the source.

How it fits together

flowchart LR
    veh["🚌 Vehicles"] -->|MQTT position/occupancy| broker["telemetry-broker<br/>(NanoMQ)"]
    broker --> rt["realtime-engine<br/>(Celery worker + MQTT bootstep)"]
    rt -->|authoritative state| redis[("state<br/>(Redis)")]
    rt -->|durable traces| db[("database<br/>(PostgreSQL/PostGIS)")]
    redis --> se["schedule-engine<br/>(Celery worker)"]
    se -->|GTFS Realtime .pb/.json| feed["feed/files/"]
    orch["orchestrator<br/>(Django HTTP API)"] -->|run commands| redis
    orch --> db
    se -->|status push| ui["user-interface<br/>(Nuxt)"]
    feed --> consumers["External GTFS-RT consumers"]

The MQTT consumer runs as a Celery bootstep inside the realtime-engine worker, not as a separate process. GTFS Realtime feeds are built by the schedule-engine, not a standalone "publisher." See Architecture → Services for the full, corrected service map.

Start here

  • Concepts

    What Databús is, GTFS Schedule vs Realtime, the glossary, and the design principles behind the system.

    Concepts

  • Architecture

    The service topology as built — Django apps and Celery workers, messaging model, and state & persistence.

    Architecture

  • Data flow

    The end-to-end path: telemetry ingestion → server-side processing → map-matching → GTFS Realtime publishing.

    Data flow

  • Run lifecycle

    The run state machine, commands vs detected facts, the detection layer, and stale-run scanning.

    Run lifecycle

  • Data model

    The canonical Redis key reference, telemetry contracts, Django models, and the schedule engine.

    Data model

  • Interfaces

    REST API, the MQTT telemetry contract, AMQP event semantics, GTFS Realtime feeds, and the URL directory.

    Interfaces

  • Operations

    Local development, configuration, Celery workers and beat, production deployment, and troubleshooting.

    Operations

Databús is developed by the SIMOVI Lab at the University of Costa Rica (UCR). Source: github.com/simovilab/databus.