Arquitetura do Sistema

O Opero Global é composto por módulos interconectados que trabalham juntos para oferecer uma experiência unificada.

Visão geral


┌─────────────────────────────────────────────────────────────────┐
│                        FRONTEND (Next.js)                         │
│                                                                   │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────────────┐│
│  │Dashboard │  │ Booking  │  │  Admin   │  │   Help / Docs    ││
│  │  (app)   │  │ (portal) │  │ (super)  │  │   (você está     ││
│  │          │  │          │  │          │  │    aqui!)        ││
│  └────┬─────┘  └────┬─────┘  └────┬─────┘  └──────────────────┘│
└───────┼──────────────┼──────────────┼────────────────────────────┘
        │              │              │
        ▼              ▼              ▼
┌─────────────────────────────────────────────────────────────────┐
│                      API (NestJS + Fastify)                       │
│                                                                   │
│  ┌─────────┐ ┌──────────┐ ┌──────────┐ ┌─────────┐ ���────────┐ │
│  │   PMS   │ │Financial │ │ Payment  │ │   OCP   │ │  GBP   │ │
│  │  Core   │ │  Basic   │ │  (OP)    │ │ (Comms) │ │(Booking│ │
│  └────┬────┘ └────┬─────┘ └────┬─────┘ └────┬────┘ └───┬────┘ │
│       │            │            │            │           │       │
│  ┌────┴────────────┴────────────┴────────────┴───────────┴────┐ │
│  │              Camada de Autorização (CASL)                    │ │
│  └────────────────────────────┬────────────────────────────────┘ │
│                               │                                   │
│  ┌────────────────────────────┴────────────────────────────────┐ │
│  │              Multi-tenancy (AsyncLocalStorage)               │ │
│  └────────────────────────────┬────────────────────────────────┘ │
└───────────────────────────────┼──────────────────────────────────┘
                                │
        ┌───────────────────────┼───────────────────────┐
        ▼                       ▼                       ▼
┌──────────────┐     ┌──────────────┐     ┌──────────────────┐
│  PostgreSQL  │     │    Redis     │     │   AWS Services   │
│  (dados)     │     │  (cache +    │     │  (S3, KMS, SES)  │
│              │     │   sessões)   │     │                  │
└──────────────┘     └──────────────┘     └──────────────────┘

Camadas da aplicação

Cada módulo segue a Clean Architecture com 4 camadas:

1. Domain (Domínio)

Regras de negócio puras. Não depende de nenhuma tecnologia externa.

Entidades (Reservation, Guest, JournalEntry)
Value Objects (Money, DateRange, TenantId)
Interfaces de repositório

2. Application (Aplicação)

Casos de uso que orquestram o domínio.

CreateReservation, CheckInGuest, PostJournalEntry
Interfaces de serviços externos

3. Infrastructure (Infraestrutura)

Implementações concretas de bancos de dados e serviços externos.

Repositórios Drizzle (PostgreSQL)
Adaptadores Stripe, Twilio, AWS SES
Redis para cache e sessões

4. Presentation (Apresentação)

Controllers HTTP que expõem a API.

Endpoints REST
Validação com Zod
Autorização com CASL

Fluxo de uma requisição


Usuário clica "Criar Reserva"
       │
       ▼
[Frontend] POST /api/tenants/:tenantId/reservations
       │
       ▼
[AuthGuard] Valida token JWT / sessão
       │
       ▼
[TenantContext] Define tenantId via AsyncLocalStorage
       │
       ▼
[PoliciesGuard] CASL verifica: ability.can('create', 'Reservation')
       │
       ▼
[Controller] Valida body com Zod schema
       │
       ▼
[UseCase] Executa lógica de negócio (verifica disponibilidade, calcula preço)
       │
       ▼
[Repository] Persiste no PostgreSQL (filtrado por tenantId)
       │
       ▼
[AuditService] Registra ação na trilha de auditoria
       │
       ▼
[Response] 201 Created { reservation: {...} }

Isolamento de dados (Multi-tenancy)

Cada tenant (organização) tem seus dados completamente isolados:

Toda tabela do banco possui uma coluna tenant_id
Toda query é automaticamente filtrada pelo tenant do usuário logado
Não é possível acessar dados de outro tenant — nem por erro de programação
O isolamento é garantido em 3 camadas: autenticação, rota e serviço

Integrações externas

Serviço	Uso no Opero
Stripe Connect	Processamento de pagamentos (cartão, PIX)
Pluggy / Belvo	Open Finance — importação automática de extratos
AWS SES	Envio de emails transacionais
Twilio	SMS e WhatsApp Business
AWS S3	Armazenamento de documentos e imagens
AWS KMS	Criptografia de dados sensíveis (LGPD)
AWS SES	Emails em produção

Segurança

Criptografia em repouso — Dados PII criptografados com AES-256 via AWS KMS
LGPD/GDPR — Consentimento, anonimização, portabilidade de dados
Auditoria completa — Toda ação registrada (quem, o quê, quando)
Sessões Redis — Tokens com expiração, revogação individual ou total
Zod validation — Toda entrada validada antes de processar