Arquitetura — Hoteis & Pousadas¶

Visao Geral¶

graph TB
    subgraph Frontend
        FE[React + Vite<br/>:5173]
    end

    subgraph Backend
        BE[Quarkus<br/>:5020]
    end

    subgraph Banco
        PG[(PostgreSQL<br/>:5434)]
    end

    subgraph Servicos Haus
        OATH[OATH<br/>:5001]
        GUILD[Guild<br/>:5002]
        HERALD[Herald<br/>:5004]
        VAULT[Vault<br/>:5006]
        CK[CoinKeeper<br/>:5005]
        TC[Tax Collector<br/>:5007]
        SCROLLS[Scrolls<br/>:5003]
    end

    subgraph Externos
        EVO[Evolution API<br/>:5081]
        STRIPE[Stripe]
        ABACATE[AbacatePay]
    end

    FE --> BE
    BE --> PG
    BE --> OATH
    BE --> GUILD
    BE --> HERALD
    BE --> VAULT
    BE --> CK
    BE --> TC
    BE --> SCROLLS
    HERALD --> EVO
    CK --> STRIPE
    CK --> ABACATE

Backend¶

Camadas¶

hotel/
├── api/                    # Controllers REST (endpoints)
│   ├── controllers/        # API core (/api/*)
│   └── bff/               # Backend for Frontend (/bff/*)
├── application/           # Servicos de negocio
│   └── services/
├── domain/                # Entidades e enums
│   ├── entities/
│   └── enums/
└── infrastructure/        # Integracao e infra
    ├── clients/           # REST clients (OATH, Guild, Herald, etc.)
    ├── repositories/      # Panache repositories (PostgreSQL)
    ├── scheduler/         # Jobs agendados
    ├── security/          # AuthFilter, PermissionService
    ├── services/          # Servicos de infra (email, vault)
    └── startup/           # Inicializacao

Padrao BFF (Backend for Frontend)¶

O backend expoe duas camadas de API:

Camada	Path	Proposito
API Core	`/api/*`	CRUD direto das entidades
BFF	`/bff/*`	APIs otimizadas para o frontend (dados agregados)

O BFF combina dados de multiplas entidades para reduzir chamadas do frontend.

Seguranca¶

sequenceDiagram
    participant FE as Frontend
    participant AF as AuthFilter
    participant OATH as OATH Service
    participant PS as PermissionService
    participant C as Controller

    FE->>AF: Request + Bearer Token
    AF->>OATH: POST /auth/introspect
    OATH-->>AF: User context
    AF->>AF: Popula UserContext
    AF->>PS: Verifica permissao
    PS->>PS: Checa role + custom permissions
    PS-->>AF: Autorizado
    AF->>C: Request processada

Entidades Principais¶

erDiagram
    Hotel ||--o{ Room : "tem"
    Hotel ||--o{ Venue : "tem"
    Hotel ||--o{ Reservation : "tem"
    Hotel ||--o{ Customer : "tem"
    Hotel ||--o{ UserHotelAssignment : "tem"
    Room ||--o{ Reservation : "recebe"
    Venue ||--o{ Reservation : "recebe"
    Customer ||--o{ Reservation : "faz"
    Reservation ||--o{ Payment : "tem"
    Reservation ||--o{ BreakfastOrder : "tem"
    Room ||--o{ CleaningTask : "tem"
    Hotel ||--o{ Channel : "sincroniza"
    Hotel ||--o{ LedgerEntry : "registra"

Enums Principais¶

Enum	Valores
`ReservationStatus`	PENDING, CONFIRMED, CHECKED_IN, CHECKED_OUT, CANCELLED
`RoomStatus`	AVAILABLE, OCCUPIED, MAINTENANCE, CLEANING, BLOCKED
`RoomType`	SINGLE, DOUBLE, SUITE, DORMITORY, PENTHOUSE
`PaymentMethod`	CREDIT_CARD, DEBIT_CARD, PIX, BANK_TRANSFER, CASH
`PaymentStatus`	PENDING, PROCESSING, COMPLETED, FAILED, REFUNDED
`CleaningStatus`	PENDING, IN_PROGRESS, COMPLETED, VERIFIED
`BreakfastMode`	NONE, EXTRA, INCLUDED
`HotelRole`	HOTEL_ADMIN, HOTEL_GERENTE, HOTEL_SECRETARIA_BALCAO, HOTEL_BAR

Schedulers¶

Scheduler	Intervalo	Funcao
`ChannelSyncScheduler`	30 min	Sincroniza iCal de Airbnb/Booking
`EmailSchedulerService`	Configuravel	Emails automaticos (lembretes)
`WhatsAppSchedulerService`	On-demand	Notificacoes WhatsApp

Frontend¶

Arquitetura¶

hotel-frontend/
├── src/
│   ├── api/               # Camada BFF (Axios)
│   │   ├── client.ts      # Axios com interceptors
│   │   └── bff/           # 24 modulos de servico
│   ├── stores/            # Zustand (auth, hotel, ui)
│   ├── hooks/             # React Query hooks
│   ├── pages/             # 30+ paginas
│   ├── components/        # Componentes reutilizaveis
│   │   ├── layout/        # MainLayout, Sidebar
│   │   ├── ui/            # Atomicos (Button, Input)
│   │   └── [feature]/     # Por modulo
│   └── utils/
│       ├── guards/        # Route guards (Auth, Hotel, Manager)
│       └── zod/           # Schemas de validacao

State Management¶

Store	Ferramenta	Dados
Auth	Zustand (localStorage)	Token, usuario, lista de hoteis
Hotel	Zustand (localStorage)	Hotel selecionado, configuracoes
UI	Zustand	Sidebar, loading, modais
Server	React Query	Dados do servidor (cache 5min)

Guards de Rota¶

Guard	Requisito
`AuthGuard`	Usuario autenticado
`GuestGuard`	Usuario nao autenticado
`HotelGuard`	Hotel selecionado
`ManagerGuard`	Role gerente ou superior
`MasterGuard`	Role master/owner

Configuracao¶

Variaveis de Ambiente (Backend)¶

# Banco
QUARKUS_DATASOURCE_USERNAME=hotel
QUARKUS_DATASOURCE_PASSWORD=hotel123
QUARKUS_DATASOURCE_JDBC_URL=jdbc:postgresql://localhost:5434/hoteldb

# Servicos
OATH_API_URL=http://localhost:5001
GUILD_API_URL=http://localhost:5002
HERALD_API_URL=http://localhost:5004
VAULT_URL=http://localhost:5006
COINKEEPER_WEBHOOK_SECRET=changeme
TAX_COLLECTOR_URL=http://localhost:5007

# Aplicacao
ENCRYPTION_KEY=...
APP_FRONTEND_URL=http://localhost:3000
GUILD_APPLICATION_ID=00000000-0000-0000-0000-000000000002

Variaveis de Ambiente (Frontend)¶

VITE_API_URL=http://localhost:8080/api
VITE_OATH_URL=http://localhost:5001
VITE_FRONTEND_URL=http://localhost:3000

Observabilidade¶

Logs: JSON estruturado para Grafana/Loki
Metricas: Prometheus via Micrometer (/q/metrics)
Audit: AuditLogService registra eventos de seguranca
Scrolls: Logging centralizado de eventos