Backend - Stack Tecnológica (Estado Atual)¶

Base tecnológica¶

Linguagem: Go 1.25
Framework HTTP: Echo v4
Persistência: PostgreSQL + GORM
Observabilidade: Prometheus (/metrics protegido por admin)
Storage: Cloudflare R2 (S3 compatible)

Estrutura real do projeto¶

billings-ease-backend/
├── cmd/
│   ├── api/main.go
│   └── migrate/main.go
├── internal/
│   ├── app/deps/
│   ├── config/
│   ├── database/
│   ├── http/bootstrap/
│   ├── infra/
│   ├── middleware/
│   ├── models/
│   ├── modules/
│   │   ├── admin/
│   │   ├── auth/
│   │   ├── client/
│   │   ├── general/
│   │   ├── marketplace/
│   │   ├── module_access/
│   │   ├── plans/
│   │   └── professional/
│   └── observability/
├── migrations/
└── openapi.v1.yaml / openapi.v2.yaml

Organização por módulos¶

O backend está organizado por domínio funcional (não por camada global única). Cada módulo usa composição de handler/service/repository quando necessário.

Destaques:

auth: login/register/refresh/OAuth
module_access: catálogo de módulos, global settings, overrides e snapshot por usuário
professional: perfil, pacientes, CRM, financeiro
client: perfil, profissionais, pagamentos
marketplace/courses: domínio compartilhado de cursos (cliente, profissional, admin e webhooks por ator)
admin: usuários, dashboard, observação, Billings data, operação do marketplace

Versionamento e rotas¶

Prefixos ativos: /api, /api/v1, /api/v2
v2 aplica middleware de resolução por public_id
Rotas registradas centralmente em internal/http/bootstrap/routes.go

Capacidade atual relevante¶

1. Controle de módulos¶

Bloqueio backend por módulo com MODULE_DISABLED.
Snapshot de módulos por usuário em /users/me/modules.

2. Financeiro profissional¶

financial-summary, payments, ledger, withdrawals.
Feature flags para evolução financeira.

3. Marketplace de cursos¶

CRUD profissional, revisão admin, pedidos, comissão global/override.
Webhook Mercado Pago com idempotência, retry e dead-letter.
Ledger e settlement com janela de reembolso.
Reconciliação financeira por endpoint admin.
Deleção lógica de curso com execução assíncrona de limpeza de vídeos.

Observabilidade (Prometheus)¶

Além de métricas HTTP gerais, existem métricas de marketplace:

eventos de webhook
transições de pedidos
pedidos por status
reconciliação (delta e delta_pct)
geração de playback token
crescimento de tabelas operacionais

Feature flags importantes¶

admin.module_control.enabled
professional.crm.enabled
professional.financial_v2.enabled
professional.withdrawals.enabled
marketplace.checkout.enabled
marketplace.webhook.enabled
marketplace.settlement.enabled

Referências recomendadas¶

openapi.v2.yaml (contrato HTTP)
internal/http/bootstrap/routes.go (mapa de registro)
docs/02-backend/estado-atual.md (resumo operacional)