Decisões Arquiteturais¶
Este documento registra decisões arquiteturais importantes do projeto Billings Ease, incluindo contexto, alternativas consideradas e trade-offs.
Índice¶
- Backend em Go
- Clean Architecture Simplificada
- Repository Pattern
- JWT para Autenticação
- PostgreSQL como Banco Principal
- React Query para Estado do Frontend
- Radix UI para Componentes
- Railway para Deploy
- Cloudflare R2 para Storage
Backend em Go¶
Decisão¶
Usar Go (Golang) como linguagem do backend.
Contexto¶
Necessidade de: - Performance alta - Concorrência eficiente - Simplicidade de deploy - Tipagem estática
Alternativas Consideradas¶
- Node.js/TypeScript
- ❌ Performance inferior para cálculos
- ❌ Gerenciamento de memória menos eficiente
-
✅ Ecossistema grande
-
Python (Django/FastAPI)
- ❌ Performance inferior
- ❌ GIL limita concorrência
-
✅ Fácil desenvolvimento
-
Java/Kotlin
- ❌ Mais verboso
- ❌ Startup mais lento
- ✅ Performance excelente
Trade-offs¶
Vantagens: - Performance excelente - Concorrência nativa (goroutines) - Compilação para binário único - Tipagem estática forte
Desvantagens: - Curva de aprendizado - Ecossistema menor que Node.js - Menos bibliotecas prontas
Status¶
✅ Implementado e funcionando bem.
Clean Architecture Simplificada¶
Decisão¶
Adotar Clean Architecture de forma simplificada (Handlers → Services → Repositories → Models).
Contexto¶
Necessidade de: - Separação de responsabilidades - Testabilidade - Manutenibilidade - Sem over-engineering
Alternativas Consideradas¶
- MVC Tradicional
- ❌ Menos separação de responsabilidades
-
✅ Mais simples
-
Clean Architecture Completa
- ❌ Muito complexo para o tamanho do projeto
-
✅ Máxima separação
-
Hexagonal Architecture
- ❌ Similar complexidade
- ✅ Boa separação
Trade-offs¶
Vantagens: - Separação clara de responsabilidades - Fácil de testar - Fácil de entender - Escalável
Desvantagens: - Mais camadas que MVC simples - Requer disciplina
Status¶
✅ Implementado. Funciona bem para o tamanho atual do projeto.
Repository Pattern¶
Decisão¶
Usar Repository Pattern para abstrair acesso a dados.
Contexto¶
Necessidade de: - Testabilidade (mock de repositories) - Flexibilidade (trocar implementação) - Separação de lógica de negócio e acesso a dados
Alternativas Consideradas¶
- Acesso Direto ao GORM
- ❌ Difícil de testar
- ❌ Lógica de acesso misturada com negócio
-
✅ Mais simples
-
Active Record Pattern
- ❌ Menos flexível
- ✅ Mais direto
Trade-offs¶
Vantagens: - Fácil de mockar em testes - Pode trocar implementação (ex: de GORM para SQL puro) - Separação clara
Desvantagens: - Mais código boilerplate - Camada adicional
Status¶
✅ Implementado. Facilita muito os testes.
JWT para Autenticação¶
Decisão¶
Usar JWT (JSON Web Tokens) para autenticação stateless.
Contexto¶
Necessidade de: - Autenticação stateless (escalável) - Funcionar em múltiplos clientes (web, mobile) - Sem necessidade de sessões no servidor
Alternativas Consideradas¶
- Sessões no Servidor (cookies)
- ❌ Requer armazenamento no servidor
- ❌ Menos escalável
-
✅ Mais seguro (revogação fácil)
-
OAuth 2.0 Completo
- ❌ Mais complexo
- ✅ Padrão da indústria
Trade-offs¶
Vantagens: - Stateless (escalável) - Funciona em múltiplos clientes - Padrão da indústria
Desvantagens: - Revogação mais difícil (precisa de blacklist) - Tokens podem ser roubados (XSS)
Status¶
✅ Implementado. Funciona bem. Considerar refresh tokens com blacklist no futuro.
PostgreSQL como Banco Principal¶
Decisão¶
Usar PostgreSQL como banco de dados principal.
Contexto¶
Necessidade de: - Relacionamentos complexos - Transações ACID - Suporte a JSON (para regras flexíveis) - Confiabilidade
Alternativas Consideradas¶
- MySQL
- ❌ Suporte JSON inferior
-
✅ Muito popular
-
MongoDB (NoSQL)
- ❌ Sem transações ACID completas
- ❌ Relacionamentos mais complexos
-
✅ Flexível para esquema
-
SQLite
- ❌ Não adequado para produção multi-usuário
- ✅ Simples
Trade-offs¶
Vantagens: - Relacionamentos complexos - Transações ACID - JSON nativo (JSONB) - Confiável e maduro
Desvantagens: - Requer servidor dedicado - Mais complexo que SQLite
Status¶
✅ Implementado. PostgreSQL atende todas as necessidades.
React Query para Estado do Frontend¶
Decisão¶
Usar TanStack Query (React Query) para gerenciar estado de servidor.
Contexto¶
Necessidade de: - Cache automático de dados do servidor - Sincronização - Loading states - Refetch automático
Alternativas Consideradas¶
- Redux
- ❌ Muito boilerplate
- ❌ Overkill para dados do servidor
-
✅ Padrão da indústria
-
Context API + useState
- ❌ Sem cache automático
- ❌ Sem sincronização
-
✅ Nativo do React
-
SWR
- ✅ Similar ao React Query
- ❌ Menos features
Trade-offs¶
Vantagens: - Cache automático - Sincronização - Loading/error states - Refetch inteligente
Desvantagens: - Dependência externa - Curva de aprendizado
Status¶
✅ Implementado. Simplifica muito o código do frontend.
Radix UI para Componentes¶
Decisão¶
Usar Radix UI como base para componentes acessíveis.
Contexto¶
Necessidade de: - Componentes acessíveis - Customizáveis - Headless (sem estilos)
Alternativas Consideradas¶
- Material UI
- ❌ Estilos pré-definidos difíceis de customizar
-
✅ Muito completo
-
Chakra UI
- ✅ Boa customização
-
❌ Menos componentes
-
Componentes próprios
- ❌ Muito trabalho
- ✅ Controle total
Trade-offs¶
Vantagens: - Acessibilidade built-in - Totalmente customizável - Headless (sem estilos)
Desvantagens: - Precisa estilizar tudo - Menos componentes prontos
Status¶
✅ Implementado. Funciona bem com Tailwind CSS.
Railway para Deploy¶
Decisão¶
Usar Railway para deploy do backend e frontend.
Contexto¶
Necessidade de: - Deploy simples - Gerenciamento de variáveis de ambiente - Escalabilidade - Custo razoável
Alternativas Consideradas¶
- AWS (EC2, ECS, Lambda)
- ❌ Mais complexo
- ❌ Mais caro
-
✅ Muito flexível
-
Heroku
- ❌ Mais caro
-
✅ Muito simples
-
DigitalOcean
- ❌ Mais configuração manual
- ✅ Mais barato
Trade-offs¶
Vantagens: - Deploy simples (Git push) - Gerenciamento de env vars - Escalabilidade automática - Preço razoável
Desvantagens: - Menos controle que AWS - Vendor lock-in
Status¶
✅ Implementado. Funciona bem para o tamanho atual.
Cloudflare R2 para Storage¶
Decisão¶
Usar Cloudflare R2 para armazenamento de arquivos (imagens de símbolos).
Contexto¶
Necessidade de: - Armazenamento de imagens - URLs públicas - Custo baixo - Compatível com S3
Alternativas Consideradas¶
- AWS S3
- ❌ Mais caro (egress fees)
-
✅ Padrão da indústria
-
Google Cloud Storage
- ❌ Mais complexo
-
✅ Integração com Google
-
Armazenamento local
- ❌ Não escalável
- ✅ Simples
Trade-offs¶
Vantagens: - Sem egress fees - Compatível com S3 API - Preço baixo - CDN integrado
Desvantagens: - Vendor lock-in - Menos maduro que S3
Status¶
✅ Implementado. Funciona bem e reduz custos.