Framework frontend · Em uso
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.
- Stack
- React · TypeScript · Radix · Tailwind · Axios · OIDC com PKCE · i18n
- Status
- Em uso
- Relacionado a
Em resumo
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.
Diferenciais
- Biblioteca React distribuída como pacote (ES e UMD), consumida por todas as SPAs do ecossistema
- Login OIDC com PKCE de ponta a ponta: identificação por senha ou por sessão existente (SSO), ambos terminam no mesmo fluxo OIDC
- Cliente HTTP com refresh de token em voo único, retry automático de 401 e normalização de erro, inclusive ProblemDetails
- Logout que revoga o token no Identity Management e força reautenticação, em vez de só limpar o estado local
- Hook de API que consome nativamente o envelope do backend, sem camada de adaptação
- Hook de permissões com capacidades, permissões legadas, papel root e bloqueio de assinatura
- Sistema de componentes sobre Radix e Tailwind, com navegação por módulos, paleta de comandos e i18n próprio
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 (build de biblioteca em ES e UMD, com geração de tipos) e consumida por todas as SPAs do ecossistema (Identity Management, Integration Platform e Mainstay). 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, um cliente OIDC com PKCE completo. Ao iniciar o login, a lib gera state, nonce e code_verifier (64 bytes aleatórios, desafio S256) com a Web Crypto API, guarda tudo no sessionStorage junto com a URL de retorno, e redireciona para o Identity Management. No callback, valida state e exige nonce, troca o code mais o code_verifier por tokens no endpoint /connect/token, e popula o contexto de autenticação.
Existem duas formas de iniciar o fluxo, identificação por senha ou por uma sessão já existente no Identity Management (SSO silencioso), mas as duas terminam no mesmo redirecionamento OIDC: não há um caminho de login direto contra a API que pule o provedor de identidade. O logout também é tratado com cuidado, ele revoga o token no endpoint /connect/revocation e força prompt=login no próximo acesso, em vez de só apagar o estado local.
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 (Accept-Language). Quando uma resposta volta com 401, ele dispara o refresh do token e repete a requisição original; como o Identity Management rotaciona o refresh token a cada uso, várias chamadas simultâneas que expiram junto compartilham a mesma promise de refresh em voo, em vez de disparar refreshes concorrentes que invalidariam uns aos outros. Se o refresh falha, a sessão é limpa. O cliente também integra o loader global e normaliza erros do backend (incluindo ProblemDetails) para um formato plano de mensagem e erros, com timeout de 60 segundos.
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 e capacidades 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 hasPermission, hasAny, hasAll, hasCapability, além de isRoot e isSubscriptionBlocked, lendo exatamente os claims que o Archon Framework e o Identity Management emitem, capacidade de módulo, permissão legada controller.action, papel root e o estado de bloqueio por assinatura.
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. E quando a assinatura do tenant está bloqueada, a interface já sabe disso pelo próprio token, sem precisar de uma chamada extra para descobrir.
Sistema de componentes
Por baixo da infraestrutura, há uma biblioteca de UI construída sobre primitivas headless (Radix), Tailwind v4 e cva para variantes tipadas, com ícones Lucide e gráficos Nivo. Ela entrega o que uma aplicação administrativa precisa: navegação por módulos (rail, painel e versão mobile), paleta de comandos, formulários, tabela de dados com filtros, sheets e modais, toasts, e as telas prontas de gestão de usuários e permissões que usam o próprio modelo de capacidades. 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, e notificações com polling a cada 30 segundos.
A biblioteca 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.