Architecture
Visão Geral da Arquitetura
Arquitetura do sistema Gestão de Município — Monolito Full-Stack TypeScript com Next.js 16.
Visão Geral da Arquitetura
Decisão: Monolito Full-Stack TypeScript
O sistema é um monolito full-stack construído com Next.js 16 (App Router) e TypeScript strict. Essa decisão foi tomada com base em:
- 1 dev + IA, 3 meses MVP — um projeto, uma linguagem = produtividade máxima
- Workflow Designer — React + React Flow = ecossistema imbatível para canvas interativo
- Mobile — Compartilhamento de types, validators e API client com React Native
Diagrama C4 — Container
graph TB
subgraph Clientes
WEB["🖥️ Navegador Desktop<br/>(Servidores Públicos)"]
MOB["📱 App Mobile<br/>(Cidadão)"]
end
subgraph "Next.js Monolito"
SC["Server Components<br/>(CRUD, Listagens)"]
CC["Client Components<br/>(Workflow Designer)"]
SA["Server Actions<br/>(Mutations Web)"]
API["API Routes<br/>(/api/v1/*)"]
end
subgraph Infra
PG["PostgreSQL 16<br/>(Multi-tenant RLS)"]
RD["Redis 7<br/>(Cache)"]
TW["Temporal Workers<br/>(src/temporal/)"]
TS["Temporal Server<br/>(orquestração)"]
end
WEB --> SC
WEB --> CC
CC --> SA
MOB --> API
SC --> PG
SA --> PG
API --> PG
SA --> RD
SA --> TS
TW --> TS
TW --> PG
TW --> RDMulti-Tenancy
Estratégia: Row-Level Security com tenant_id em toda tabela scoped.
- Resolução de tenant via subdomínio ou header
x-tenant-id - Toda query DEVE incluir filtro de
tenantId - Single deploy, single database, múltiplas prefeituras
Camadas da Aplicação
| Camada | Responsabilidade | Localização |
|---|---|---|
| Apresentação | UI, formulários, interações | src/app/, src/components/ |
| Actions | Validação + orquestração | src/server/actions/ |
| Services | Lógica de negócio pura | src/server/services/ |
| Dados | Persistência (Prisma) | src/lib/prisma.ts |
| Background | Workflows e activities Temporal | src/temporal/ |
Fluxo de uma Request
sequenceDiagram
participant U as Usuário
participant SC as Server Component
participant SA as Server Action
participant SV as Service
participant DB as PostgreSQL
U->>SC: Acessa página
SC->>SV: Busca dados (com tenantId)
SV->>DB: SELECT ... WHERE tenant_id = ?
DB-->>SV: Dados
SV-->>SC: Retorna dados
SC-->>U: Renderiza HTML
U->>SA: Submete formulário
SA->>SA: Valida com Zod
SA->>SV: Chama service
SV->>DB: INSERT/UPDATE
DB-->>SV: Confirmação
SV-->>SA: ActionResult
SA-->>U: Redirect ou erro