Skip to main content

API Centralizada do SuperApp CPTM

🚀 Introdução​

Esta API atua como camada intermediária entre clientes (Web/Mobile) e serviços da CPTM. Utiliza Fastify, TypeScript, Redis, PostgreSQL, Prisma e Docker para oferecer uma solução robusta, escalável e segura.

  • 🧱 Fastify + TypeScript – framework performático com tipagem forte.
  • 🧠 Redis – armazena o JWT da autenticação com a CPTM.
  • 🐘 PostgreSQL + Prisma – persistência dos dados extraídos do GTFS.
  • 📦 Docker + docker-compose – containerização e orquestração dos serviços.
  • ♻ Makefile – automatiza rotinas de desenvolvimento, deploy e manutenção.
  • 🧩 Arquitetura modular – separa routes, services, domain, helpers e types para mais clareza e manutenção.

🗂️ Estrutura do Repositório​

api_cptm/
├─ prisma/
│  ├─ migrations/
│  └─ schema.prisma
├─ src/
│  ├─ domain/
│  ├─ helpers/
│  ├─ routes/
│  ├─ services/
│  ├─ types/
│  ├─ api.ts
│  └─ db.ts
├─ Dockerfile
├─ docker-compose.yml
├─ Makefile
├─ .env
├─ tsconfig.json
└─ package.json

🏗️ Comandos com Makefile​

Todos os comandos de build, deploy, testes e manutenção estão encapsulados no Makefile:

PROJECT_NAME=fastify-api

up:
	docker compose up -d --build
	docker exec -it fastify-api npx prisma migrate reset
	docker exec -it fastify-api npx prisma generate

down:
	docker compose down -v

restart: down up

logs:
	docker compose logs -f

build:
	docker compose build

bash:
	docker compose exec api bash

redis-cli:
	docker compose exec redis redis-cli

prune:
	docker system prune -af && docker volume prune -f

force-kill:
	sudo docker rm -f fastify-redis || true

reset:
	sudo systemctl restart docker || true

migrate:
	docker exec -it fastify-api npx prisma migrate reset

generate:
	docker exec -it fastify-api npx prisma generate

Principais comandos​

  • make up – sobe containers, aplica migrations (reset) e gera Prisma Client.
  • make down – derruba containers e volumes.
  • make restart – reinicia todo o stack.
  • make logs – exibe logs em tempo real.
  • make build – builda containers.
  • make bash – abre shell dentro do container da API.
  • make redis-cli – abre prompt do Redis.
  • make prune – limpa containers, imagens e volumes não usados.
  • make migrate – aplica migrations via Prisma dentro do container.
  • make generate – gera Prisma Client.

⚙️ Inicialização Completa​

# Ajuste variáveis no .env (String Postgres)

# Subir ambiente completo:
make up

# Visualizar logs:
make logs

# Acessar shell da API:
make bash

# Reduzir snapshots antigos:
make prune

🔐 Autenticação​

  • authService.ts gera e gerencia o JWT da CPTM.
  • Redis armazena token com TTL.
  • Requisições subsequentes reutilizam JWT.
  • Quando expira, serviço reautentica automaticamente.

📡 Endpoints (exemplos)​

GET /linhas​

Retorna as linhas com suas respectivas estações:

[
	{
		"linhaNumero": 13,
		"linhaNome": "Linha 13 Jade",
		"empresa": "CPTM",
		"estacoes": [
			{
				"id": 155,
				"nome": "Aeroporto - Guarulhos",
				"acessivel": true,
				"bicicletario": false,
				"linhaNumero": 13,
				"linhaNome": "Linha 13 Jade",
				"empresa": "CPTM"
			},
			{
				"id": 157,
				"nome": "Engº. Goulart",
				"acessivel": true,
				"bicicletario": true,
				"linhaNumero": 13,
				"linhaNome": "Linha 13 Jade",
				"empresa": "CPTM"
			},
			{
				"id": 156,
				"nome": "Guarulhos - CECAP",
				"acessivel": true,
				"bicicletario": false,
				"linhaNumero": 13,
				"linhaNome": "Linha 13 Jade",
				"empresa": "CPTM"
			}
		]
	}
]

POST /gtfs/import​

Importa da API da CPTM salva o conteúdo dos gtfs de Schedule no banco de dados

Outros endpoints seguem padrão similar.

🔄 Ingestão e Consulta dos Dados GTFS​

  • Scripts executados off‑line processam arquivos GTFS (CSV).
  • Dados salvos no PostgreSQL via Prisma.
  • Endpoints fazem consultas offline, melhorando latência e resiliência.

🛡️ Segurança & Middleware​

  • Validação com JSON Schema / Fastify.
  • Rate limiting configurável.
  • Queries parametrizadas com Prisma – mitigação de SQL Injection.
  • Limites de request para proteção contra DDoS.

📈 Resiliência & Performance​

  • Cache de token e consultas frequentes no Redis.
  • Suporte a execução em cluster (pm2 / Kubernetes).
  • Logs estruturados para monitoramento.
  • Fácil integração com sistemas de monitoramento (Prometheus, etc.).

🧪 Organização de Código​

MóduloFunção Principal
domain/Tipagens e regras de domínio
routes/Definições das rotas e validações
services/Conexões com CPTM, DB e lógica
helpers/Parser GTFS, utils Redis/JWT
types/DTOs e Interfaces customizadas
db.tsInicialização do Prisma Cliente
api.tsInstancia Fastify, plugins e rotas

🎯 Scripts via package.json​

  • npm run dev – inicia Fastify em modo dev com reload.
  • npm run build – transpila TS para JS.
  • npm run start – executa build compilado.
  • npm run migrate – executa migrations Prisma.
  • npm run generate – gera Prisma Client.

👥 Como Contribuir​

  1. Fork do repositório.
  2. Crie feature branch (feature/*).
  3. Implemente testes (Jest + Fastify inject).
  4. Adicione/atualize migrações (caso necessário).
  5. Abra PR com descrição, screenshots, testes.

Referências​

📎 Resumo​

Esta API é um facade seguro e eficiente que:

  1. Faz mediação entre cliente e CPTM.
  2. Armazena GTFS offline para consulta rápida.
  3. Usa containerização e automação via Makefile.
  4. Assegura segurança, performance e manutenibilidade.

💡 Próximos passos:

  • Documentar via OpenAPI/Swagger.
  • Monitoramento com dashboards.
  • Implementar Load Balancer
  • Pipelines CI/CD integradas aos comandos Makefile.