Files

Matheus (Handix) 44510bd019 Bootstrap EDEN: Fase 0 (arquitetura) e Fase 1 (monorepo + infra)

Fase 0 — descoberta e arquitetura:
- Inventário do projeto, glossário de domínio, arquitetura com bounded
  contexts e topologia de containers, threat model inicial.
- 12 ADRs cobrindo modular monolith, topologia de containers (Postgres
  isolado + eden-core/parceiros/assinante em containers e portas
  distintos), auth/sessões, modelo de permissões, criptografia/segredos,
  contrato first-class, stock ledger, separação billing/finance/fiscal,
  outbox transacional, adapters SaperX e Focus NFe, e identidade
  compartilhada entre as 3 apps.
- 14 subagentes e 7 skills especializados por domínio em .claude/.
- Hooks de segurança (PreToolUse/PostToolUse/Stop) testados via pipe.

Fase 1 — plataforma (em andamento):
- Monorepo pnpm workspaces + Turborepo: apps/{api,worker,core-web,
  reseller-web,subscriber-web} + 9 packages compartilhados.
- apps/api: NestJS mínimo com /health/live e /health/ready (checando
  Postgres real via @eden/database).
- 3 frontends Vite + React + TypeScript + Tailwind, com o favicon
  oficial do EDEN.
- packages/database: migration baseline (node-pg-migrate) criando
  roles/role_permissions/applications/users/user_applications/sessions/
  audit_log — audit log append-only com hash-chain, testado ao vivo
  (UPDATE/DELETE bloqueados pelo trigger).
- compose.yaml implementando a topologia da ADR-0002, validada de ponta
  a ponta: os 6 containers sobem e ficam saudáveis com um único
  `docker compose up`.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

2026-09-03 08:01:14 -03:00

3.1 KiB

Raw Blame History

ADR-0002: Topologia de containers — Postgres isolado + 1 container por aplicação web

Status

Aceito (decisão explícita do operador)

Contexto

O EDEN tem 3 aplicações web (core-web, reseller-web, subscriber-web) mais a API e um worker assíncrono, além do Postgres 18 exigido pelo Master Prompt (§4.3). O operador determinou explicitamente: o banco de dados deve subir em container separado; eden-core, eden-parceiro e eden-assinantes devem ser containers distintos, cada um em porta própria.

Decisão

Topologia de containers via Docker Compose (um compose.yaml por ambiente — dev/staging/prod usando overrides), com os seguintes serviços:

Serviço	Container	Porta exposta ao host	Fala com Postgres?
`eden-postgres`	Postgres 18	Não (produção) / porta alta não-padrão (dev)	—
`eden-redis`	Redis (quando houver job real)	Não	—
`eden-api`	API principal (NestJS)	`EDEN_API_PORT` (env, default 8080)	Sim — único serviço com credencial de banco
`eden-worker`	Jobs assíncronos (BullMQ)	Não	Sim (mesma credencial de app, escopo próprio se possível)
`eden-core`	Frontend ERP interno	`EDEN_CORE_PORT` (env, default 3001)	Não — só HTTP para `eden-api`
`eden-parceiros`	Frontend portal revenda	`EDEN_PARCEIROS_PORT` (env, default 3002)	Não — só HTTP para `eden-api`
`eden-assinante`	Frontend portal assinante	`EDEN_ASSINANTE_PORT` (env, default 3003)	Não — só HTTP para `eden-api`

Regras adicionais:

Rede docker interna dedicada (eden_net); só a API tem credencial de Postgres — as 3 apps web nunca recebem DATABASE_URL.
Portas configuráveis via .env, nunca hardcoded no compose.yaml, para permitir múltiplas instâncias (dev + staging) na mesma máquina.
healthcheck obrigatório em cada serviço; depends_on usa condition: service_healthy, não apenas ordem de start.
Volume nomeado eden_pgdata para dado do Postgres; nunca bind mount direto de produção sem estratégia de backup validada.
Build multi-stage; imagens de produção sem devDependencies/toolchain de build.
Backup lógico (Master Prompt §6.15) roda a partir do container do worker (ou de um job dedicado), nunca do host diretamente — mantém a regra de "streaming, nunca materializar em disco local" também em containers.

Consequências

Positivo: isolamento de falha por aplicação — um crash no frontend do assinante não derruba o core nem a API.
Positivo: cada app pode escalar/atualizar independentemente (ex.: deploy do eden-assinante sem tocar no eden-core).
Positivo: superfície de acesso ao banco reduzida a um único serviço, simplificando auditoria de acesso a dado.
Negativo: mais serviços para orquestrar/monitorar do que um único container "tudo junto" — mitigado por healthchecks e observabilidade centralizada (Master Prompt §16).
A definir na Fase 1: se eden-core/eden-parceiros/eden-assinante são servidos como SPA estática (nginx) ou com SSR — não muda a topologia de containers, só a imagem base de cada um.

3.1 KiB Raw Blame History