Databús

A distributed transit data system implementing GTFS Schedule and GTFS Realtime specifications. The system is composed of independent services coordinated via message brokers: a Django control plane, Celery workers for real-time processing and feed generation, MQTT telemetry ingestion, a Nuxt frontend, and Prefect for batch analytics — all orchestrated through Docker Compose.

Architecture

Service	Role	Tech
orchestrator	Control plane, REST API, admin	Django / Daphne (ASGI)
realtime-engine	Processes MQTT telemetry, updates Redis state	Celery worker
schedule-engine	Processes schedules tasks	Celery worker
scheduler	Triggers periodic tasks	Celery Beat
user-interface	Web frontend	Nuxt
database	Durable persistence	PostgreSQL + PostGIS
state	Authoritative real-time state	Redis
message-broker	Async messaging	RabbitMQ
telemetry-broker	Vehicle telemetry ingestion	NanoMQ (MQTT)
analytics-engine	Batch processing and ML	Prefect
task-monitoring	Celery task dashboard	Flower

See ARCHITECTURE.md for detailed service mandates, message semantics, and data flow diagrams. See MODEL.md for functional diagrams and state machine flows.

Getting Started

Prerequisites

• Docker Engine 24+ and Docker Compose v2
• Git

Setup

git clone https://github.com/simovilab/databus.git
cd databus
cp .env.example .env   # edit with your values
./scripts/dev.sh

The startup script initializes Git submodules, pulls images, builds containers, and waits for all services to become healthy. On first run this takes 1–2 minutes.

Development URLs

URL	Description
http://localhost:8000	Orchestrator / API
http://localhost:8000/admin	Django admin
http://localhost:8000/api/	REST API root
http://localhost:8000/api/docs/	API documentation (ReDoc)
http://localhost:3000	Nuxt frontend
http://localhost:15672	RabbitMQ management (guest/guest)
http://localhost:4200	Prefect dashboard
http://localhost:5555	Flower (Celery monitoring)

Common commands

# Logs
docker compose -f compose.dev.yml logs -f              # all services
docker compose -f compose.dev.yml logs -f orchestrator  # single service

# Django management
docker compose -f compose.dev.yml exec orchestrator uv run python manage.py migrate
docker compose -f compose.dev.yml exec orchestrator uv run python manage.py createsuperuser
docker compose -f compose.dev.yml exec orchestrator uv run python manage.py shell
docker compose -f compose.dev.yml exec orchestrator uv run python manage.py loaddata gtfs.json

# Stop
docker compose -f compose.dev.yml down

Code quality

# From backend/
ruff check .
ruff format .
mypy .
pytest

Production Deployment

Production runs on Docker Compose behind a Traefik reverse proxy that handles TLS termination via Let's Encrypt. All HTTP traffic goes through port 443; MQTT through port 8883 (TLS). No services expose ports directly to the host.

Quick start

cp .env.example .env   # add production domains and credentials (see below)
./scripts/prod.sh

Required environment variables

# Domain routing (Traefik)
ORCHESTRATOR_DOMAIN=api.example.com
UI_DOMAIN=app.example.com
MQTT_DOMAIN=mqtt.example.com
RABBITMQ_DOMAIN=rabbitmq.example.com
ANALYTICS_DOMAIN=analytics.example.com
FLOWER_DOMAIN=flower.example.com
DOCS_DOMAIN=docs.example.com
CERT_RESOLVER=letsencrypt

# Credentials
SECRET_KEY=<generate-a-strong-key>
DB_PASSWORD=<strong-password>
REDIS_PASSWORD=<strong-password>
RABBITMQ_USER=databus
RABBITMQ_PASS=<strong-password>

Production services

Service	Domain variable	Description
orchestrator	ORCHESTRATOR_DOMAIN	Django API and admin
user-interface	UI_DOMAIN	Nuxt frontend
telemetry-broker	MQTT_DOMAIN	MQTT over TLS (port 8883)
message-broker	RABBITMQ_DOMAIN	RabbitMQ management UI
analytics-engine	ANALYTICS_DOMAIN	Prefect dashboard
task-monitoring	FLOWER_DOMAIN	Celery Flower
docs	DOCS_DOMAIN	Documentation site (nginx)

Internal-only (not exposed): database, state, realtime-engine, schedule-engine, scheduler.

Common operations

# Rebuild and restart after code changes
docker compose -f compose.prod.yml build orchestrator user-interface
docker compose -f compose.prod.yml up -d orchestrator user-interface

# Django management
docker compose -f compose.prod.yml exec orchestrator uv run python manage.py migrate
docker compose -f compose.prod.yml exec orchestrator uv run python manage.py createsuperuser

# Stop
docker compose -f compose.prod.yml down

Documentation

• ARCHITECTURE.md — Service mandates, message semantics, and design principles
• MODEL.md — Functional diagrams and state machine flows
• HOWTO.md — Step-by-step development environment guide
• docs/development.md — Functional development notes (Spanish)
• docs/deployment.md — Legacy systemd deployment reference
• docs/api.md — API specification and data formats
• docs/obe.md — On-board equipment specifications

Roadmap

SIMOVI's roadmap.

Contributing

See the guidelines.

Contact

• Email: simovi@ucr.ac.cr
• Website: simovi.org

License

Apache 2.0