Fases 4 e 5 — Arquitetura e modelo de aplicação (S)

Fase 4 — Arquitetura e decisões técnicas

Objetivo

Definir a solução técnica antes e durante a construção, mantendo decisões registradas e vinculadas às necessidades. ARC trata descoberta, concepção e decisões arquiteturais antes e durante a construção — ver ARC — Arquitetura.

Artefatos

Artefato	Conteúdo mínimo
SDD/TDD	Arquitetura, componentes, integrações, fluxos, dados, segurança, implantação
ADR	Decisões arquiteturais relevantes, alternativas avaliadas, justificativa
Diagrama de contexto	Sistemas, usuários, integrações, fronteiras
Diagrama de componentes	Módulos, serviços, APIs, banco, filas, integrações
Modelo de dados	Entidades, relacionamentos, retenção, sensibilidade
Contrato de API	OpenAPI/Swagger, autenticação, payloads, erros
Threat model simplificado	Ameaças, riscos, controles
Plano de observabilidade	Logs, métricas, rastreamento, auditoria

Decisões que exigem ADR

Decisão	Exige ADR?
Linguagem ou framework principal	Sim
Banco de dados	Sim
Padrão de autenticação/autorização	Sim
Arquitetura monolítica, modular ou microsserviços	Sim
Integração com sistema crítico	Sim
Uso de IA em funcionalidade do sistema	Sim
Tratamento de dados pessoais relevante	Sim
Mudança de arquitetura durante sprint	Sim
Biblioteca utilitária simples	Não, salvo impacto relevante

Uso de IA

A IA pode sugerir arquitetura, comparar alternativas, gerar rascunho de ADR, criar diagramas em Mermaid/PlantUML, revisar riscos, sugerir padrões de segurança e gerar contratos OpenAPI iniciais. Decisões arquiteturais relevantes exigem validação técnica humana, em linha com o validador técnico previsto pelo SinergIA para temas de segurança, arquitetura, infraestrutura, gates de produção e mudanças arquiteturais relevantes.

Gate 4 — Arquitetura aprovada

Critério	Evidência
Arquitetura documentada	SDD/TDD
Decisões relevantes registradas	ADRs
Integrações descritas	Diagrama e OpenAPI
Dados mapeados	Modelo de dados
Segurança considerada	Threat model/checklist
Observabilidade definida	Plano de logs/métricas
Validação técnica	Registro formal

---

Fase 5 — Modelo de aplicação: ferramentas, configurações e técnicas

Esta é a camada que traduz o framework em operação prática. O ponto central é:

O SinergIA não escolhe a ferramenta. Ele define as condições para que a ferramenta seja usada com rastreabilidade, validação, evidência, controle e supervisão humana.

Mapa de ferramentas por finalidade

Finalidade	Ferramentas possíveis	Como o SinergIA baliza
Ideação e negócio	ChatGPT, Claude, Gemini, NotebookLM	Saída vira rascunho; validação humana obrigatória
Prototipação	Figma, Lovable, v0, Uizard	Protótipo vira evidência vinculada a história
Codificação assistida	Cursor, Claude Code, GitHub Copilot, Codex	Código deve derivar de especificação e passar por PR/gates
Gestão de backlog	Jira, Azure DevOps, GitHub Projects	História precisa de requisito, critério, teste e evidência
Documentação	Markdown/Git, Confluence, GitBook, Docusaurus	Documento versionado e rastreável
Repositório	GitHub, GitLab, Bitbucket, Azure Repos	Branch, PR, revisão e rastreabilidade obrigatórios
CI/CD	GitHub Actions, GitLab CI, Azure Pipelines, Jenkins	Build, teste e análise devem gerar evidência
Análise estática	SonarQube, SonarCloud, Semgrep	Quality gate antes de merge/release
Dependências	Dependabot, Snyk, Trivy, OWASP Dependency-Check	Vulnerabilidades bloqueiam ou geram exceção justificada
Testes unitários	Jest, Vitest, JUnit, PyTest	Cobertura mínima conforme criticidade
Testes E2E	Playwright, Cypress, Selenium	Fluxos críticos automatizados
DAST	OWASP ZAP, Burp Suite Enterprise	Teste em ambiente de homologação
Observabilidade	Grafana, Prometheus, Elastic, OpenTelemetry	Evidência pós-release
ITSM/sustentação	GLPI, Jira Service Management, ServiceNow, BMC Helix	Mudanças, incidentes e problemas vinculados à release

Configuração mínima recomendada

Repositório Git

Configuração	Recomendação
Branch principal	main ou master protegida
Branch de desenvolvimento	develop, se o fluxo exigir
Branch por história	feature/HNU-001-descricao-curta
PR obrigatório	Sim
Merge direto na principal	Vedado
Revisão humana	Mínimo 1 revisor técnico
Build obrigatório	Sim
Testes obrigatórios	Sim
Sonar/qualidade	Sim
Scan de dependências	Sim
Vinculação a história	Obrigatória no PR

Pull Request

Todo PR deve conter:

## História vinculada
HNU-001

## Requisitos vinculados
REQ-001, RN-001

## Casos de teste vinculados
CT-001, CT-002, CT-003

## Evidências
- Build: link
- Testes unitários: link
- Testes E2E: link
- SonarQube: link
- Evidência funcional: link

## Uso de IA
- Ferramenta utilizada:
- Finalidade:
- Trechos gerados ou revisados:
- Revisão humana realizada:

## Riscos
- [ ] Sem mudança arquitetural
- [ ] Sem impacto em dados pessoais
- [ ] Sem nova dependência crítica

Pipeline mínimo

commit/pull request
  → lint
  → build
  → testes unitários
  → testes de integração
  → análise estática
  → scan de dependências
  → validação de cobertura
  → publicação de relatório
  → aprovação de PR
  → merge
  → deploy em homologação
  → testes E2E
  → DAST quando aplicável
  → evidência de aceite
  → deploy controlado

---

Anterior: Fases 1–3 · Próximo: Fases 6–9