ADR-801: Admin UI & Portal

Status: Accepted

Contexto

middag-account precisa de duas interfaces: admin UI no wp-admin para equipe interna (backoffice), e portal headless para clientes (self-service). Admin UI deve ser React SPA dentro do WordPress sem conflito de CSS. Portal deve consumir REST API v1 — qualquer frontend serve. Tema legado usava Inertia.js com sucesso (96% alinhado).

Decisão

Admin UI — Inertia.js + React no wp-admin

Aspecto	Detalhe
Framework	Inertia.js v2 + React 19 + Tailwind v4
Build	Vite 6 → IIFE → assets/dist/app.js
CSS Isolation	#middag-app { all: initial; } previne vazamento WP
Menu	Item único no wp-admin sidebar → páginas Inertia
Routing	Inertia router (client-side), não page reloads

Build IIFE

Vite compila React app em formato IIFE — um único app.js carregado via wp_enqueue_script. Sem módulos ES externos, sem conflito com outros plugins.

CSS Isolation

#middag-app {
    all: initial;
    /* Tailwind styles dentro deste scope */
}

Previne que CSS do wp-admin vaze para UI middag-account e vice-versa.

Páginas na v5.0

Página	Domínio	Funcionalidade
Dashboard	Cross-domain	Quotes pendentes, entitlements expirando, atividade
Organizations	Organization	Lista + detalhe + edição
Collaborators	Collaborator	Lista + detalhe + convite
Entitlements	Entitlement	Lista + detalhe + gerenciamento de status
Quotes	Quote	Lista + detalhe + ações de lifecycle
Licenses	License	Lista + detalhe
Orders	Order	Lista + detalhe
Invoices	Invoice	Lista + detalhe
Tax Invoices	TaxInvoice	Lista + detalhe + PDF
Contracts	Contract	Lista + detalhe + PDF
Documents	Document	Lista + detalhe + download
Environments	Environment	Lista + detalhe + service requests
Services	Service	Lista + detalhe + service requests
Service Requests	ServiceRequest	Lista + detalhe + criação

Headless-Ready

REST API v1 é a interface canônica. Admin UI consome a mesma API que qualquer portal externo. Se admin UI pode fazer, a API também pode.

Portal NextJS — app.middag.io

Aspecto	Detalhe
URL	app.middag.io — UM portal para TODOS os clientes
Framework	NextJS (frontend separado, repo separado)
Auth	JWT RS256 via REST API v1
Conteúdo	Entitlements, quotes, invoices, licenses, SRs, equipe
Moeda/idioma	Segue Organization (preferred_currency, billing_entity)

Arquitetura de Portal

app.middag.io               → Portal cliente (todos os produtos, todos os clientes)
account.middag.com.br       → Admin UI wp-admin (apenas equipe interna)
account.middag.pro (futuro)  → Portal branded SaaS (mesmo backend API)

Portal por marca é possível — frontend diferente, mesma API.

UI Não É Contrato

Admin UI pode mudar entre versões MINOR. Adotantes NÃO devem depender de classes CSS, estrutura DOM ou IDs de elementos. A API é o contrato — a UI é fluida.

Consequências

Positivas:

• React SPA dentro do wp-admin — UX moderna sem sair do WordPress
• CSS isolation previne conflitos com wp-admin e outros plugins
• Headless-ready — qualquer frontend pode consumir a API
• Portal branded possível via mesma API (white-label futuro)

Negativas:

• IIFE bundle único = tamanho grande (mitigado por code splitting futuro)
• Inertia.js v2 é dependência nicho no ecossistema WP
• Dois frontends (admin + portal) para manter
• CSS isolation com all: initial pode causar edge cases

Especificação Técnica

Detalhes de implementação em REF-801-01:

• InertiaAdapter API (4 métodos, shared props, page object)
• Hybrid Page System (Contract vs Direct pages, Block Registry)
• 14 Page Controllers (method convention, ScopeGuardTrait, DI)
• Vite Build Pipeline (IIFE, config, artifacts)
• CSS Isolation Strategy (3 camadas, portal container)
• WordPress Integration (menu, routing, interception, assets)
• Portal NextJS — 15 módulos e API mapping

Referências

• REF-801-01 — Admin UI Inertia Spec
• ADR-102 — Architecture Foundation (Vite, build pipeline)
• ADR-701 — API & Authentication (REST API consumida por ambos)
• ../reference/personas.md §2-5 — Quem usa cada interface
• operations/03-brand-architecture.md §2 — Arquitetura de portal e domínios