Arquitetura

Como o painel SaaS, o backend Nest e o resource Lua conversam — e o que vive em cada lado.

Visão geral

Três processos cooperam, cada um com responsabilidade isolada:

topologia.txt·text

           ┌─────────────────────────────┐
           │   Frontend Next.js          │  ← reseller hospeda
           │   (painel multi-tenant)     │
           └──────────────┬──────────────┘
                          │ HTTPS  JWT (refresh 14d)
                          ▼
           ┌─────────────────────────────┐
           │   Backend NestJS + Fastify  │  ← reseller hospeda
           │   + Postgres/MariaDB        │
           └──────────────┬──────────────┘
                          │ HTTP   Bearer + x-tenant-id
                          ▼
           ┌─────────────────────────────┐
           │   FXServer · elite_saas_api │  ← CLIENTE hospeda
           │   Lua resource (vRP based)  │
           └─────────────────────────────┘

Responsabilidades

Frontend (reseller) — UI. Não fala com Lua direto; tudo passa pelo backend.
Backend (reseller) — autenticação multi-tenant, persistência (auditoria, branding, sessões), proxy autenticado para os servidores Lua dos clientes.
Lua (cliente) — fonte de verdade de gameplay. Lê o banco do servidor (vrp_users, mtg_*, snt_*) e expõe via HTTP.

Single source of truth

Gameplay vive no Lua. O painel não duplica saldos, inventário ou veículos — sempre consulta o resource em tempo real.

Fluxo típico de uma requisição

Usuário clica em um jogador no painel.
Frontend chama o backend: GET /v1/fivem/players/{userId} com JWT.
Backend valida JWT, lê luaApiBaseUrl e serverLinkToken do tenant no banco.
Backend faz GET {base}/player/{userId} com Authorization: Bearer + x-tenant-id.
Lua resolve agregando 6+ tabelas (identidade, dinheiro, propriedades, veículos, multas, jobs).
Backend repassa o JSON ao frontend, que renderiza o perfil.

Multi-tenant

O painel é multi-tenant; cada FXServer é um tenant separado. Isolamento em dois níveis:

No banco do painel — toda query carrega tenantId. O JWT inclui tenantId + tenantSlug e o middleware nega cross-tenant.
No FXServer — o resource só responde para o tenantSlug configurado em config.lua e exige o serverLinkToken idêntico. Tokens trocados entre tenants não funcionam.

Camada de adapters

O Lua tem dois grupos de arquivos:

server/*.lua — roteamento, snapshots, métricas. Genérico, não toca no banco do servidor diretamente.
functions/*.lua — adapters específicos do servidor (vRP + mtg_*). Você os edita para mapear ao seu schema sem mexer no core.

Toda função em functions/ usa pcall — se o adapter retornar erro, o painel mostra fallback graceful (partialErrors no perfil) em vez de cair.

Live data vs persistência

O Lua não persiste muito — só os picos diários de jogadores/economia em tabelas auto-criadas (elite_saas_daily_*) e o histórico de punições. Tudo o que é estado da cidade (saldo, inventário, gangs) vem das tabelas do próprio servidor (vRP, mtg_*).

O painel mantém auditoria das ações administrativas (AuditLog), sessões e branding. Eventos do FX são lidos via ring buffer em memória do events_buffer.lua.

AnteriorQuickstart Próxima config.lua