saveinmed/docs/architecture.md

Arquitetura SaveInMed

Visão geral

┌─────────────────────────────────────────────────────┐
│                   Clientes HTTP                      │
│  Browser (frontend)        Browser (admin panel)     │
└──────────────┬──────────────────────┬───────────────┘
               │                      │
               ▼                      ▼
     ┌─────────────────┐   ┌─────────────────────┐
     │  backend (Go)   │   │  backoffice (NestJS) │
     │  :8214          │   │  :3001              │
     └────────┬────────┘   └──────────┬──────────┘
              │                        │
              └───────────┬────────────┘
                          ▼
              ┌─────────────────────┐
              │  PostgreSQL         │
              └─────────────────────┘

Decisões de design

Backend Go — Clean Architecture

A separação de camadas segue Uncle Bob's Clean Architecture:

cmd/api/
  └── main.go            → DI e wiring de dependências

internal/
  ├── domain/            → Entidades, value objects, interfaces de repositório
  ├── usecase/           → Regras de negócio (independentes de framework)
  │     ├── usecase.go            → Service struct + interfaces centrais
  │     ├── auth_usecase.go       → Autenticação, JWT, reset de senha
  │     ├── company_usecase.go    → Empresas e KYC
  │     ├── product_usecase.go    → Catálogo e inventário
  │     ├── order_usecase.go      → Ciclo de vida de pedidos (state machine)
  │     ├── shipping_usecase.go   → Cálculo de frete e configurações
  │     ├── cart_usecase.go       → Carrinho com descontos B2B
  │     ├── payment_usecase.go    → Pagamentos e webhooks
  │     ├── review_usecase.go     → Avaliações de vendedores
  │     ├── user_usecase.go       → CRUD de usuários
  │     ├── address_usecase.go    → Endereços
  │     └── dashboard_usecase.go  → KPIs de vendedor e admin
  ├── http/
  │     ├── handler/     → Um arquivo por recurso REST
  │     └── middleware/  → Auth JWT, CORS, rate-limit, logging
  ├── repository/postgres/ → Implementações de Repository + migrações
  └── infrastructure/
        ├── mapbox/      → Cliente Mapbox (cálculo de distância de rota)
        ├── payments/    → Mercado Pago, Asaas, Stripe
        └── notifications/ → Firebase Cloud Messaging (FCM)

Regra de dependência: camadas externas (HTTP, banco, infra) dependem das camadas internas (use case, domain). Nunca o contrário.

Frontend React — Organização por perfil

Páginas agrupadas em src/pages/<contexto>/<perfil>/, com alias @/ para importações absolutas:

pages/
  auth/           → Login, registro (público)
  marketplace/    → Search, Cart, Checkout, Orders (compradores)
  dashboard/
    admin/        → Painel admin (consome backoffice API)
    seller/       → Seller Dashboard, Inventory, Products
    employee/     → Colaborador
    delivery/     → Entregador
    Company.tsx   → Perfil da empresa (compartilhado)
    MyProfile.tsx → Perfil do usuário (compartilhado)

Backoffice NestJS — API para operações internas

O backoffice/ é uma API separada (não é front-end), organizada em módulos NestJS:

Módulo	Responsabilidade
auth	Autenticação de operadores internos
users	Gestão de usuários da plataforma
kyc	Aprovação de empresas (KYC)
inventory	Gestão de estoque e compras (B2B interno)
dashboard	Métricas agregadas da plataforma
reports	Exportação de relatórios
fraud	Detecção de padrões suspeitos
disputes	Gestão de disputas entre partes
audit	Log de ações administrativas
webhooks	Recebimento de eventos externos
performance	Monitoramento de performance de sellers
settings	Configurações da plataforma

Importante: backoffice e as páginas admin do frontend formam um par API+UI. Não há duplicidade — um é o servidor, o outro é o cliente.

Integrações externas

Serviço	Uso	Pacote
Mapbox API	Distância de rota para cálculo de frete	infrastructure/mapbox/
Mercado Pago	Pagamentos B2C e B2B com split	infrastructure/payments/
Asaas	Gateway alternativo / boleto	infrastructure/payments/
Firebase FCM	Push notifications (mobile/PWA)	infrastructure/notifications/

State machine de pedidos

Pending → Paid → Invoiced → Shipped → Delivered → Completed
   ↓         ↓       ↓
Cancelled  Cancelled Cancelled

Transições são validadas em order_usecase.go#UpdateOrderStatus. Cancelamentos restituem estoque automaticamente.

Segurança

• JWT HS256 com pepper no hash de senha (bcrypt)
• Rate limiting por IP no middleware
• CORS configurável por ambiente
• Company verification (KYC) antes de pedidos de produção
• Uploads validados por tipo MIME e tamanho