Cotral

Monorepo per il trasporto pubblico Cotral: server API + bot Telegram + bot Discord

Panoramica

Stack completo per consultare il trasporto pubblico Cotral (Lazio): un server API che unifica i dati GTFS offline e le API XML Cotral in tempo reale, più due bot (Telegram e Discord) che lo consumano.

Pacchetti

Pacchetto	Descrizione
@cotral/server	API REST Fastify. GTFS come fonte primaria, API Cotral per real-time, SQLite per i preferiti
@cotral/telegram-bot	Bot Telegram (Telegraf) con menu inline, preferiti, transiti real-time
@cotral/discord-bot	Bot Discord (discord.js) con slash commands, autocomplete e select menu
@cotral/shared	Tipi TypeScript e utility condivise tra i pacchetti

Prerequisiti

• Node.js >= 18.x
• npm >= 8.x (workspaces)
• Per il deploy in container: Docker + Docker Compose

Installazione

git clone https://github.com/ChromuSx/cotral.git
cd cotral
npm install      # installa le dipendenze di tutti i workspace

Configurazione

Ogni pacchetto ha il proprio .env (gitignored). Vedi i README dei singoli pacchetti per le variabili specifiche:

• @cotral/server
• @cotral/telegram-bot
• @cotral/discord-bot

Per il deploy con Docker, le credenziali vivono in un .env nella root usato da docker-compose.yml:

TELEGRAM_BOT_TOKEN=...
DISCORD_BOT_TOKEN=...
DISCORD_CLIENT_ID=...
ALLOWED_USER_IDS=...
DISCORD_ALLOWED_USER_IDS=...

Sviluppo locale (senza Docker)

npm run build                    # build di tutti i workspace
npm run start:server             # avvia il server (porta 3000)
npm run start:telegram-bot       # in un altro terminale
npm run start:discord-bot        # in un altro terminale
npm run deploy-commands:discord  # registra/aggiorna gli slash commands su Discord

Build del singolo workspace:

npm run build:shared
npm run build:server
npm run build:telegram-bot
npm run build:discord-bot

Avvio con Docker

Stack completo (server + entrambi i bot):

docker compose up -d --build

Caratteristiche:

• server espone l'API su localhost:3001 (mappato sul 3000 interno)
• telegram-bot e discord-bot parlano col server tramite la rete interna del compose
• Tutti i container girano in Europe/Rome (TZ impostato sia in docker-compose.yml che nel Dockerfile con tzdata)
• Volumi nominati per persistenza GTFS / SQLite / sessioni Telegram

Test

npm test                       # esegue i test di tutti i workspace
npm run test:server
npm run test:telegram-bot
npm run test:discord-bot

Struttura del repository

cotral/
├── packages/
│   ├── shared/          # tipi e util condivise
│   ├── server/          # API REST
│   ├── telegram-bot/    # bot Telegram
│   └── discord-bot/     # bot Discord
├── Dockerfile           # multi-stage: build comune + 3 immagini finali
├── docker-compose.yml   # stack server + bot
└── package.json         # workspaces npm

Licenza

MIT — vedi LICENSE.

Autore

Giovanni Guarino — @ChromuSx