GLC_RFM-0010
ADR 0002proposta2026-04-17

Stack inicial: FastAPI + PocketBase + Next.js

proposta (nao implementada)

ADR 0002 — Stack inicial: FastAPI + PocketBase + Next.js

Data: 2026-04-17 Status: proposta (nao implementada) Contexto: definicao de stack antes de codar a v1.

Decisao

Stack v1:

  • Backend: FastAPI (Python)
  • Banco + Auth: PocketBase
  • Frontend: Next.js + Tailwind + shadcn/ui
  • LLM: Claude API (so onde realmente precisa: classificacao de catalogo)
  • Deploy: Docker Compose + Traefik + Coolify, via docker --context vps-rafael
  • Canal de alerta v1: email (SMTP)

Justificativa por camada (Regras 11-17)

Regra 11 — Banco: PocketBase. Entrega CRUD + Auth + painel admin prontos. Perfeito para v1 (dominio pequeno, <10 entidades). Se a v2/v3 exigir queries analiticas pesadas ou multi-tenant complexo, migra para Postgres — custo de migracao baixo porque o dominio passa por FastAPI, nao por PocketBase direto do frontend.

Regra 12 — Backend: FastAPI. Logica de dominio (classificacao de licencas aplicaveis, calculo de proxima renovacao, regras de alerta) nao cabe em PocketBase direto. FastAPI como camada de dominio deixa o frontend consumindo API estavel enquanto o banco pode trocar por baixo. FastAPI tambem e onde a chamada a Claude API vai viver (com timeout + AbortController).

Regra 13 — Orquestrador: LangGraph. Nao entra na v1. Entra na v2 quando o Workplan virar um fluxo multi-etapa (coleta → validacao → aprovacao → submissao). Na v1 a logica e sequencial simples.

Regra 14 — LLM: Claude API. Usado so onde agrega: ajudar a classificar "quais licencas sao aplicaveis" quando regras simples (CNAE + municipio + vertical) nao bastarem. Fallback: Claude opus como padrao, testar Haiku para custo se volume crescer.

Regra 15 — Frontend: Next.js + Tailwind. Painel dinamico (login, dashboard com semaforo, CRUD). Next.js entrega SSR (SEO futuro + rapidez) e carrega shadcn nativamente.

Regra 16 — UI/UX: shadcn/ui. Componentes prontos (Table, Badge, Dialog, Form). Nao reinventar — entregar rapido com identidade visual padrao.

Regra 17 — Integracoes v1: SMTP apenas. Email para alertas. WhatsApp (Evolution + Chatwoot) e integracao variavel que entra na v2, quando coleta de docs fizer sentido.

Infra (Regras 3, 7, 8, 9, 10)

  • .env e data/ fora do git (Regra 3)
  • Codigo fonte mora local (/home/rafaelcamargo/_rfm/_RFM-0010-GLC_Gestao_Licencas/), containers rodam na VPS via docker --context vps-rafael (Regra 8)
  • Traefik com labels + rede coolify externa (Regra 9)
  • DNS: subdomínio a definir em rafaelcamargo.online (Regra 10). Sugestao: glc.rafaelcamargo.online. Decidir depois quando for deployar.

Alternativas consideradas

Express + Prisma + Postgres. Rejeitada para v1. Mais codigo (schema + migrations + auth manual) e mais lento que PocketBase para MVP. Considerar se v3 exigir queries complexas.

Supabase. Rejeitada. Dependencia de SaaS externo com custo escalonado; PocketBase self-hosted ja cobre o caso em v1 com zero custo.

Django. Rejeitada. Monolitico demais para o recorte em blocos (Regra 1). FastAPI + PocketBase mantem camadas separadas.

Consequencias

Positivas:

  • Stack alinhada com _rfm/CLAUDE.md — zero custo de aprendizado do time
  • Deploy homogeneo com outros projetos _RFM-* (mesma VPS, mesmo Traefik, mesma pipeline)
  • PocketBase encurta tempo ate primeiro painel funcional

Negativas / a monitorar:

  • Dois servicos (PocketBase + FastAPI) em vez de um. Justificavel porque FastAPI e camada de dominio real. Se virasse so repassador, colapsar em PocketBase puro com JS hooks.
  • Multi-tenant no PocketBase depende de collection rules bem feitas. Vira ADR quando for implementar (provavelmente ADR 0004).

Ligacao com as regras

Regras 11, 12, 13, 14, 15, 16, 17 (aplicacao). Regras 3, 7, 8, 9, 10 (infra). Ensaio completo em docs/playbook/regra-11-a-16-aplicacao.md (quando for escrito).