API do Gym Study, uma plataforma de estudos gamificada para quem estuda tecnologia. Ela recebe as sessões de estudo e transforma cada uma em XP, ofensiva, badges com níveis, conquistas, ligas semanais e ranking. Também cuida da parte social: amigos, feed, stories, grupos e desafios.
O processamento pesado roda fora da requisição: XP, badges, conquistas, notificações e e-mails passam por filas BullMQ no Redis, e rotinas como virada da liga, reset de XP semanal e quebra de ofensiva rodam em cron jobs.
O front que consome esta API é o gym-study-front.
| Prefixo | O que faz |
|---|---|
/api/auth |
Cadastro, login, refresh e logout (JWT) |
/api/users |
Perfil, edição e avatar |
/api/study-sessions |
Registro de sessões e estatísticas |
/api/certifications, /api/goals |
Certificações e metas de estudo |
/api/xp, /api/streak, /api/quests |
XP e nível, ofensiva com freeze, missões do dia |
/api/badges, /api/achievements |
Badges com níveis e conquistas |
/api/leagues, /api/ranking |
Ligas semanais (Bronze → Diamante) e rankings |
/api/feed, /api/stories |
Posts, curtidas, comentários e stories |
/api/friendships, /api/groups, /api/challenges |
Amigos, grupos de estudo e desafios |
/api/gems |
Moeda do app e loja |
/api/articles, /api/recommendations |
Artigos e recomendações entre usuários |
/api/github |
Conexão com o GitHub e sync de contribuições |
/api/public |
Perfil público e verificação de badges, sem login |
/health |
Health check |
A documentação interativa fica em /docs (Swagger UI), gerada de docs/openapi.yaml.
| Tipo | Tarefa |
|---|---|
| Fila (BullMQ) | XP, badges, conquistas, notificações, e-mails e sync do GitHub |
| Cron | Ofensivas (meia-noite), ranking (1h), limpeza (3h), missões do dia (0h05), reset de XP e promoção de liga (segunda), resumo semanal por e-mail |
29 migrations SQL em src/database/migrations, aplicadas automaticamente na subida da API e registradas na tabela schema_migrations.
- Node.js 20 + Express + TypeScript: API REST;
- Socket.io + adapter Redis: tempo real, pronto para várias instâncias;
- PostgreSQL 16 (
pg): banco relacional, com SQL puro; - Redis 7 (
ioredis) + BullMQ: cache e filas; - MinIO (
@aws-sdk/client-s3): armazenamento dos avatares, compatível com S3; - Zod: validação das requisições e das variáveis de ambiente;
- JWT + bcrypt: autenticação;
- Nodemailer + Handlebars: e-mails;
- Helmet, CORS e rate limit: segurança;
- Jest + Supertest: testes;
- Docker + GitHub Actions: imagem publicada no GitHub Container Registry.
gym-study-back/
├── src/
│ ├── modules/<módulo>/ # routes, controllers, services, validators
│ ├── database/migrations/ # 001 a 029 (.sql)
│ ├── jobs/ # Cron jobs
│ ├── shared/queue/ # Filas e workers BullMQ
│ ├── websocket/ # Socket.io
│ ├── config/ # Ambiente, banco, Redis, storage
│ ├── app.ts # Express
│ └── server.ts # Migrations + HTTP + Socket.io
├── docs/
│ ├── openapi.yaml # Especificação da API
│ ├── api-demo.gif # Demonstração no Swagger UI
│ └── arch.gif # Diagrama da arquitetura
├── scripts/seed-demo.mjs # Dados de exemplo
├── tests/
├── docker-compose.yml # PostgreSQL + Redis para desenvolvimento
├── Dockerfile
└── README.md
- O usuário faz login em
POST /api/auth/logine recebe um JWT. - Ao terminar de estudar, o front envia
POST /api/study-sessions. - A API grava a sessão, soma as horas e atualiza a ofensiva.
- XP, badges e conquistas são calculados em segundo plano pelas filas BullMQ.
- O XP da semana define a posição na liga e no ranking.
- Conquistas e novidades chegam ao front pelo Socket.io.
- Toda segunda-feira, os cron jobs promovem os primeiros da liga e zeram o XP semanal.
A stack completa (front, API, banco, Redis e MinIO) sobe pelo gym-study-infra.
Só a API:
cp .env.example .env # troque o JWT_SECRET
docker compose up -d # PostgreSQL e Redis
npm install
npm run dev # http://localhost:5000/docs
node scripts/seed-demo.mjs # usuários e dados de exemploLogin de demonstração: ana@gymstudy.dev / Demo1234.
Em uma validação end-to-end, registrar uma sessão de estudo deve aumentar o XP do usuário e mudar a posição dele no ranking.
Pontos principais de validação:
GET /healthrespondendo200;- migrations aplicadas na primeira subida, com o banco vazio;
POST /api/auth/registerePOST /api/auth/logindevolvendo o token;POST /api/study-sessionsrespondendo201;GET /api/xp/memostrando o XP novo alguns segundos depois;GET /api/ranking/weeklyeGET /api/leagues/currentcom a posição atualizada;/docsabrindo o Swagger UI;npm testpassando (com o Redis dodocker composeno ar).
| Repositório | Camada |
|---|---|
| gym-study-front | Web app (Next.js) |
| gym-study-back | API (Express + PostgreSQL + Redis) |
| gym-study-infra | Stack completa com Docker Compose |
William Alves Coelho · @willtechdev

