Architecture

modular               — código dividido em módulos coesos com fronteiras definidas
MVC                   — separação em Model, View e Controller
Clean Architecture    — camadas concêntricas com domínio no centro
Hexagonal (Ports & Adapters) — domínio isolado de infraestrutura por adaptadores
Monólito modular      — único processo com módulos internos bem delimitados
Microserviços         — serviços independentes por domínio ou capacidade
Frontend + Backend    — cliente desacoplado do servidor com contrato explícito
BFF (Backend for Frontend) — camada de orquestração entre interface e serviços
Event-driven          — comunicação por eventos com desacoplamento temporal
Híbrido               — combinação de estilos por camada ou domínio

Nome do projeto:
Versão do documento:
Status: [rascunho | revisando | aprovado]
Documentos base: Docs/project.md, Docs/stack.md, Docs/user-stories.md, Docs/entities.md
Data de criação:
Última atualização:

Resumo arquitetural:          [como o sistema é organizado em poucas linhas]
Estilo arquitetural adotado:  [modular | Clean | hexagonal | BFF | event-driven | híbrido]
Justificativa da escolha:     [por que esse estilo faz sentido para este projeto]
Estratégia de evolução:       [começar simples e modularizar | preparado para escala | etc.]

Separação de responsabilidades — [o que significa aqui]
Baixo acoplamento              — [o que significa aqui]
Alta coesão                    — [o que significa aqui]
Testabilidade                  — [o que significa aqui]
Evolução incremental           — [o que significa aqui]
Contratos explícitos           — [o que significa aqui]
Infraestrutura isolada         — [o que significa aqui]

Tipo de sistema:    [web app | api | admin | worker | plataforma | SaaS | interno]
Partes principais:
  - frontend
  - backend
  - banco de dados
  - fila (quando houver)
  - cache (quando houver)
  - workers (quando houver)
  - integrações externas
  - painel administrativo (quando houver)
Visão macro: [como as partes conversam entre si]

Responsabilidade: [descreva]
Inclui:
  - páginas
  - componentes
  - formulários
  - navegação
  - interação com usuário
Não deve conter:
  - regra de negócio complexa
  - acesso direto à infraestrutura
  - lógica de persistência

Responsabilidade: [descreva]
Inclui:
  - casos de uso
  - orquestração
  - validação de entrada
  - coordenação entre domínio e infraestrutura
Não deve conter:
  - detalhes de banco
  - dependência forte de framework
  - regras visuais

Responsabilidade: [descreva]
Inclui:
  - entidades
  - regras centrais do negócio
  - invariantes
  - serviços de domínio (quando necessário)
Não deve conter:
  - detalhes de transporte
  - detalhes de persistência
  - dependência de framework ou interface

Responsabilidade: [descreva]
Inclui:
  - banco de dados e ORM
  - serviços externos
  - cache
  - fila
  - storage
  - providers
Não deve conter:
  - regra central de negócio espalhada
  - decisões funcionais de interface

### Módulo N — [nome]
 
Objetivo:                [descreva]
Responsabilidades:
  - [responsabilidade 1]
  - [responsabilidade 2]
Entidades relacionadas:  [ENT-001, ENT-002]
Casos de uso principais:
  - [caso 1]
  - [caso 2]
Dependências internas:   [módulo A, módulo B]
Dependências externas:   [integração X]
Observações:             [preencher]

Fluxo principal:
1. Interface recebe ação do usuário
2. Camada de aplicação valida entrada e orquestra o caso de uso
3. Camada de domínio aplica regras de negócio
4. Infraestrutura persiste ou consulta dados
5. Integrações externas são acionadas, se necessário
6. Resultado retorna estruturado à interface
 
Pontos críticos do fluxo:
  - [ponto 1: onde mais falhas ocorrem]
  - [ponto 2: onde consistência é crítica]
  - [ponto 3: onde latência impacta UX]

Integrações previstas:
  - [integração 1: função]
  - [integração 2: função]
 
Regras de isolamento:
  - integrações ficam na camada de infraestrutura
  - domínio não conhece detalhes de integração externa
  - falha de integração deve ser tratada — nunca propagada sem handling
 
Riscos arquiteturais:
  - [risco 1: o que pode falhar e como mitigar]

Estratégia de persistência:  [descreva]
Fonte principal de verdade:  [qual banco é a source of truth]
Necessidades de consistência:
  - consistência imediata:   [onde é necessário]
  - consistência eventual:   [onde é tolerada]
  - auditoria:               [quais operações precisam de log]
  - idempotência:            [quais operações devem ser idempotentes]
  - concorrência:            [onde locks ou filas são necessários]
Cuidados relevantes:
  - [cuidado 1]
  - [cuidado 2]

Padrão principal:     [REST | eventos | fila | RPC | GraphQL | interno]
Síncrona:             [como frontend fala com backend, como módulos se chamam]
Assíncrona:           [quais operações usam fila ou eventos]
Eventos/mensagens previstos:
  - [evento 1]
  - [evento 2]
Regras de comunicação:
  - [regra 1: ex.: toda resposta tem envelope padrão]
  - [regra 2: ex.: erros de integração têm retry com backoff]

Escalabilidade esperada: [baixa | média | alta | progressiva]
Partes com maior chance de crescimento:
  - [parte 1]
Partes que devem permanecer simples:
  - [parte 1]
Estratégia de evolução arquitetural: [descreva]
Sinais que indicariam refatoração futura:
  - [sinal 1: ex.: latência de módulo ultrapassando SLA]
  - [sinal 2: ex.: módulo com mais de N responsabilidades]

Pontos sensíveis da arquitetura:
  - autenticação
  - autorização e RBAC
  - dados sensíveis (criptografia, mascaramento)
  - integrações externas (tokens, secrets)
  - arquivos (upload, acesso)
  - logs (sem dados PII)
  - ações destrutivas (confirmação, auditoria)
 
Regras arquiteturais de segurança:
  - [regra 1]
  - [regra 2]
 
Áreas que exigem atenção extra:
  - [área 1]

Necessidades operacionais:
  - logs estruturados
  - health checks
  - métricas de performance
  - alertas por SLA
  - rastreabilidade de requisição
 
Pontos que devem ser observáveis:
  - [ponto 1]
 
Falhas que precisam ser rastreáveis:
  - [falha 1]

Restrições assumidas:
  - [restrição 1: ex.: monólito por prazo — poderá ser modularizado na fase 2]
 
Trade-offs aceitos conscientemente:
  - [trade-off 1: ganho X vs custo Y]
 
Alternativas consideradas e não adotadas:
  - [alternativa 1 + motivo de rejeição]

Docs/entities.md   → como o domínio influencia módulos e regras internas
Docs/contract.yaml → como a arquitetura expõe ou consome contratos
Docs/structure.md  → como a arquitetura se reflete em diretórios e camadas
Docs/deploy.md     → como a arquitetura impacta ambientes e pipeline
Docs/plan.md       → quais partes arquiteturais orientam a ordem de implementação

Obrigatório:
  - [diretriz 1: ex.: toda lógica de negócio na camada de domínio]
  - [diretriz 2: ex.: toda integração isolada na infraestrutura]
  - [diretriz 3: ex.: nenhum módulo acessa banco de outro módulo diretamente]
 
A evitar:
  - [erro 1: ex.: regra de negócio espalhada em handlers de rota]
  - [erro 2: ex.: chamada direta de infraestrutura na camada de interface]
 
Exige atualização deste documento:
  - novo módulo estrutural
  - mudança de responsabilidade entre camadas
  - nova integração crítica
  - mudança de padrão de comunicação

Estilo arquitetural:                [resumo]
Módulos principais:                 [lista]
Regras estruturais que não quebram: [lista]
Pontos críticos da arquitetura:     [lista]
O que ainda está indefinido:        [ponto 1]

Status: [pendente | aprovado | revisando]
Aprovado por:
Data de aprovação:
Observações finais:

## Visão Geral (exemplo)
 
Resumo: Sistema mobile + API REST com autenticação JWT.
Frontend mobile (React Native) consome API backend (NestJS).
Backend modular por domínio — cada domínio tem controller, service e repository.
Banco PostgreSQL via Prisma. Storage S3 para arquivos. Push via Firebase.
 
Estilo: Monólito modular com separação em camadas.
Justificativa: Time pequeno, prazo restrito, modularização interna
permite escalar para microserviços se necessário.
 
---
 
## Módulo: Atendimentos
 
Objetivo: Gerenciar o ciclo de vida dos chamados de campo.
Responsabilidades:
  - Criar, atualizar e encerrar chamados
  - Registrar atendimento com foto e assinatura
  - Notificar gestor no encerramento
Entidades: Chamado (ENT-002), Atendimento (ENT-003)
Casos de uso:
  - Técnico registra atendimento
  - Gestor valida ou rejeita atendimento
Dependências internas: Módulo Auth (autenticação), Módulo Notificações
Dependências externas: S3 (upload de foto), Firebase (push de notificação)

## Resumo arquitetural
[como o sistema é organizado em poucas linhas]
 
## Estilo arquitetural
[modular | clean | mvc | monólito modular | híbrido]
 
## Princípios
- separação de responsabilidades
- baixo acoplamento
- testabilidade
 
## Camadas
Interface:      [responsabilidade]
Aplicação:      [responsabilidade]
Domínio:        [responsabilidade]
Infraestrutura: [responsabilidade]
 
## Módulos principais
### [nome]
Objetivo: [preencher]
Responsabilidades: [item 1]
 
## Fluxo técnico principal
1. [passo 1]
2. [passo 2]
3. [passo 3]
 
## Integrações externas
- [integração: função]
 
## Persistência
[estratégia principal]
 
## Comunicação
Síncrona:   [preencher]
Assíncrona: [preencher]
 
## Restrições e trade-offs
- [trade-off]
 
## Direção para os próximos documentos
Docs/contract.yaml: [orientação]
Docs/structure.md:  [orientação]
Docs/deploy.md:     [orientação]
 
## Síntese para Dev e AI
Arquitetura: [resumo]
Regras obrigatórias: [regra]
Pontos críticos: [ponto]
O que está indefinido: [ponto]

Atue como SystemAgent.
Objetivo: criar Docs/architecture.md com base em Docs/stack.md e Docs/entities.md
 
Carregue contexto base:
- GUIDE.md
- Skills/implementation.md
- Templates/Full/architecture.md
- Docs/stack.md
- Docs/entities.md
- Docs/project.md
 
Preencha as 19 seções do template Full.
Seção 3: defina estilo arquitetural com justificativa baseada no stack e contexto.
Seção 6: descreva cada camada com o que inclui e o que não deve conter.
Seção 7: crie um módulo por domínio identificado em entities.md seção 4.
Seção 8: descreva o fluxo técnico passo a passo.
Seção 15: registre trade-offs assumidos e alternativas descartadas.
Seção 17: diretrizes obrigatórias de implementação.
Marque [indefinido] onde a decisão ainda depende de prototipagem ou discovery.

Docs/architecture.md (aprovado)
    ↓
Docs/contract.yaml  — endpoints e schemas derivados dos módulos e camadas
Docs/structure.md   — organização de diretórios refletindo camadas e módulos
Docs/deploy.md      — pipeline e ambientes alinhados à arquitetura
Docs/tasks.md       — tasks de implementação por módulo, na ordem correta