Componentes da Solução

Nesta seção serão detalhados todos os componentes da solução que compõe a stack de desenvolvimento da arquitetura de desenvolvimento corporativo da Embrapa.

Fig. 1 - Stack de desenvolvimento de sistemas institucionais.

Camada	Componentes
Autenticação	Keycloak (OpenID Connect) como Identity Provider institucional
Autorização	ASP.NET Core Identity, com autorização baseada em permissões por perfil
Frontend	HTML5, CSS/Bootstrap, Blazor (Server), Bootstrap Blazor UI, layout Spark
Backend	.NET 10 / ASP.NET Core, Entity Framework Core, arquitetura modular (host + Core + Integrações + módulos em RCL)
Banco de dados	PostgreSQL (dados da aplicação) e MongoDB (leitura dos dados corporativos do ETL, na Sede)
Observabilidade	Sentry (erros) e Matomo (uso e acessos), ambos providos pelo Embrapa I/O
Ferramental	VS Code, GitLab, Docker, Renovate, Embrapa I/O

Autenticação e Autorização

Keycloak (OpenID Connect): a autenticação (login) das soluções construídas sobre o boilerplate é delegada ao Keycloak institucional por meio do protocolo OpenID Connect. O Keycloak passou a ser o hub de autenticação da Embrapa, substituindo a integração direta com o Google OAuth utilizada até 2025.

Cada aplicação possui o seu próprio client OIDC no realm institucional, por ambiente, com as respectivas credenciais (Authority, Client Id e Client Secret). Além do login institucional, a integração do boilerplate contempla:

• revinculação de contas migradas do antigo login Google, de forma transparente para o usuário;
• autocadastro de usuários externos, quando habilitado, apoiado em federação externa configurável no realm;
• modal de aviso de expiração de sessão, com tempos configuráveis por variável de ambiente.

Como a autenticação é delegada por um protocolo padrão, integrar outros provedores (Gov.br, Microsoft Entra, LDAP externo) passa a ser uma configuração de realm no Keycloak, e não uma alteração de código na aplicação.

Para mais detalhes, consulte a documentação oficial do Keycloak e a documentação do OpenID Connect no ASP.NET Core.

ASP.NET Core Identity: é uma API que suporta a funcionalidade de login da interface do usuário em aplicativos Web. Ela gerencia usuários, dados de perfil, funções, declarações, tokens, confirmação por e-mail e muito mais. No boilerplate, ela é utilizada para implementar os recursos de autorização — os de autenticação são providos pelo Keycloak.

A autorização é baseada em permissões, não em perfis: o código conhece apenas permissões (ações granulares e estáveis, como Auditoria.Consultar), e o vínculo entre perfil e permissões fica no banco, gerenciado em tempo de execução por uma tela administrativa. Criar um perfil novo ou mudar o que um perfil pode fazer é operação de dados, não de código. Veja o detalhamento na seção Boilerplates.

Para mais detalhes, consulte a documentação oficial.

Frontend

A camada de frontend da solução utiliza vários recursos para promover os melhores resultados na UI de usuários WEB. Vão desde o HTML5, passando por CSS (Bootstrap) e componentes Blazor.

HTML5: É a quinta versão do HyperText Markup Language (HTML), a linguagem de marcação usada para estruturar e exibir conteúdo na web1. Ele traz novos recursos e melhorias, aprimorando a experiência de desenvolvimento e navegação.

Bootstrap: É uma das bibliotecas mais populares para desenvolvimento frontend. Com ele, pode-se criar rapidamente sites responsivos e repletos de recursos. Ele oferece uma variedade de componentes prontos, como botões, formulários, navegação e muito mais. Além disso, seu sistema de grid facilita o layout responsivo.

Para mais detalhes, consulte a documentação oficial.

Blazor: É uma estrutura moderna de front-end baseada em HTML, CSS e C# que permite criar aplicativos web full stack sem a necessidade de JavaScript. Com o Blazor, é possível:

• Criar belas experiências de usuário usando componentes reutilizáveis.
• Conectar-se a dados vinculando-se a modelos de dados fortemente tipados.
• Implementar segurança com facilidade, configurando políticas de autenticação e autorização.
• Interoperar com JavaScript, chamando bibliotecas e APIs existentes diretamente do C#.
• Executar aplicativos Blazor no cliente (usando WebAssembly) ou no servidor (com ASP.NET Core)

Para mais detalhes, consulte a documentação oficial.

Bootstrap Blazor UI: O Bootstrap Blazor é um framework de componentes UI open source que combina as funcionalidades do Bootstrap com o ecossistema .NET/Blazor. Oferece mais de 70 componentes pré-construídos, incluindo gráficos, grids, modais e outros elementos de interface, todos otimizados para desempenho e responsividade. A biblioteca suporta interações tanto no lado do cliente (via WebAssembly) quanto no servidor (via SignalR), é compatível com PWA (Progressive Web Applications) e é totalmente desenvolvida em C#, eliminando a necessidade de JavaScript na maioria dos casos. Seus componentes seguem os padrões de design do Bootstrap, oferecem suporte à personalização de temas, localização em múltiplos idiomas e se integram naturalmente ao ecossistema .NET, proporcionando uma experiência de desenvolvimento mais fluida e eficiente.

Para mais detalhes, consulte a documentação oficial.

Backend

ASP.NET Core: É uma estrutura moderna de desenvolvimento web de alto desempenho para a plataforma .NET. Ele pode ser executado no Windows, Linux, macOS e Docker. Algumas características importantes do ASP.NET Core incluem:

1. Desempenho: O ASP.NET Core é mais rápido do que outras estruturas populares, conforme avaliado pelo TechEmpower.
2. Modernidade e inovação: Ele permite que componentes de runtime, APIs, compiladores e linguagens evoluam rapidamente, mantendo a estabilidade para os aplicativos em execução. Diferentes versões podem coexistir no mesmo servidor.
3. Código aberto: Assim como o restante do .NET, o ASP.NET Core é de código aberto no GitHub, com milhares de contribuições da comunidade.
4. Implantação flexível: Pode ser implantado como parte do aplicativo ou centralmente no servidor. Também é adequado para contêineres do Docker.
5. Suporte: A Microsoft oferece versões oficiais com suporte, garantindo estabilidade e segurança para aplicativos de produção.

Os boilerplates do embrapa4dev estão atualmente na versão .NET 10, utilizando o formato de solution .slnx e o gerenciamento centralizado de versões de pacote (Central Package Management).

Para mais detalhes, consulte a documentação oficial.

Entity Framework Core: É um mapeador moderno de relação de objetos que permite criar uma camada de acesso a dados limpa, portátil e de alto nível com o .NET (C#) em vários bancos de dados, incluindo SQL Server, SQLite, MySQL, PostgreSQL e Azure Cosmos DB. Ele elimina a necessidade de grande parte do código de acesso a dados que os desenvolvedores normalmente precisam escrever.

No boilerplate, o EF Core é utilizado sem Migrations: o schema é versionado em scripts SQL executados na criação do contêiner do banco — a aplicação nunca executa DDL. O acesso a dados é sempre feito por IDbContextFactory, como recomendado para Blazor Server.

Para mais detalhes, consulte a documentação oficial.

Arquitetura modular: desde 2026 o boilerplate blazorpost é organizado em uma solution multi-projeto — um host Blazor Server, um projeto Core (contratos, auditoria, modelos institucionais) e um projeto Integracoes (gateways corporativos) — no qual cada módulo de negócio da solução derivada vive em uma Razor Class Library própria. A fronteira entre plataforma e domínio é garantida pelo compilador. O detalhamento está na seção Modularização.

Banco de dados

PostgreSQL: é o SGBD relacional padrão das soluções construídas sobre o boilerplate, usado para os dados da própria aplicação (Identity, auditoria e o domínio de negócio). Cada módulo de negócio pode ter schema, usuário e conexão próprios dentro da mesma instância.

MongoDB: é a fonte dos dados corporativos consumidos pelas soluções (empregados, unidades, pessoas físicas e jurídicas, localidades), disponibilizados pelo processo de ETL corporativo. O acesso é somente leitura e sempre indireto, por meio dos gateways institucionais do boilerplate — a aplicação nunca persiste a entidade corporativa inteira, apenas a chave (matrícula, id de unidade).

Importante: o MongoDB corporativo só é acessível a partir da rede da Sede. Essa é a configuração padrão do boilerplate porque ela atende aos sistemas corporativos desenvolvidos pelo GTI. Soluções hospedadas fora da Sede devem consumir os dados corporativos pelas APIs corporativas, substituindo as implementações dos gateways no projeto Integracoes — as interfaces e todo o restante da aplicação permanecem iguais. Veja o item 8 do FAQ.

Essa integração substituiu o consumo das APIs corporativas de empregado e unidade via API Gateway, que era o modelo adotado até 2025.

Importante ressaltar que a plataforma .NET, via pacotes disponibilizados pela comunidade e/ou DB providers, suporta uma grande gama de soluções de SGBD relacionais, NoSQL e até colunares. O banco de dados Oracle ainda é utilizado em várias soluções legadas, que em muitos cenários são provedoras de informações de integração.

Ferramental de apoio

Embrapa I/O: é a plataforma institucional de gestão do ciclo de vida das soluções (criação do projeto e da aplicação a partir do boilerplate, configuração de variáveis e volumes, build, deploy e monitoramento). Para mais detalhes, consulte a documentação oficial.

Visual Studio Code (VS Code): É um editor de código-fonte gratuito e altamente extensível desenvolvido pela Microsoft. Ele oferece suporte a várias linguagens de programação, incluindo C# e F#.

Para baixar a ferramenta, consulte o site oficial.

GitLab: É uma plataforma abrangente que integra ferramentas de desenvolvimento, segurança e operações em um único lugar. Ele ajuda a automatizar, proteger e implantar seu software de maneira mais rápida e eficiente.

Para mais detalhes, consulte a documentação oficial.

Docker: É uma tecnologia de conteinerização open source. Ela permite que desenvolvedores criem, entreguem e executem aplicações em containers Linux. Esses containers são como máquinas virtuais leves e modulares, oferecendo flexibilidade para implantar, copiar e migrar entre ambientes. Em resumo, o Docker automatiza a implantação de apps e facilita sua execução em ambientes isolados.

Para mais detalhes, consulte a documentação oficial.

Renovate: automatiza a abertura de merge requests para atualização das dependências do projeto. Os boilerplates já vêm com o arquivo renovate.json configurado.

Sentry e Matomo: providos pelo Embrapa I/O para, respectivamente, o rastreamento de erros (bug.embrapa.io) e o rastreamento de uso e acessos (hit.embrapa.io) das soluções publicadas.

* Parte das descrições das soluções apresentadas nesta documentação foi gerada com apoio de IA.