🚌 Infobús

Comprehensive real-time public transportation information system for Costa Rica

Infobús is a modern Django-based platform that processes GTFS Schedule and Realtime feeds to deliver live transit information across multiple channels. Designed for Universidad de Costa Rica (UCR), it provides real-time passenger information through digital displays at bus stops and stations, APIs, and web interfaces.

🔍 Overview

Infobús is a production-ready, containerized platform that transforms raw GTFS transit data into accessible, real-time information for passengers across Costa Rica. The system processes multiple data sources and delivers information through various channels including digital displays, mobile apps, and web interfaces.

Key Capabilities

🚍 Real-time Transit Updates: Live arrival/departure information from GTFS Realtime feeds
📺 Digital Display Network: Geographic screen management with PostGIS integration
🔄 Live Data Streaming: WebSocket-powered real-time updates to connected devices
🏢 Multi-agency Support: Unified platform for multiple transit providers
🌦️ Weather Integration: Location-based weather information for displays
📱 Social Media Integration: Curated transit-related social content
🆘 Emergency Alerts: CAP (Common Alerting Protocol) integration for critical updates

✨ Features

🏭 Production Infrastructure

Containerized Deployment: Docker-based dev/production environments
Scalable Architecture: Nginx reverse proxy with load balancing ready
High Availability: Redis-backed caching and session management
Security Hardened: Rate limiting, security headers, and container isolation
Monitoring Ready: Health check endpoints and structured logging

📡 Real-time Data Processing

GTFS Realtime Integration: Vehicle positions, trip updates, and service alerts
Background Task Processing: Celery-powered async data collection
Geospatial Analysis: PostGIS-enabled location-based services
Data Validation: Robust data quality checks and error handling
Multi-source Aggregation: Unified data from various transit agencies

🖥️ Display Management

Geographic Screen Positioning: GPS-coordinated display locations
Dynamic Content Rendering: Context-aware information display
WebSocket Live Updates: Real-time screen content synchronization
Kiosk Mode Support: Raspberry Pi deployment optimizations
Responsive Design: Multi-device and screen size support

🛠️ Technology Stack

🔋 Backend & APIs

Django 5.2+: Modern Python web framework with GeoDjango/PostGIS
Django REST Framework: RESTful API development
Django Channels: WebSocket support for real-time features
Daphne ASGI Server: Production-ready async server
Python 3.12+: Latest Python with modern async support

📊 Data & Storage

PostgreSQL 16: Primary database with ACID compliance
PostGIS 3.4: Advanced geospatial data processing
Redis 7: High-performance caching and message broker
Docker Volumes: Persistent data storage

🚪 Infrastructure & Deployment

Docker & Docker Compose: Containerized development and production
Nginx: Reverse proxy with security headers and rate limiting
Multi-stage Builds: Optimized container images
uv: Fast Python package management

🌐 Real-time & Background Processing

Celery: Distributed task processing
Celery Beat: Periodic task scheduling
WebSockets: Live data streaming to displays
GTFS Realtime: Transit data processing bindings

🔒 Security & Monitoring

Environment-based Config: Secure secrets management
Rate Limiting: API and admin protection
Security Headers: OWASP recommended protections
Health Checks: Application and service monitoring

🚀 Quick Start

Prerequisites

Docker Desktop (Download)
Git (Download)
8GB+ RAM recommended for all services

🛠️ Development Setup (Recommended)

Clone the repository bash git clone https://github.com/simovilab/infobus.git cd infobus
Initialize submodules bash git submodule update --init --recursive
Start development environment bash ./scripts/dev.sh

This single command will: - 📦 Build all Docker containers - 💾 Set up PostgreSQL with PostGIS - 🔄 Start Redis for caching - ⚙️ Run database migrations - 👥 Create admin user (admin/admin) - 🌐 Launch the development server with hot reload

Access the application
Website: http://localhost:8000
Admin Panel: http://localhost:8000/admin (admin/admin)
API: http://localhost:8000/api/

🏭 Production Deployment

Configure production environment bash # Copy and edit production settings cp .env.prod.example .env.prod # Generate a secure SECRET_KEY python -c "from django.core.management.utils import get_random_secret_key; print(get_random_secret_key())"
Start production environment bash ./scripts/prod.sh

Production includes: - 🌐 Nginx reverse proxy with SSL-ready config - 🛡️ Security headers and rate limiting - 📊 Performance optimizations and caching - 🔍 Health check endpoints

Access production
Website: http://localhost (via Nginx)
Admin: http://localhost/admin
Health Check: http://localhost/health/

📝 Common Commands

# View logs
docker-compose logs -f

# Run Django commands
docker compose exec web uv run python manage.py migrate
docker compose exec web uv run python manage.py createsuperuser
docker compose exec web uv run python manage.py shell

# Run tests
docker compose exec web uv run python manage.py test

# Stop all services
docker compose down

🏧 Architecture

📊 Service Architecture

🌐 Internet → 🚪 Nginx (Port 80) → 🐍 Django/Daphne (Port 8000)
                                          ↓
                                   💾 PostgreSQL (PostGIS)
                                          ↓
                                   🔴 Redis ← 🐝 Celery Workers/Beat

🔄 Data Flow

📡 Data Collection: Celery tasks periodically fetch GTFS Realtime feeds from transit agencies
⚙️ Data Processing: Information is validated, processed, and classified by screen relevance
📶 Real-time Distribution: Django Channels WebSockets push live updates to connected displays
🖥️ Display Rendering: Raspberry Pi devices in kiosk mode render the passenger information

💱 Application Structure

website: Main site pages, user management, and public interfaces
alerts: Screen management, real-time data display via WebSockets
gtfs: GTFS Schedule and Realtime data management (submodule: django-app-gtfs)
feed: Information service providers and WebSocket consumers
api: RESTful API endpoints with DRF integration

📚 API Documentation

REST API Endpoints

/api/ - Main API endpoints with DRF browsable interface
/api/gtfs/ - GTFS Schedule and Realtime data
/api/alerts/ - Screen management and alert systems
/api/weather/ - Weather information for display locations

WebSocket Endpoints

/ws/alerts/ - Real-time screen updates
/ws/feed/ - Live transit data streaming

🛠️ Development

Project Structure

infobus/
├── 📁 scripts/          # Management scripts (dev.sh, prod.sh)
├── 📁 nginx/            # Nginx configuration
├── 📁 datahub/          # Django project settings
├── 📁 website/          # Main web application
├── 📁 alerts/           # Display and alert management
├── 📁 gtfs/             # GTFS data processing (submodule)
├── 📁 feed/             # Data feed management
├── 📁 api/              # REST API endpoints
├── 📦 docker-compose.yml              # Development environment
├── 📦 docker-compose.production.yml   # Production environment
├── 📄 Dockerfile         # Multi-stage container build
└── 📄 WARP.md           # AI assistant guidance

Environment Configuration

.env - Base configuration (committed)
.env.dev - Development overrides (committed)
.env.prod - Production template (committed, no secrets)
.env.local - Local secrets (git-ignored)

Contributing

Fork the repository
Create a feature branch: git checkout -b feature/amazing-feature
Make your changes and test with ./scripts/dev.sh
Run security scan: gitleaks detect --source . --verbose
Commit your changes: git commit -m 'Add amazing feature'
Push to the branch: git push origin feature/amazing-feature
Open a Pull Request

🏢 Production Deployment

Deployment Options

☁️ Cloud Platforms: AWS, GCP, Azure with Docker
🖥️ VPS Deployment: Ubuntu/CentOS with Docker Compose
🥰 Raspberry Pi: Kiosk mode for display devices
💻 Local Development: Full-featured local environment

Security Checklist

[ ] Generate secure SECRET_KEY in production
[ ] Update database passwords
[ ] Configure domain names in ALLOWED_HOSTS
[ ] Set up SSL certificates
[ ] Configure backup strategy
[ ] Set up monitoring and logging
[ ] Test health check endpoints

💫 Support & Community

Getting Help

Documentation: See WARP.md for detailed guidance
Scripts: Use ./scripts/dev.sh --help for command help
Health Checks: Monitor /health/ endpoint in production
Logs: Use docker-compose logs -f for troubleshooting

Universidad de Costa Rica (UCR) | Laboratorio SIMOVI | Costa Rica