Real-time bus tracking for CityBus of Greater Lafayette, Indiana — Telegram bot, REST API, MCP server, and background worker.

# Clone & install
git clone https://github.com/<you>/citybus-bot.git && cd citybus-bot
python3 -m venv venv && source venv/bin/activate
pip install -r requirements.txt

# Configure
cp .env.example .env   # edit: set TELEGRAM_BOT_TOKEN, MONGO_URI, REDIS_URL

# Run (pick one or all)
python main_bot.py          # Telegram bot
python main_api.py          # REST API → http://localhost:8000/docs
python main_worker.py       # Background worker (GTFS-RT → Redis → notifications)
python -m citybus.mcp.server  # MCP server (for LM Studio / AI assistants)

• Architecture & Design Details
• Deployment Guide

Note on Registration: All users must register a unique alphanumeric username (3-15 characters) via the /start command before they can search or track stops.

Admin (Telegram IDs in ADMIN_IDS config): /admin_stats, /admin_users, /admin_errors, /admin_broadcast, /debug

CityBus provides a fully interactive REST API. You can explore all available endpoints, view schemas, and test requests directly from your browser using the built-in Swagger UI.

Access the UI here:
👉 http://localhost:8000/docs

To use the API (both in Swagger and your own apps), you need an API key. You can generate one instantly via the /signup endpoint.

Run this command in your terminal:

curl -X POST http://localhost:8000/api/v1/auth/signup \
     -H "Content-Type: application/json" \
     -d '{"owner": "my-cool-app"}'

The response will contain your unique api_key:

{
  "owner": "my-cool-app",
  "api_key": "cb_a1b2c3d4e5f6...",
  "rate_limit": "100/minute",
  "message": "Save your API key! Include it as 'X-API-Key' header in all requests."
}

1. Open http://localhost:8000/docs in your browser.
2. Click the green Authorize button at the top right.
3. Paste the api_key you generated into the X-API-Key field and click Authorize.
4. You can now expand any endpoint (e.g., /api/v1/search) and click "Try it out" to test it right in the browser!

Admin endpoints (/admin/*) require a master key. In the Swagger UI Authorize menu, paste your MongoDB ADMIN_API_KEY into the X-Admin-Key field to unlock these routes.

The simplest way to run CityBus Tracker is via the pre-built Docker image. You only need two files: docker-compose.yml and .env.

Ensure you have the docker-compose.yml and .env.example (renamed to .env) in the same directory.

Edit your local .env file with your specific credentials:

• TELEGRAM_BOT_TOKEN, MONGO_URI, REDIS_URL.

Run the following command. Docker will automatically pull the image and inject your .env secrets into the containers:

docker-compose up -d

The application uses a hybrid configuration model. Foundational settings are required to boot the app, while Dynamic settings can be updated at runtime without a restart by modifying the config collection in MongoDB.

These can also be set in .env as initial fallbacks.

MIT