Archon Framework

A fundação backend em .NET sobre a qual todo o ecossistema é construído. Em vez de cada API reimplementar tenant, autenticação, autorização e auditoria, o Archon resolve essas decisões uma vez e as entrega prontas para quem nasce em cima dele.

A decisão por trás do projeto

Toda API de um ecossistema interno acaba repetindo os mesmos problemas: descobrir o tenant da requisição e sua conexão, validar o usuário e a sessão, expor endpoints protegidos sem duplicar roteamento, devolver respostas no mesmo formato e auditar mudanças no banco. Resolver isso caso a caso significa segurança inconsistente, manutenção cara e plataforma lenta para evoluir.

O Archon é a resposta a isso: uma fundação única que centraliza essas decisões. Um sistema novo não começa do zero, começa com multi-tenant, auth, autorização, auditoria e contrato de API já resolvidos. Identity Management e Integration Platform são os dois maiores exemplos disso, ambos construídos sobre ele.

Arquitetura em camadas

A solução segue Clean Architecture com a direção de dependência apontando para dentro: Core (tipos fundamentais, sem dependência de framework) ← Application (contratos e interfaces) ← Infrastructure (EF Core, Dapper, migrations, clientes) ← Api (pipeline HTTP, middlewares, atributos). A camada Api referencia tudo; a Core não referencia nada.

Essa direção é o que mantém o domínio isolado da infraestrutura: dá para trocar o resolver de tenant, o provider de banco ou o cliente de identidade sem tocar nas regras centrais.

Multi-tenant por conexão

O tenant é resolvido por requisição, antes de qualquer acesso ao banco, e populado num contexto que toda a infraestrutura subsequente consulta. A resolução é um ponto de extensão: o resolver padrão lê os tenants da configuração (com cache por TTL e semáforo para evitar leitura concorrente do mesmo tenant), mas há um resolver alternativo que busca os tenants de um catálogo externo de identidade.

O efeito prático é que um sistema consumidor escreve seu domínio como se fosse single-tenant; o framework garante que cada requisição opere na conexão certa.

Autenticação JWT dinâmica

Este é um dos pontos mais interessantes. Em vez de fixar a chave de validação na configuração de cada aplicação, o framework resolve a autoridade e as chaves de assinatura em runtime, consultando o Identity Management (discovery OpenID e jwks.json, com cache). A assinatura do token é validada contra essas chaves, o issuer e a audience da configuração, com tolerância de clock skew.

Ou seja: a confiança é descoberta em tempo de requisição, não codificada. Trocar uma chave no centro de identidade se propaga sem redeploy das APIs consumidoras.

Autorização em um atributo só

A autorização inteira passa por um único atributo, RequireAccess, que aceita dois mundos ao mesmo tempo:

• usuário — Bearer JWT, autorizado por claim root=true ou permission=controller.action;
• serviço — segredo de integração via Basic Auth (tenantId:apiKey) ou header X-Api-Key, com comparação em tempo constante.

Unificar os dois num atributo eliminou a necessidade de um atributo separado para integração entre serviços. Quando a autorização vem por segredo, o próprio atributo já resolve e popula o tenant da requisição.

Auditoria automática

A auditoria não é código espalhado por entidade: ela acontece dentro do SaveChangesAsync do contexto base. Antes do commit, o framework preenche os timestamps, tira um snapshot do que foi inserido, alterado e excluído (propriedade a propriedade) e, depois do commit principal, persiste os registros de auditoria numa transação separada e despacha os eventos de domínio acumulados.

Cada registro carrega quem alterou (resolvido do usuário autenticado), o tenant e o id de correlação da requisição (o mesmo trace id). Qualquer entidade do ecossistema ganha auditoria completa só por herdar da entidade base.

Persistência por convenção

A base de dados aplica convenções automáticas ao mapear as entidades (chave long, timestamps preenchidos sozinhos, tamanho padrão de string, precisão padrão de decimal, exclusão restritiva), e configurações manuais continuam podendo sobrescrever quando preciso. A persistência é híbrida: EF Core para escrita, domínio e transação; Dapper para leituras especializadas e sensíveis a performance.

Contrato de API padronizado

Toda resposta sai no mesmo envelope (mensagem, dados, erros, paginação, com campos nulos omitidos), e os controllers base já entregam isso pronto: helpers de contexto da requisição, retornos HTTP tipados, envio de arquivos (PDF, Excel, CSV) e um controller CRUD genérico. As exceções são tipadas e viram resposta padronizada e localizada, sempre com um trace id no log.

Esse contrato único é o que permite ao frontend compartilhado consumir qualquer API do ecossistema sem adaptação, e o que mantém a experiência homogênea entre sistemas diferentes.

Descoberta automática

Duas coisas se montam sozinhas no startup. Os serviços são registrados por convenção a partir do assembly, sem fiação manual de DI. E o catálogo de permissões se alimenta sozinho: o framework varre os endpoints da aplicação, identifica os que têm RequireAccess e os sincroniza com o catálogo central do Identity Management, em background, sem derrubar a API se o sync falhar.

É o que faz o catálogo de permissões do ecossistema refletir o código real, em vez de uma lista mantida à mão.

Diferenciais do projeto

• Clean Architecture com direção de dependência preservada (domínio isolado da infraestrutura);
• multi-tenant por conexão com resolver plugável (configuração ou catálogo externo);
• autenticação JWT validada com autoridade e chaves resolvidas em runtime, sem chave fixa por app;
• autorização unificada de usuário e serviço num único atributo, com comparação em tempo constante;
• auditoria automática dentro do ciclo de persistência, com autor, tenant e correlação;
• contrato de API padronizado consumido por todos os sistemas e pelo frontend compartilhado;
• auto-registro de serviços e auto-sincronização do catálogo de permissões a partir do código.

Resumo executivo

O Archon Framework é a fundação backend em .NET do ecossistema. Ele padroniza, num único lugar, tudo o que é transversal a uma API multi-tenant: identidade, autorização, persistência, auditoria e contrato de resposta, de forma que sistemas novos nascem consistentes e os existentes evoluem sem divergir.

É o projeto que melhor mostra a diferença entre construir aplicações e construir a plataforma que sustenta aplicações, porque uma decisão errada aqui se propaga para todos os sistemas que vivem em cima dele.