Arquitetura

Por que esta arquitetura existe

O GovON nasceu para resolver problemas recorrentes em sistemas publicos municipais: falta de isolamento entre prefeituras que compartilham infraestrutura, ausencia de trilha de auditoria por padrao, controle de acesso ad-hoc, exposicao de dados sensiveis em listagens, e uso de IA sem rastreabilidade.

• Isolamento por municipio — cada prefeitura opera como tenant isolado. Vazamento cross-tenant e tratado como bug critico de seguranca.
• Seguranca por padrao — JWT, revogacao em segundos, default-deny em permissoes, HTTPS obrigatorio.
• Auditoria automatica — toda mutacao gera registro imutavel. Atende Lei de Acesso a Informacao, TCE/TCU, CGU, LGPD.
• Permissoes nomeadas — formato dominio.recurso.acao. Granular sem virar ABAC complexo.
• Dados sensiveis com politica LGPD — CPF, CNPJ, email mascarados em listagens. Retencao declarada por campo.
• IA governada — toda chamada de modelo exige permissao + gera log com hash do prompt. Texto bruto nao persiste.
• Modulos reutilizaveis — cada area (protocolo, tributos, atendimento) entra como modulo isolado com contrato unico.
• Integracao com sistemas publicos — base preparada para gov.br, SERPRO, e-CAC, sistemas legados municipais. Toda integracao externa exige conector com retry + log + audit.

Fluxo de uma requisicao

Usuario / Servidor publico
  |
  v
Admin (Next.js) / Web
  |
  v  HTTPS + Bearer JWT
API NestJS
  |
  v
TenantMiddleware (verifica JWT, valida sessionVersion + permissionVersion, abre TenantContext)
  |
  v
PermissionGuard (consome @RequirePermission)
  |
  v
Controller (camada HTTP fina)
  |
  v
Service Layer (regra de negocio)
  |
  v
PrismaService tenant-aware -> PostgreSQL
  |
  +-> AuditInterceptor    -> AuditLog (Postgres)
  +-> Redis (sessao + cache + filas)
  +-> JobRunner            -> BullMQ -> Worker dedicado
  +-> GovernedAI (futuro)  -> driver LLM + AIRequestLog

Camadas da arquitetura

O que ja esta ativo em runtime

• Login JWT (POST /auth/login) com bcrypt
• sessionVersion por usuario: logout invalida tokens antigos em segundos
• permissionVersion por perfil: alteracao de permissoes invalida tokens existentes
• TenantContext via AsyncLocalStorage propaga municipio em toda chain async
• PermissionGuard global aplica @RequirePermission com default-deny
• AuditInterceptor grava AuditLog imutavel em toda mutacao
• PrismaService exige tenant ativo (lanca ForbiddenError sem contexto)
• Cache de revogacao em Redis (AWS ElastiCache, TLS + auth + KMS) com fallback Prisma
• Swagger protegido por Basic Auth em /docs
• GET /health/runtime verifica latencia de DB e Redis
• Site de documentacao publico (este aqui)
• Modulo Protocolo MVP entregue (primeiro modulo de negocio em runtime)
• Schema Protocolo, Movimentacao e Anexo aplicado no RDS Postgres (sa-east-1) via migration 20260513200000_add_protocolo
• Rotas /protocolo protegidas por JWT + PermissionGuard (default-deny; GET/POST sem token devolvem 401)
• Admin UI com lista, criacao e detalhe de protocolo (apps/admin/src/app/protocolos)
• Mascara LGPD aplicada em CPF do requerente em listagens, detalhe e logs de auditoria (@govon/mask)
• Suite E2E do Protocolo criada (tests/e2e/protocolo.spec.ts) + 13 testes unitarios do ProtocoloService

O que ainda e demo / parcial

• API rodando via ts-node --transpile-only (cold start +200ms; compilacao definitiva planejada no roadmap)
• Upload usa LocalFileStorage em disco; driver S3 implementado em @govon/upload, ainda nao plugado por padrao no modulo Protocolo
• Worker BullMQ do Protocolo deployed como ECS Fargate Service (govon-demo-worker) e consumindo a fila protocolo.notificar do ElastiCache Redis.
• Driver S3 (@govon/upload com S3Storage) implementado, bucket govon-demo-uploads criado com KMS encryption + Block Public Access. LocalFileStorage mantido como driver para dev local.
• Nenhum dado real: 2 municipios ficticios (Cidade Demo Alpha / Cidade Demo Beta)
• Nenhum cliente real conectado
• Sem rate limit nativo (futuro: Cloudflare ou @nestjs/throttler)
• Driver de IA real ainda nao plugado (contrato pronto em @govon/ai)
• Sem integracao externa real (contrato pronto em @govon/integrations)

Acessos da demo

Stack

• Monorepo: Turborepo + npm workspaces
• Backend: NestJS 10 + Prisma 5 + PostgreSQL (AWS RDS)
• Frontend: Next.js 14 + Tailwind + shadcn/ui
• Cache + filas: Redis (AWS ElastiCache, TLS + KMS) + BullMQ
• Linguagem: TypeScript strict ponta a ponta
• Testes: Vitest (unit) + Playwright (E2E)
• Hospedagem: AWS sa-east-1 — ECS Fargate (api + admin + worker), RDS Postgres, ElastiCache Redis, S3 + CloudFront (docs estaticos + TLS API/Admin), ALB + WAF, Secrets Manager, KMS, CloudTrail, AWS Backup

ADRs (decisoes arquiteturais)

Decisoes formais em docs/architecture/:

• 0001 — Monorepo Turborepo
• 0002 — Multi-tenant por municipio
• 0003 — Auditoria obrigatoria por entidade
• 0004 — RBAC com permissoes nomeadas
• 0005 — Padrao de resposta HTTP
• 0006 — Contrato de modulo
• 0007 — TenantContext via AsyncLocalStorage
• 0008 — IA governada
• 0009 — BaseConnector (integracoes externas)
• 0010 — Runtime activation (PrismaModule + AuditInterceptor + JWT)
• 0011 — Revogacao via sessionVersion + permissionVersion
• 0012 — Identidade visual: shell estilo Angular com paleta vermelho-shield
• 0013 — Migracao para AWS sa-east-1 (Railway+Neon+Upstash → ECS+RDS+ElastiCache)
• 0014 — S3 como storage de uploads do Protocolo (substitui LocalFileStorage em producao)