24 KiB
🚀 AGGIOS - PLATAFORMA SAAS MULTITENANT
Documento Completo de Especificações e Arquitetura
Versão: 1.0
Data: 04/12/2025
Status: Pronto para Desenvolvimento (Code Agent)
📋 Índice
- Visão Geral
- Estrutura de Domínios
- Usuários e Roles
- Módulos Principais
- Modelo de Negócio
- Stack Técnico
- Arquitetura
- Fluxo de Cadastro (5 Steps)
- CRM - MVP
- Desenvolvimento Local
- Deploy Produção
- Roadmap
- Segurança
- Escalabilidade
🎯 Visão Geral
Aggios é uma plataforma SaaS multitenant que unifica ferramentas de gestão para agências digitais.
Problema Resolvido: Agências precisam gerenciar clientes, projetos, contratos, pagamentos e documentos em uma única plataforma integrada.
Solução: Dashboard personalizado por agência onde:
- Admin da agência gerencia equipe, CRM, projetos
- Clientes acessam portal para acompanhar seus projetos
- Tudo integrado: CRM, ERP, Helpdesk, Pagamentos, Contratos
Público-alvo: Agências digitais de 1-50 pessoas
Modelo: SaaS subscription com planos diferentes
🌐 Estrutura de Domínios
Domínios Principais
aggios.app - Site Institucional
- Marketing da plataforma
- Pricing (mostra planos)
- Blog/Recursos
- Landing pages
- SEO e público geral
dash.aggios.app - Admin Interno Aggios
- Super admin da plataforma
- Ver todas as agências cadastradas
- Gerenciar assinaturas e faturamento
- Impersonate (logar como admin de outra agência)
- Analytics da plataforma
- Suporte (abrir tickets para clientes)
{agencia}.aggios.app - Painel da Agência (Multitenant)
- Exemplo:
idealpages.aggios.app - Admin e equipe da agência acessam aqui
- Personalizado com logo, cores, dados da agência
- Todos os módulos: CRM, ERP, Projetos, etc
- Subpath do portal cliente:
{agencia}.aggios.app/portal/{cliente}
Portal Cliente
URL: {agencia}.aggios.app/portal/{cliente-id}?token=xyz
- Cliente acessa seus projetos específicos
- Read-only + comentários
- Acompanha progresso
- Download de arquivos
- Sem acesso a dados de outras agências
👥 Usuários e Roles
Tipos de Usuários
Admin Aggios (Plataforma)
- Acessa:
dash.aggios.app - Permissões: ver todas agências, faturamento, assinaturas, analytics, impersonate
- Uso: time Aggios (suporte, vendas, admin)
Admin da Agência
- Acessa:
{agencia}.aggios.app - Permissões: gerenciar equipe, configurar agência, todos os módulos, relatórios
- Uso: dono/gerente geral da agência
Gerente/Operacional
- Acessa:
{agencia}.aggios.app - Permissões: CRM, projetos, helpdesk, mas sem financeiro/admin
- Uso: coordenador de projetos, gerente de equipe
Membro da Equipe
- Acessa:
{agencia}.aggios.app - Permissões: módulos específicos conforme papel (desenvolvedores, designers, etc)
- Uso: equipe interna
Cliente (Portal)
- Acessa:
{agencia}.aggios.app/portal/{cliente} - Permissões: ver próprios projetos, comentar, download de arquivos
- Uso: clientes da agência
📦 Módulos Principais
MVP (Versão Inicial)
CRM (Customer Relationship Management)
- Gerenciar clientes (lista, adicionar, editar, deletar)
- Status: prospect, client, inactive
- Dashboard com estatísticas
- Filtros e busca
- Histórico de interações (futuro)
Projetos
- Criar projeto (nome, cliente, data de entrega)
- Kanban (To Do, In Progress, Done)
- Timeline com marcos
- Atribuir ao membro da equipe
- Anexar arquivos
Pagamentos
- Integração com Stripe
- Cobranças automáticas
- Faturas geradas
- Histórico de pagamentos
Portal Cliente
- Compartilhar projeto via link
- Cliente faz login/cria conta
- Visualiza progresso
- Faz comentários
Módulos Futuros (v1.0+)
ERP
- Recursos (materiais, ferramentas)
- Financeiro avançado (custos, lucro)
- Relatórios financeiros
- Exportação de dados
Helpdesk
- Tickets de suporte
- SLA (tempo de resposta)
- Base de conhecimento
- Automação
Contratos
- Templates de contratos
- E-signature (assinatura digital)
- Versionamento
- Histórico de assinaturas
Integrações
- Zapier
- Slack
- Google Workspace
- GitHub
- Jira
💰 Modelo de Negócio
Planos de Assinatura
STARTER - R$99/mês
- CRM + Contratos + Pagamentos
- 3 usuários
- 10 projetos simultâneos
- 5GB de armazenamento
- Suporte por email
PROFESSIONAL - R$299/mês
- Starter + ERP + Helpdesk + Projetos
- 10 usuários
- Projetos ilimitados
- 100GB de armazenamento
- Suporte prioritário
- API básica
ENTERPRISE - R$999+/mês
- Professional + Integrações customizadas
- Usuários ilimitados
- Armazenamento ilimitado
- Suporte 24/7
- API completa
- Webhooks
- SSO (Single Sign-On)
À La Carte (Futuro)
- CRM: R$49/mês
- ERP: R$79/mês
- Helpdesk: R$59/mês
- Contratos: R$29/mês
- Projetos: R$39/mês
Modelo de Receita
- Subscription mensal (principal)
- Taxa de setup: R$99 (primeira agência)
- Integrações customizadas: R$1000+
- Suporte dedicado: R$500/mês
🛠️ Stack Técnico
Frontend
Next.js (React)
- App router (não pages router)
- Server components quando possível
- TypeScript
- Tailwind CSS para estilos
- ShadcN UI ou Radix UI para componentes
Interfaces Principais:
- Landing page (aggios.app)
- Admin internal (dash.aggios.app)
- Painel da agência ({agencia}.aggios.app)
- Portal do cliente
Backend
NestJS (Node.js)
- Arquitetura modular
- TypeScript nativo
- Guards, Pipes, Interceptors
- Validation com class-validator
- Documentation com Swagger
Principais Módulos:
- Authentication (JWT, refresh tokens)
- Tenants (multi-tenancy)
- CRM
- Projetos
- Pagamentos (Stripe integration)
Banco de Dados
PostgreSQL
- Schema por tenant (isolamento de dados)
- Row-Level Security (RLS) para segurança
- Migrations com Typeorm ou Knex
- Backup automático diário
Cache
Redis
- Sessions de usuário
- Cache de dados frequentes
- Rate limiting
- Fila de jobs
Storage
Minio (S3-compatible)
- Upload de logos
- Arquivos de projetos
- Documentos/contratos
- Backup de dados
Roteamento
Traefik
- Load balancer
- Roteamento por hostname
- HTTPS/SSL automático
CI/CD
GitHub Actions
- Testes automáticos
- Build da aplicação
- Deploy automático em merge para main
🏗️ Arquitetura
Visão Geral
┌─────────────────────────────────────────────┐
│ Frontend (Next.js) │
│ ├─ Landing: aggios.app │
│ ├─ Admin: dash.aggios.app │
│ ├─ App: {agencia}.aggios.app │
│ └─ Portal: {agencia}.aggios.app/portal │
└────────────────┬────────────────────────────┘
│ HTTPS
┌────────────────▼────────────────────────────┐
│ Traefik │
│ (Roteamento por hostname) │
└────────────────┬────────────────────────────┘
│
┌────────────────▼────────────────────────────┐
│ Backend (NestJS API) │
│ ├─ Auth Module │
│ ├─ Tenants Module │
│ ├─ CRM Module │
│ ├─ Projetos Module │
│ └─ Pagamentos Module │
└────────────────┬────────────────────────────┘
│
┌────────────┼────────────┬──────────┐
│ │ │ │
▼ ▼ ▼ ▼
┌─────────┐ ┌────────┐ ┌─────────┐ ┌──────┐
│PostgreSQL│ │ Redis │ │ Minio │ │Stripe│
│ │ │ │ │ (S3) │ │ │
└──────────┘ └────────┘ └─────────┘ └──────┘
Isolamento de Dados
Row-Level Security (RLS) no PostgreSQL:
- Cada tenant tem suas próprias linhas
- Política: usuário só vê dados do seu tenant
- Impossível vazar dados entre clientes
Schema Compartilhado:
- Uma tabela "tenants" com todas as agências
- Foreign key tenant_id em todas as tabelas
- Sem criar schemas separados (simples)
📝 Fluxo de Cadastro (5 Steps)
Resumo dos Steps
Step 1: Dados Pessoais (5 campos)
- Nome, email, telefone, whatsapp, senha
- Tempo: 2-3 minutos
Step 2: Empresa Básico (6 campos)
- Nome, CNPJ, descrição, website, indústria, tamanho equipe
- Tempo: 3-4 minutos
Step 3: Localização e Contato (10 campos)
- CEP (com busca ViaCEP), estado, cidade, bairro, rua, número, complemento
- Email comercial, telefone, whatsapp
- Tempo: 3-4 minutos
Step 4: Escolher Domínio (1 campo)
- Slug com sugestão automática e validação em tempo real
- Tempo: 1-2 minutos
Step 5: Personalização (3 campos)
- Logo (upload), cor primária, cor secundária
- Checkboxes: permitir upload cliente, portal automático
- Tempo: 2-3 minutos
Fluxo Técnico
User acessa: dash.aggios.app/cadastro
↓
Step 1: Preenche dados pessoais → POST /auth/signup/step-1
↓
Backend valida + INSERT signup_temp (temporário, 24h)
↓
User redireciona para Step 2
↓
Step 2: Preenche dados empresa → POST /auth/signup/step-2
↓
Backend valida + UPDATE signup_temp
↓
Continua para Step 3, 4, 5...
↓
Step 5: Upload logo + cores → POST /auth/signup/step-5
↓
Backend executa TRANSAÇÃO:
├─ CREATE tenant (agência)
├─ CREATE user (admin)
├─ DELETE signup_temp
├─ Gera JWT
└─ Retorna token + redirectUrl
↓
Frontend redireciona para: {slug}.aggios.app/welcome
Dados Coletados
Pessoal (Step 1):
- Nome completo
- Email (login)
- Telefone
- Senha (hashed)
Empresa (Step 2):
- Nome agência
- CNPJ (14 dígitos)
- Descrição
- Website
- Indústria
- Tamanho equipe
Localização (Step 3):
- CEP (integração ViaCEP)
- Estado/UF
- Cidade
- Bairro
- Rua/Avenida
- Número
- Complemento
Contato (Step 3):
- Email comercial
- Telefone empresa
- WhatsApp empresa
Domínio (Step 4):
- Slug ({agencia}.aggios.app)
Personalização (Step 5):
- Logo URL (Minio)
- Cor primária (hex) - Padrão: #FF3A05
- Cor secundária (hex) - Padrão: #FF0080
- Gradiente de branding:
linear-gradient(90deg, #FF3A05, #FF0080) - Permitir upload cliente (sim/não)
- Portal automático (sim/não)
Validações Importantes
CNPJ:
- 14 dígitos válidos
- Dígitos verificadores corretos
- Não duplicado no banco
CEP:
- 8 dígitos válidos
- Busca em ViaCEP
- Se não encontrado: preenchimento manual
Slug:
- 3-50 caracteres
- Apenas a-z, 0-9, hífen
- Não é palavra reservada
- Não duplicado
Senha:
- 8+ caracteres
- 1 maiúscula, 1 número, 1 especial
💻 CRM - MVP
Funcionalidades Incluídas (MVP)
Lista de Clientes
- Paginação (20 por página)
- Busca por nome/email
- Filtro por status (prospect, client, inactive)
- Ordenação (nome, data criação, status)
Adicionar Cliente
- Form simples: nome, email, telefone, empresa
- Validação de email
- Cliente criado com status "prospect"
Editar Cliente
- Atualizar dados
- Mudar status
- Salvar histórico de mudanças
Deletar Cliente
- Soft delete (marca como inactive)
- Ou hard delete (remove do banco)
Dashboard Stats
- Total de clientes
- Clientes por status (prospect, client, inactive)
- Gráficos simples
Funcionalidades Futuras (Deixar para depois)
- Pipeline de vendas (funil)
- Histórico de interações
- Tags/categorias
- Atividades (calls, emails)
- Emails integrados
- Relatórios avançados
- Import/export CSV
- Automação
Dados Armazenados
Clientes:
- ID (UUID)
- Tenant ID (qual agência)
- Nome (obrigatório)
- Email (obrigatório)
- Telefone
- Empresa
- Status (prospect/client/inactive)
- Data criação
- Data última atualização
- Criado por (user ID)
Histórico (futuro):
- ID
- Cliente ID
- O que mudou
- Valor anterior
- Valor novo
- Quem mudou
- Data
URLs
{agencia}.aggios.app/crm/customers- Lista{agencia}.aggios.app/crm/customers/new- Novo{agencia}.aggios.app/crm/customers/[id]- Detalhe/editar{agencia}.aggios.app/crm/dashboard- Dashboard stats
Telas "Em Breve"
Todos os outros módulos mostram tela "Este módulo será lançado em breve":
- ERP
- Helpdesk
- Contratos
- Pagamentos
- Projetos
🏗️ Desenvolvimento Local
Ambiente Local
Ferramentas Necessárias:
- Docker + Docker Compose
- Node.js 18+
- Git
Serviços Locais (Docker)
PostgreSQL
├─ Host: localhost:5432
├─ User: aggios
├─ Password: password
└─ Database: aggios_dev
Redis
├─ Host: localhost:6379
└─ Port: 6379
Minio (S3-compatible)
├─ Host: localhost:9000
├─ User: minioadmin
├─ Password: minioadmin
└─ Bucket: aggios
Traefik
├─ Host: localhost (com config /etc/hosts para *.localhost)
├─ Dashboard: localhost:8080
└─ Router automático por hostname
Hosts Locais
Configure em /etc/hosts:
127.0.0.1 aggios.localhost
127.0.0.1 dash.aggios.localhost
127.0.0.1 idealpages.aggios.localhost
127.0.0.1 test.aggios.localhost
Iniciar Ambiente
1. Clone repositório
2. Configure .env (cópiar de .env.example)
3. docker-compose up -d
4. npm install
5. npm run db:migrate
6. npm run dev
URLs de Acesso
- Landing: http://aggios.localhost
- Admin: http://dash.aggios.localhost
- Agência teste: http://idealpages.aggios.localhost
- Minio: http://localhost:9000
- Traefik: http://localhost:8080
🚀 Deploy Produção
Infraestrutura
VPS Recomendado:
- 2GB RAM
- 20GB SSD
- Ubuntu 24 LTS
- IP público estático
Provedor: Linode, DigitalOcean, Vultr, AWS EC2
Setup Produção (Dokploy)
Passo 1: Comprar VPS + domínio
Passo 2: Instalar Dokploy
- SSH no VPS
- Executar script instalação
- Interface web no
http://ip-vps:3000
Passo 3: Configurar DNS
- Apontar domínio para IP do VPS
- Subdomínios: dash.aggios.app, *.aggios.app (wildcard)
Passo 4: Cadastrar 6 Serviços em Dokploy
-
Landing (Next.js - aggios.app)
- Port: 3000
- Build:
npm run build - Start:
npm start
-
Admin (Next.js - dash.aggios.app)
- Port: 3001
- Build:
npm run build - Start:
npm start
-
API (NestJS - *.aggios.app wildcard)
- Port: 3333
- Build:
npm run build - Start:
npm run start:prod
-
PostgreSQL
- Port: 5432
- Backup automático (daily)
-
Redis
- Port: 6379
-
Minio
- Port: 9000
Passo 5: GitHub Integration
- Conectar repositório GitHub
- Push em main → Deploy automático
- Webhook automático
O que Dokploy Cuida
- Traefik integrado (não configurar manual)
- SSL automático (Let's Encrypt)
- HTTPS forçado
- Backup automático de banco
- Monitoramento básico
- CI/CD nativo
- Logs centralizados
Diferenças Local vs Produção
| Aspecto | Local | Produção |
|---|---|---|
| Traefik | Manual config | Dokploy nativo |
| HTTPS | HTTP (.localhost) | HTTPS automático |
| Domínios | *.localhost | Domínios reais |
| SSL | Não | Let's Encrypt |
| Backup | Manual | Automático |
| CI/CD | Manual | GitHub webhook |
| Monitoramento | Não | Básico |
| Logs | Docker | Dokploy |
📅 Roadmap
MVP (Mês 1-2)
Prioridades:
- Setup infraestrutura (Docker, Traefik, Dokploy)
- Autenticação (JWT, refresh tokens)
- Cadastro 5 steps
- Tenant middleware + RLS
- CRM básico (CRUD)
- Painel inicial
- Upload de logo (Minio)
- Stripe integration básica
- Deploy no Dokploy
Resultado: Agência consegue se cadastrar e gerenciar clientes
v1.0 (Mês 2-3)
Adições:
- Módulo Projetos (Kanban, timeline)
- Portal cliente (compartilhar projeto)
- Contratos com e-signature
- Helpdesk básico
- Relatórios simples
- Email notifications
- Onboarding/tour
Resultado: Plataforma funcional com todos módulos principais
v1.1 (Mês 3-4)
Adições:
- ERP básico (recursos, financeiro)
- Integrações (Zapier, Slack)
- API documentada
- Webhooks
- Backup automático na nuvem
- Autenticação 2FA
Resultado: Mais poderoso, integrações com outros serviços
v2.0 (Futuro)
Inovação:
- IA para sugestões (recomendações de tarefas)
- Mobile app (iOS/Android)
- Marketplace de integrações
- Multi-região
- Chatbot suporte automático
🔒 Segurança
Autenticação
- JWT (JSON Web Tokens)
- Refresh tokens (7 dias)
- Access tokens (15 minutos)
- Refresh token rotation (novo token a cada uso)
- Logout (blacklist token)
Autorização
- Row-Level Security (PostgreSQL RLS)
- Cada user só vê dados do seu tenant
- Middleware valida tenant_id em cada requisição
- Guards em endpoints críticos
Dados
- Criptografia de senhas (bcrypt)
- HTTPS/SSL em produção (Let's Encrypt)
- SGBD com autenticação
- Redis com password
- Minio com credenciais
Conformidade
- LGPD compliance (lei brasileira de dados)
- Termos de uso + Privacy policy
- Consentimento antes de cadastro
- Direito de dados (export/delete)
- Audit logs (quem fez o quê, quando)
Backup
- Backup diário do PostgreSQL
- Retenção: 30 dias
- Armazenamento: Minio ou nuvem
- Restore automático testado semanalmente
📊 Escalabilidade
Fase 1: Até 100 Agências
Infraestrutura:
- 1 VPS (2GB RAM)
- PostgreSQL com plano starter
- Redis com cache básico
- Minio com 50GB
Capacidade:
- ~10k usuários
- ~100k clientes
- Resposta <500ms
Fase 2: 100-500 Agências
Infraestrutura:
- 1 VPS principal (4GB RAM)
- 1 VPS para banco (2GB RAM)
- PostgreSQL Read Replicas
- Redis Cluster
- Minio distribuído
Mudanças:
- Load balancer entre servidores API
- Connection pooling no banco
- Cache distribuído
Fase 3: 500-2k Agências
Infraestrutura:
- Múltiplas instâncias API
- RDS (AWS managed database)
- ElastiCache (Redis managed)
- S3 (AWS S3 real)
- CloudFront (CDN)
- ALB (Application Load Balancer)
Mudanças:
- Sharding de banco (por tenant)
- Cache camadas múltiplas
- Workers para jobs longos
Fase 4: 5k+ Agências
Infraestrutura:
- Kubernetes (EKS)
- Autoscaling horizontal
- Multi-region replication
- Microsserviços
- Event-driven architecture
📊 Database Schema (Estrutura)
Tabelas Principais
tenants
- Agências cadastradas
- Campos: id, slug, name, cnpj, description, website, email, phone, whatsapp, logo_url, primary_color, secondary_color, industry, team_size, allow_client_uploads, enable_customer_portal, plan, status, created_at, updated_at
users
- Usuários (admins, gerentes, equipe)
- Campos: id, tenant_id, first_name, last_name, email, password_hash, phone, whatsapp, role, status, last_login_at, created_at, updated_at
signup_temp
- Dados temporários do cadastro (24h expiration)
- Campos: id, temp_user_id, [todos os dados coletados nos 5 steps], status, created_at, expires_at
customers (CRM)
- Clientes das agências
- Campos: id, tenant_id, name, email, phone, company, status, created_at, updated_at
projects (futuro)
- Projetos por agência
- Campos: id, tenant_id, name, client_id, status, start_date, due_date, created_at, updated_at
tasks (futuro)
- Tarefas dentro de projetos
- Campos: id, project_id, title, description, status, assigned_to, due_date, created_at, updated_at
subscriptions
- Assinaturas (plano + pagamento)
- Campos: id, tenant_id, plan, status, stripe_subscription_id, current_period_start, current_period_end, created_at
audit_logs
- Log de ações (segurança)
- Campos: id, tenant_id, user_id, action, resource, changes, created_at
📁 Estrutura de Pasta (Monorepo)
aggios/
├── apps/
│ ├── api-core/ (NestJS backend)
│ │ ├── src/
│ │ │ ├── modules/
│ │ │ │ ├── auth/
│ │ │ │ ├── tenants/
│ │ │ │ ├── crm/
│ │ │ │ ├── projects/
│ │ │ │ └── payments/
│ │ │ ├── common/
│ │ │ │ ├── guards/
│ │ │ │ ├── decorators/
│ │ │ │ ├── middleware/
│ │ │ │ └── filters/
│ │ │ ├── config/
│ │ │ └── main.ts
│ │ ├── migrations/
│ │ ├── Dockerfile
│ │ └── package.json
│ │
│ ├── landing/ (Next.js - aggios.app)
│ │ ├── app/
│ │ ├── components/
│ │ ├── public/
│ │ └── package.json
│ │
│ ├── dashboard/ (Next.js - dash.aggios.app)
│ │ ├── app/
│ │ │ ├── cadastro/
│ │ │ └── [admin pages]
│ │ ├── components/
│ │ └── package.json
│ │
│ └── tenant-app/ (Next.js - {agencia}.aggios.app)
│ ├── app/
│ │ ├── welcome/
│ │ ├── crm/
│ │ ├── dashboard/
│ │ └── [tenant pages]
│ ├── components/
│ └── package.json
│
├── packages/
│ ├── shared-types/
│ │ └── DTOs, interfaces, types
│ └── shared-ui/
│ └── Componentes reutilizáveis
│
├── docker-compose.yml
├── .env.example
└── README.md
🎯 Próximos Passos
Semana 1:
- Estruturar monorepo (turborepo)
- Setup Docker local
- Setup PostgreSQL + migrations
- Setup NestJS (modules auth, tenants)
Semana 2:
- Setup Next.js (landing + dashboard + tenant-app)
- Cadastro 5 steps (frontend + backend)
- Autenticação JWT
Semana 3:
- CRM básico (CRUD)
- Dashboard inicial
- Integração Minio (logo)
Semana 4:
- Integração Stripe
- Stripe webhook
- Deploy Dokploy teste
Semana 5:
- Testes
- Bugfixes
- Deploy produção
📊 Métricas de Sucesso
Para Agência
- Tempo cadastro: < 10 minutos
- Taxa conclusão: > 60%
- Retenção 30 dias: > 70%
- NPS (satisfação): > 8/10
Para Usuário
- Login: < 2 segundos
- Carregar página: < 3 segundos
- Criar cliente: < 1 minuto
- Compartilhar projeto: < 2 minutos
Para Negócio
- Churn: < 5% mensal
- CAC (custo adquisição): < R$50
- LTV (lifetime value): > R$1000
- MRR (receita mensal): crescimento 10% mês
📞 Suporte e Manutenção
Canais de Suporte
- Email: support@aggios.app
- Chat no painel
- Ticket system (Helpdesk)
- Community (Discord/Slack)
SLA por Plano
- STARTER: 24-48h resposta
- PROFESSIONAL: 12h resposta
- ENTERPRISE: 2-4h resposta + 24/7
Manutenção
- Atualizações: terça-feira 2h da manhã
- Downtime esperado: 15 minutos
- Backup: diário às 3h da manhã
- Monitoramento: 24/7
🎓 Documentação Futura
Deve ser criada:
- API Documentation (Swagger)
- User Guide (como usar cada módulo)
- Admin Guide (como gerenciar agência)
- Developer Guide (como integrar)
- Changelog (versões)
- FAQ (perguntas comuns)
Versão: 1.0
Data Criação: 04/12/2025
Status: Pronto para Code Agent
Uso: Compartilhar com code agent (Claude Code, ou outra IA) para gerar código
Notas:
- Este documento é SEM CÓDIGO
- Ideal para planejamento, requisitos, arquitetura
- Code agent usará isso como especificação técnica
- Todos os detalhes lógicos estão aqui
- Falta apenas implementação (qual o trabalho do code agent)