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
💡 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
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
💡 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.