aggios.app/1. docs/backend-deployment/QUICKSTART.md

🎯 Quick Start - Backend + Traefik

📋 O que foi criado?

Você agora tem uma arquitetura completa de produção com:

✅ Backend em Go com estrutura profissional ✅ Traefik como reverse proxy com suporte a multi-tenant ✅ PostgreSQL para dados com isolamento por tenant ✅ Redis para cache e sessões ✅ MinIO para storage S3-compatible ✅ Docker Compose com stack completa ✅ Autenticação JWT segura ✅ Multi-tenant com roteamento automático ✅ Documentação completa

🚀 Iniciar Desenvolvimento

1. Copiar variáveis de ambiente

cd aggios-app
cp .env.example .env

2. Iniciar stack com um comando

Windows:

.\scripts\start-dev.bat

macOS/Linux:

chmod +x ./scripts/start-dev.sh
./scripts/start-dev.sh

Ou manualmente:

docker-compose up -d

3. Verificar serviços

docker-compose ps

# OUTPUT esperado:
# NAME              STATUS
# traefik           Up (healthy)
# postgres          Up (healthy)
# redis             Up (healthy)
# minio             Up (healthy)
# backend           Up (healthy)

4. Testar API

# Health check
curl http://localhost:8080/api/health

# Response esperado:
# {"status":"up","timestamp":1733376000,"database":true,...}

📚 Documentação Importante

Documento	Descrição
ARCHITECTURE.md	Design da arquitetura
API_REFERENCE.md	Todos os endpoints
DEPLOYMENT.md	Deploy e diagramas
SECURITY.md	Guia de segurança
backend/README.md	Setup do backend

🔄 Estrutura de Pastas

aggios-app/
├── backend/                    # ← Backend Go aqui
│   ├── cmd/server/main.go     # Entry point
│   ├── internal/
│   │   ├── api/               # Handlers, middleware, routes
│   │   ├── auth/              # JWT, passwords, tokens
│   │   ├── config/            # Configurações
│   │   ├── database/          # PostgreSQL, migrations
│   │   ├── models/            # Estruturas de dados
│   │   ├── services/          # Lógica de negócio
│   │   └── storage/           # Redis e MinIO
│   ├── migrations/            # SQL scripts
│   ├── go.mod                 # Dependencies
│   ├── Dockerfile             # Para Docker
│   └── README.md              # Backend docs
│
├── aggios.app-institucional/  # Frontend Institucional (Next.js)
├── dash.aggios.app/           # Frontend Dashboard (Next.js)
│
├── docker-compose.yml         # Stack completa
├── .env.example               # Template de env
├── .env                       # Variáveis reais (não committar!)
│
├── traefik/                   # Configuração Traefik
│   ├── traefik.yml           # Main config
│   ├── dynamic/rules.yml      # Dynamic routing rules
│   └── letsencrypt/          # Certificados (auto-gerado)
│
├── postgres/                  # Inicialização PostgreSQL
│   └── init-db.sql           # Schema initial
│
├── scripts/
│   ├── start-dev.sh          # Start em Linux/macOS
│   └── start-dev.bat         # Start em Windows
│
├── ARCHITECTURE.md            # Design detalhado
├── API_REFERENCE.md          # Endpoints
├── DEPLOYMENT.md             # Diagrama & deploy
├── SECURITY.md               # Segurança & checklist
└── README.md                 # Este arquivo

🛠️ Próximos Passos

1. Completar Autenticação (2-3 horas)

• Implementar login com validação real
• Adicionar password hashing (Argon2)
• Implementar refresh token logic
• Testes de autenticação

Arquivo: backend/internal/api/handlers/auth.go

2. Adicionar Endpoints de Usuário (1-2 horas)

• GET /api/users/me
• PUT /api/users/me (update profile)
• POST /api/users/me/change-password
• DELETE /api/users/me

Arquivo: backend/internal/api/handlers/users.go

3. Implementar Services Layer (2-3 horas)

• UserService
• TenantService
• TokenService
• FileService

Pasta: backend/internal/services/

4. Adicionar Endpoints de Tenant (1-2 horas)

• GET /api/tenant
• PUT /api/tenant
• GET /api/tenant/members
• Invite members

Arquivo: backend/internal/api/handlers/tenant.go

5. Implementar Upload de Arquivos (2 horas)

• POST /api/files/upload
• GET /api/files/{id}
• DELETE /api/files/{id}
• Integração MinIO

Arquivo: backend/internal/api/handlers/files.go

6. Testes Unitários (3-4 horas)

• Auth tests
• Handler tests
• Service tests
• Middleware tests

Pasta: backend/internal/*_test.go

7. Documentação Swagger (1-2 horas)

• Adicionar comentários swagger
• Gerar OpenAPI/Swagger
• Publicar em /api/docs

Dependency: github.com/swaggo/http-swagger

8. Integração com Frontends (2-3 horas)

• Atualizar CORS_ALLOWED_ORIGINS
• Criar cliente HTTP no Next.js
• Autenticação no frontend
• Redirects de login

9. CI/CD Pipeline (2-3 horas)

• GitHub Actions workflow
• Build Docker image
• Push para registry
• Deploy automático

Arquivo: .github/workflows/deploy.yml

10. Monitoramento (1-2 horas)

• Adicionar logging estruturado
• Sentry integration
• Prometheus metrics
• Health check endpoint

---

📝 Exemplo: Adicionar um novo endpoint

1. Criar handler

// backend/internal/api/handlers/agencias.go
package handlers

func (h *AgenciaHandler) ListAgencias(w http.ResponseWriter, r *http.Request) {
    tenantID := r.Header.Get("X-Tenant-ID")
    
    agencias, err := h.agenciaService.ListByTenant(r.Context(), tenantID)
    if err != nil {
        utils.RespondError(w, 500, "error", err.Error(), r.URL.Path)
        return
    }
    
    utils.RespondSuccess(w, 200, agencias, "Agências obtidas com sucesso")
}

2. Registrar na rota

// backend/internal/api/routes.go
mux.HandleFunc("GET /api/agencias", middleware.Chain(
    agenciaHandler.ListAgencias,
    corsMiddleware,
    jwtMiddleware,
))

3. Testar

curl -X GET http://localhost:8080/api/agencias \
  -H "Authorization: Bearer {token}"

---

🐛 Troubleshooting

Backend não inicia

# Ver logs
docker-compose logs -f backend

# Rebuildar
docker-compose build backend
docker-compose up -d backend

PostgreSQL falha

# Verificar password
cat .env | grep DB_PASSWORD

# Reset database
docker-compose down -v postgres
docker-compose up -d postgres

Redis não conecta

# Test connection
docker-compose exec redis redis-cli ping

# Verificar password
docker-compose exec redis redis-cli -a $(grep REDIS_PASSWORD .env) ping

Certificado SSL

# Ver status Let's Encrypt
docker-compose logs traefik | grep acme

# Debug Traefik
docker-compose logs -f traefik

---

🔐 Segurança Inicial

IMPORTANTE: Antes de publicar em produção:

# 1. Gerar secrets seguros
openssl rand -base64 32 > jwt_secret.txt
openssl rand -base64 24 > db_password.txt

# 2. Editar .env com valores seguros
nano .env

# 3. Deletar .env.example
rm .env.example

# 4. Verificar .gitignore
echo ".env" >> .gitignore
git add .gitignore

---

🚀 Deploy em Produção

1. Servidor Linux (Ubuntu 20.04+)
2. Docker + Compose instalados
3. Domain apontando para servidor
4. Secrets em vault (não em .env)

# 1. Clone repo
git clone <repo> /opt/aggios-app
cd /opt/aggios-app

# 2. Setup secrets
export JWT_SECRET=$(openssl rand -base64 32)
export DB_PASSWORD=$(openssl rand -base64 24)

# 3. Start stack
docker-compose -f docker-compose.yml up -d

# 4. Health check
curl https://api.aggios.app/api/health

---

📊 Monitoramento

Após deploy em produção:

# Ver métricas
docker-compose stats

# Ver logs
docker-compose logs -f backend

# Verificar saúde
docker-compose ps

# Acessar dashboards:
# - Traefik: http://traefik.localhost
# - MinIO: http://minio-console.localhost

---

💬 Próximas Discussões

Quando estiver pronto, podemos implementar:

1. OAuth2 (Google, GitHub login)
2. WebSockets (notificações em tempo real)
3. gRPC (comunicação inter-serviços)
4. Message Queue (Kafka/RabbitMQ)
5. Search (Elasticsearch)
6. Analytics (Big Query/Datadog)
7. Machine Learning (recomendações)
8. Blockchain (auditoria imutável)

---

📞 Suporte

Para dúvidas:

1. Consulte a documentação nos links acima
2. Verifique os logs: docker-compose logs {service}
3. Leia o arquivo correspondente em ARCHITECTURE.md, API_REFERENCE.md ou SECURITY.md

---

Status: ✅ Pronto para desenvolvimento Stack: Go + PostgreSQL + Redis + MinIO + Traefik Versão: 1.0.0 Data: Dezembro 2025