Modulo 6.4: Documento de Arquitetura

Download do Template

Template completo de Arquitetura em Markdown. Inclui stack, padroes, modelos e especificacoes de API.

📐 Arquitetura como Blueprint

O documento de arquitetura e o blueprint tecnico completo do projeto. Cada decisao de tecnologia, cada padrao, cada API esta aqui. Desenvolvedores e IAs consultam este documento para garantir consistencia.

O que o Documento Define

• Stack tecnologico com versoes exatas

• Padroes arquiteturais obrigatorios

• Modelos de dados e relacionamentos

• Especificacoes de API (OpenAPI)

• Estrutura de pastas e organizacao

• Regras de seguranca e validacao

💡 Por que isso importa para IA

Quando a IA gera codigo, ela DEVE seguir este blueprint. Sem ele, cada geracao e uma loteria de padroes inconsistentes.

📦 Tech Stack Table

Liste TODAS as tecnologias com versoes especificas. "Node.js" nao e suficiente. "Node.js 20.11.0 LTS" e. Versoes exatas evitam surpresas de compatibilidade.

Exemplo de Tech Stack Table

Camada	Tecnologia	Versao	Justificativa
Runtime	Node.js	20.11.0 LTS	Suporte longo prazo, estavel
Framework	Next.js	14.1.0	App Router, Server Components
Database	PostgreSQL	16.1	JSONB, indices parciais
ORM	Prisma	5.8.0	Type-safe, migrations

⚠️ Evite

"Use a versao mais recente" - isso cria inconsistencia entre ambientes. Sempre fixe versoes.

🧱 Padroes Arquiteturais

Documente os padroes escolhidos com justificativa. Repository Pattern, Dependency Injection, CQRS - estes padroes sao LEI para a IA seguir.

Repository Pattern

Abstrai acesso a dados em interfaces

Justificativa: Facilita testes e troca de ORM

Dependency Injection

Injeta dependencias via construtor

Justificativa: Testabilidade e desacoplamento

Clean Architecture

Camadas com dependencias unidirecionais

Justificativa: Separacao de responsabilidades

Event-Driven

Comunicacao via eventos assincronos

Justificativa: Escalabilidade e desacoplamento

🗃️ Modelos de Dados

Defina entidades, atributos e relacionamentos. Use diagramas Mermaid para visualizacao. Este modelo guia a criacao de banco de dados e APIs.

Estrutura de Entidade

// User Entity

id: UUID (PK)
email: string (unique, indexed)
password_hash: string
created_at: timestamp
updated_at: timestamp

Chaves

PK, FK, indices

Tipos

UUID, string, int, timestamp

Constraints

NOT NULL, UNIQUE, CHECK

🔌 API Specification

Documente endpoints em formato OpenAPI/Swagger. Request/response schemas, codigos de erro, autenticacao. A IA usara isso para gerar codigo consistente.

Exemplo de Endpoint

POST /api/v1/users

Request Body:

{"{ email: string, password: string }"}

Responses:

201: User created successfully

400: Validation error

409: Email already exists

💡 Dica

Use ferramentas como Swagger UI para visualizar e testar sua API spec antes de implementar.

📁 Estrutura de Pastas

Defina onde cada tipo de arquivo vai. Controllers em /controllers, services em /services, etc. Consistencia e auditabilidade dependem disso.

Estrutura Tipica

src/
├── app/                  # Routes e pages (Next.js)
├── components/           # React components
│   ├── ui/              # Componentes genericos
│   └── features/        # Componentes de dominio
├── lib/                  # Bibliotecas e utilidades
├── services/            # Business logic
├── repositories/        # Data access layer
├── types/               # TypeScript types/interfaces
├── hooks/               # Custom React hooks
└── utils/               # Funcoes auxiliares

🔒 Seguranca

Documente estrategias de validacao, autenticacao, autorizacao e gestao de secrets. Seguranca nao e opcional.

Autenticacao

• JWT com refresh tokens
• Expiracao: 15min access, 7d refresh
• HTTP-only cookies para tokens

Autorizacao

• RBAC (Role-Based Access Control)
• Middleware de verificacao
• Permissoes granulares

Validacao

• Zod para schema validation
• Sanitizacao de inputs
• Rate limiting em endpoints

Secrets

• .env para desenvolvimento
• Vault/KMS para producao
• Nunca commitar secrets

📝 Padrao de Codigo

Regras criticas que a IA DEVE seguir. "Nunca use any", "Sempre valide input", "Use prepared statements". Seja especifico e inequivoco.

Regras Obrigatorias

NUNCA Use 'any' em TypeScript - sempre defina tipos

NUNCA Concatene strings em queries SQL - use prepared statements

SEMPRE Valide todos os inputs antes de processar

SEMPRE Use async/await em vez de callbacks

SEMPRE Trate erros com try/catch e logging apropriado

📝 Resumo do Modulo

✓Blueprint Tecnico - Documento que governa toda geracao de codigo

✓Tech Stack - Versoes exatas de todas as tecnologias

✓Padroes - Repository, DI, Clean Architecture com justificativas

✓API Spec - Endpoints documentados em formato OpenAPI

✓Regras de Codigo - NUNCA/SEMPRE que a IA deve seguir

Pronto para arquitetar? ⬇️ Baixar Template

← PRD Proximo: User Stories →