Archon UI

A contraparte frontend do Archon Framework. Enquanto o framework padroniza o backend, o Archon UI padroniza como toda SPA do ecossistema autentica, consome a API e renderiza, de forma que as duas pontas falam exatamente a mesma língua.

A decisão por trás do projeto

O mesmo problema que existe no backend existe no frontend: quando cada aplicação React nasce separada, todas acabam reimplementando login, cliente HTTP, layout, permissões e feedback do seu próprio jeito. O resultado é divergência visual e, pior, divergência de contrato com o backend.

O Archon UI resolve isso sendo uma biblioteca compartilhada, distribuída como pacote e consumida por todas as SPAs do ecossistema (Identity Management, Integration Platform e Kanvas). Uma aplicação consumidora envolve a árvore em providers, configura as URLs base e passa a usar componentes e hooks. O resto, autenticação, consumo de API, permissões, já vem resolvido.

Login OIDC do lado do cliente

A parte mais densa da biblioteca é o fluxo de autenticação. Ela implementa o lado cliente de um login OIDC com PKCE: o usuário se identifica, escolhe o contrato quando há mais de um, e a lib gera state, nonce e code_verifier, guarda no sessionStorage e redireciona para o Identity Management. No retorno, o componente de callback valida state e nonce, troca o code mais o code_verifier por tokens, decodifica o JWT e popula o contexto de autenticação.

Há dois modos suportados, login por API direta e SSO via OIDC, e um cuidado específico para não piscar a tela de dashboard antes do redirecionamento final. É um fluxo onde cada detalhe (a ordem dos passos, a validação anti-replay, a montagem da URL de retorno) tem que estar certo, porque é a fronteira de segurança da aplicação inteira.

Cliente HTTP com refresh transparente

O cliente HTTP é um wrapper sobre Axios com interceptors que tornam a autenticação invisível para a tela. Em cada requisição ele injeta o token e o idioma ativo. Quando uma resposta volta com 401, ele dispara o refresh do token automaticamente e repete a requisição original; se o refresh falha, faz logout. Ele também integra o loader global e normaliza erros do backend (incluindo ProblemDetails) para um formato plano de mensagem e erros.

Quem escreve uma tela só faz get/post/put/delete e recebe os dados; expiração de token, retry e tratamento de erro acontecem por baixo.

Consumo de API alinhado ao backend

O hook de API entende nativamente o envelope de resposta do Archon Framework: extrai dados, paginação, mensagens e erros de validação, e oferece toast automático configurável. A tela recebe estado de carregamento, erro, dados e paginação prontos, sem desempacotar resposta manualmente.

Isso só funciona porque o contrato é o mesmo dos dois lados: o backend sempre responde no mesmo envelope, e o frontend sempre o lê do mesmo jeito. É essa simetria que elimina a camada de adaptação que normalmente existe entre API e interface.

Permissões coerentes com o backend

O ponto que melhor mostra a integração entre os dois frameworks é a autorização. O hook de permissões decodifica o JWT e expõe verificações como "tem essa permissão", "tem alguma destas", "tem todas" e "é root", lendo exatamente o mesmo formato de claim (permission no padrão controller.action, e root) que o Archon Framework emite.

Ou seja: a mesma decisão de acesso que protege um endpoint no backend controla a renderização de um botão no frontend, a partir da mesma fonte. Não há dois modelos de permissão para manter em sincronia, há um só, consumido nas duas pontas.

Sistema de componentes

Por baixo da infraestrutura, há uma biblioteca de UI construída sobre primitivas headless (Radix) e Tailwind, com um tema baseado em tokens de cor e variantes tipadas. Ela entrega o que uma aplicação administrativa precisa: layout completo (sidebar, navbar, breadcrumb, page layout), formulários, tabelas com paginação e filtro, modais e drawers, toasts, e gráficos. A internacionalização é própria (pt-BR, en-US e es-AR), com a cultura ativa propagada automaticamente para o backend no cabeçalho de idioma.

A biblioteca é construída em modo lib, com geração de tipos, e mantém um playground interno de componentes para servir de vitrine e ambiente de validação.

Como uma aplicação consome

O setup de um consumidor é declarativo: importar os estilos, configurar as URLs base e compor a árvore com os providers de tema, loader, i18n e autenticação, protegendo as rotas com o guard e o callback prontos. A partir daí, a aplicação foca nas suas telas; toda a parte transversal, da sessão à navegação, vem da lib.

Diferenciais do projeto

• biblioteca React distribuída como pacote, consumida por todas as SPAs do ecossistema;
• login OIDC com PKCE implementado no cliente, com dois modos (API direta e SSO);
• cliente HTTP com refresh de token transparente, retry de 401 e normalização de erro;
• hook de API que consome nativamente o envelope do backend, sem camada de adaptação;
• modelo de permissão único: o mesmo claim protege o endpoint e controla a interface;
• sistema de componentes sobre Radix e Tailwind, com tema tokenizado e i18n próprio;
• coerência ponta a ponta com o Archon Framework: um envelope, um formato de claim, um fluxo de auth.

Resumo executivo

O Archon UI é a fundação frontend do ecossistema. Ele padroniza autenticação, consumo de API, permissões e interface para todas as aplicações React que vivem sobre o Archon, fechando o par com o framework de backend.

É o projeto que mostra o pensamento de plataforma do lado do cliente: não apenas componentes reutilizáveis, mas a garantia de que backend e frontend compartilham o mesmo contrato, a mesma autorização e o mesmo fluxo de segurança, de ponta a ponta.