Decisão de Stack Tecnológica - ifpebj-ti/controle-acesso-veiculos GitHub Wiki

Decisão de Stack Tecnológica

Projeto: Controle de Acesso de Veículos
Instituição: Instituto Federal de Pernambuco — Campus Belo Jardim
Disciplina: Projeto Integrador — Práticas Reais de Software e Segurança
Equipe: José Ernandes Gonçalves Costa; Raíssa Beatriz Marinho dos Santos
Cliente inicial: Eurico Lopes — Setor de Transporte
Versão: 0.5 Status: Stack, persistência, segurança e fluxos técnicos do MVP implementados; implantação institucional pendente Data de referência: 29 de agosto de 2026 Issue relacionada: #14 — Documentar decisão de stack tecnológica
Issues relacionadas à implementação: #16 — Estruturar monorepo inicial

1. Objetivo

Este documento registra as decisões de stack tecnológica, arquitetura e infraestrutura do projeto Controle de Acesso de Veículos.

As decisões orientam:

Desenvolvimento do frontend.
Desenvolvimento do backend.
Persistência dos dados.
Organização arquitetural.
Testes.
Containerização.
Integração contínua.
Implantação futura na OCI.
Operação e manutenção do sistema.

O documento separa explicitamente:

Stack de aplicação.
Decisões arquiteturais.
Infraestrutura e entrega.
Ferramentas implementadas.
Decisões técnicas ainda pendentes.

2. Contexto do projeto

O sistema será desenvolvido para apoiar ou substituir o processo manual de controle de entrada, saída e movimentação de veículos do IFPE Campus Belo Jardim.

O MVP está concentrado nos Formulários nº 01 e nº 02 e deve contemplar preliminarmente:

Cadastro de veículos.
Cadastro de pessoas relacionadas a veículos.
Associação entre pessoas e veículos.
Registro de entrada.
Registro de saída.
Consulta por placa, veículo, condutor, motorista e período.
Controle de veículos institucionais.
Registro de motorista.
Registro de quilometragem.
Registro de itinerário.
Correções controladas.
Auditoria.
Perfis e permissões.

A estrutura do monorepo, a persistência PostgreSQL, autenticação e o primeiro caso de uso operacional já foram implementados. Os demais casos de uso e as telas funcionais permanecem pendentes.

O frontend será responsabilidade principal de Raíssa Beatriz Marinho dos Santos.

Backend, banco de dados, DevSecOps, infraestrutura e QA terão responsabilidade principal de José Ernandes Gonçalves Costa.

3. Tecnologias e direcionamentos

3.1. Stack principal

Categoria	Item	Decisão	Situação
Stack — Frontend	Biblioteca de interface	React	Implementado na estrutura inicial
Stack — Frontend	Linguagem	TypeScript	Implementado na estrutura inicial
Stack — Frontend	Build	Vite	Implementado e validado
Stack — Frontend	Estilização	Tailwind CSS 4 + `@tailwindcss/vite`	Implementado e validado
Stack — Frontend	Gerenciador de dependências	npm	Implementado
Stack — Frontend	Lint	ESLint	Implementado e validado
Stack — Backend	Framework	ASP.NET Core Web API	Estrutura inicial criada
Stack — Backend	Linguagem	C#	Implementado na estrutura inicial
Stack — Backend	Versão	.NET 10 e `net10.0`	Implementado e validado
Stack — Backend	Solução	`.slnx`	Implementada
Stack — Dados	Banco de dados	PostgreSQL 16	Configurado para desenvolvimento e containers
Stack — Dados	ORM	Entity Framework Core 10 com Npgsql	Implementado
Stack — Dados	Migrações	Entity Framework Core Migrations	Duas migrations versionadas
Arquitetura	Organização interna do backend	Clean Architecture adaptada ao MVP	Estrutura inicial criada
Arquitetura	Estilo de aplicação	Monólito modular	Confirmado
Infraestrutura	Containerização	Docker e Docker Compose	Estrutura inicial criada
Infraestrutura	CI/CD	GitHub Actions	Implementado e validado
Infraestrutura	Hospedagem futura	VM Linux na OCI	Confirmado; não implementado
Licença	Licença do repositório	Apache License 2.0	Implementada

3.2. Resumo

Stack de aplicação
- Frontend: React + TypeScript + Vite + Tailwind CSS 4
- Backend: ASP.NET Core Web API + C# + .NET 10
- Banco de dados: PostgreSQL
- ORM e migrations: Entity Framework Core

Arquitetura
- Clean Architecture adaptada ao MVP no backend
- Monólito modular
- API Web organizada em camadas

Infraestrutura e entrega
- Docker e Docker Compose
- GitHub Actions
- VM Linux futura na OCI
- Proxy reverso, HTTPS, logs, monitoramento e backup: pendentes

4. Decisão sobre .NET 10

4.1. Versão adotada

O backend utiliza:

.NET 10
Target Framework: net10.0
Formato de solução: .slnx

4.2. Situação atual

O SDK .NET 10 está disponível no ambiente principal de desenvolvimento.

A solução backend foi criada e validada com:

dotnet restore src/backend/ControleAcessoVeiculos.slnx
dotnet build src/backend/ControleAcessoVeiculos.slnx --no-restore
dotnet test src/backend/ControleAcessoVeiculos.slnx --no-build --verbosity normal

4.3. Justificativa

A adoção do .NET 10 foi confirmada pela equipe porque:

O SDK está instalado e disponível no ambiente principal.
Possui compatibilidade com ASP.NET Core Web API.
Possui compatibilidade com Docker e Linux.
É compatível com execução futura em VM Linux na OCI.
Suporta Entity Framework Core e PostgreSQL.
Permite desenvolvimento orientado a objetos em C#.
É adequado para uma API com regras de negócio, auditoria, validações e perfis de acesso.
O período de suporte cobre o desenvolvimento e a entrega planejada do projeto.

4.4. Regra de implementação

Todos os projetos backend devem manter:

<TargetFramework>net10.0</TargetFramework>

Alterações de versão deverão ser discutidas pela equipe e registradas na Matriz de Ferramentas Técnicas.

5. Justificativa da stack

5.1. Frontend com React, TypeScript, Vite e Tailwind CSS

O frontend utiliza React, TypeScript, Vite e Tailwind CSS 4.

A escolha permite:

Criar uma interface web para portaria e Setor de Transporte.
Trabalhar com componentes reutilizáveis.
Utilizar tipagem estática no frontend.
Gerar builds rápidos para desenvolvimento e produção.
Criar formulários e telas administrativas futuramente.
Aplicar estilos responsivos e customizados com Tailwind CSS.
Manter flexibilidade visual para a interface definida pela equipe.

A configuração de Tailwind foi realizada com o plugin oficial:

@tailwindcss/vite

O projeto não utiliza mais a configuração legada baseada em tailwind.config.js e postcss.config.js.

5.2. Backend com ASP.NET Core e C#

A escolha de ASP.NET Core Web API com C# considera:

Experiência da pessoa responsável pelo backend.
Adequação a orientação a objetos.
Suporte à organização em camadas.
Compatibilidade com Clean Architecture.
Recursos para autenticação e autorização.
Compatibilidade com Entity Framework Core.
Facilidade de evolução para testes automatizados.
Compatibilidade com Docker, Linux e OCI.
Adequação a regras de negócio, auditoria e validações.

5.3. PostgreSQL

PostgreSQL foi escolhido como banco de dados relacional porque o projeto possui relações estruturadas entre:

Pessoas.
Veículos.
Relações entre pessoas e veículos.
Registros de acesso.
Viagens institucionais.
Usuários.
Perfis.
Auditoria.

O banco relacional oferece:

Chaves estrangeiras.
Integridade referencial.
Transações.
Consultas por período.
Consultas por placa.
Consultas por motorista.
Relacionamentos muitos-para-muitos.
Suporte adequado à auditoria.

5.4. Entity Framework Core

Entity Framework Core será utilizado como ORM e camada de acesso a dados.

Ele permitirá:

Mapear entidades C# para tabelas.
Configurar relacionamentos.
Aplicar consultas tipadas.
Criar migrations.
Evoluir o esquema do banco de forma versionada.
Organizar persistência na camada Infrastructure.

O uso do ORM não elimina a necessidade de compreender SQL, modelagem relacional, índices, transações e desempenho.

5.5. Clean Architecture adaptada

Clean Architecture é uma decisão arquitetural, não uma tecnologia da stack.

Ela será aplicada de forma adaptada ao tamanho do MVP, evitando complexidade artificial e mantendo separação entre:

Domain.
Application.
Infrastructure.
API.

A estrutura inicial foi criada como:

src/backend/
├── ControleAcessoVeiculos.slnx
├── ControleAcessoVeiculos.API/
├── ControleAcessoVeiculos.Application/
├── ControleAcessoVeiculos.Domain/
└── ControleAcessoVeiculos.Infrastructure/

5.6. Docker e Docker Compose

Docker e Docker Compose são decisões de infraestrutura e entrega.

A estrutura inicial foi criada com:

Dockerfile do backend.
Dockerfile do frontend.
Configuração Nginx inicial do frontend.
docker-compose.yml com frontend, backend e PostgreSQL.

A execução integrada com Docker Compose ainda precisa ser validada antes de ser considerada pronta para uso.

5.7. GitHub Actions

GitHub Actions foi configurado para automação inicial de qualidade.

Foram criados workflows para:

Restore e build do backend.
Execução de testes existentes no backend.
Instalação de dependências do frontend.
Lint do frontend.
Build do frontend.

Os checks foram executados com sucesso no Pull Request da estrutura inicial do monorepo.

A pipeline deverá evoluir gradualmente para contemplar:

lint
    ↓
build
    ↓
testes unitários
    ↓
testes de integração
    ↓
cobertura
    ↓
análise de dependências
    ↓
build de imagens
    ↓
análise de imagens
    ↓
publicação ou deploy futuro

5.8. Apache License 2.0

O repositório utiliza Apache License 2.0.

A licença foi mantida porque já fazia parte do repositório e estabelece permissões e condições claras para uso, reprodução, modificação e distribuição do código.

6. Arquitetura da solução

6.1. Camadas do backend

┌─────────────────────────────────────────┐
│ API                                     │
│ Endpoints HTTP, DI, middlewares          │
└──────────────────────┬──────────────────┘
                       │
┌──────────────────────▼──────────────────┐
│ Application                             │
│ Casos de uso, DTOs, interfaces          │
└──────────────────────┬──────────────────┘
                       │
┌──────────────────────▼──────────────────┐
│ Domain                                  │
│ Entidades, regras e contratos           │
└──────────────────────▲──────────────────┘
                       │
┌──────────────────────┴──────────────────┐
│ Infrastructure                          │
│ EF Core, PostgreSQL e integrações       │
└─────────────────────────────────────────┘

6.2. Responsabilidades das camadas

Camada	Responsabilidades previstas
Domain	Entidades, regras de negócio, contratos, enums e objetos de valor
Application	Casos de uso, DTOs, interfaces e orquestração das regras
Infrastructure	Persistência, `DbContext`, EF Core, PostgreSQL, repositórios e integrações
API	Endpoints, injeção de dependência, middlewares, autenticação e tratamento de erros

6.3. Estrutura do frontend

A arquitetura interna detalhada do frontend ainda será estruturada em issue específica.

A organização prevista inclui:

src/frontend/src/
├── components/
├── pages/
├── routes/
├── services/
├── hooks/
├── types/
├── utils/
├── App.tsx
├── main.tsx
└── index.css

7. Banco de dados e persistência

7.1. Entidades preliminares

O modelo relacional deverá considerar:

Pessoa.
Veículo.
PessoaVeiculo.
CategoriaAcesso.
RegistroAcesso.
UsoVeiculoInstitucional.
Usuário.
Perfil.
Auditoria.

7.2. Relações principais

Pessoa 1 ─── N PessoaVeiculo N ─── 1 Veiculo

Pessoa 1 ─── N RegistroAcesso N ─── 1 Veiculo

CategoriaAcesso 1 ─── N RegistroAcesso

Veiculo 1 ─── N UsoVeiculoInstitucional

Pessoa 1 ─── N UsoVeiculoInstitucional

Pessoa 1 ─── 0..1 Usuario

Perfil 1 ─── N Usuario

Usuario 1 ─── N Auditoria

7.3. Migrations

Migrations serão utilizadas para versionar mudanças no esquema do banco.

Fluxo previsto:

Alteração no modelo
    ↓
Criação da migration
    ↓
Revisão do código gerado
    ↓
Execução em desenvolvimento
    ↓
Execução controlada em homologação
    ↓
Execução controlada em produção

Comandos previstos:

dotnet ef migrations add <NomeDaMigration>
dotnet ef database update

Esses comandos só serão utilizados após instalação do Entity Framework Core, configuração do provider PostgreSQL e validação do modelo de dados.

8. Testes e qualidade

8.1. Estado atual

Foram validados:

Backend
- dotnet restore
- dotnet build
- dotnet test

Frontend
- npm run lint
- npm run build

Ainda não existem projetos de testes automatizados de domínio, integração ou ponta a ponta.

8.2. Estratégia prevista

A estratégia preliminar considera:

xUnit para testes unitários de backend.
FluentAssertions, se aprovado.
Vitest e Testing Library para frontend.
Testes de integração com PostgreSQL.
Testes de API.
Testes de autorização.
Testes de auditoria.
Testes de migrations.
Playwright como evolução futura para testes ponta a ponta.

8.3. Fluxos críticos

Testes devem priorizar:

Registro de entrada.
Registro de saída.
Veículo institucional.
Quilometragem.
Itinerário.
Consulta histórica.
Veículos sem saída.
Correções.
Auditoria.
Autenticação.
Autorização.

9. Segurança e DevSecOps

A stack deverá seguir o documento Segurança e Privacidade.

9.1. Requisitos técnicos de segurança

Autenticação.
Autorização por perfil.
Senhas armazenadas somente como hash.
Validação de entrada.
Proteção contra exposição de dados pessoais.
Auditoria.
Controle de correções.
Proteção de segredos.
Dependências atualizadas.
HTTPS na implantação.
Backup protegido.

9.2. Segredos

Nunca versionar:

Senhas.
Tokens.
Chaves privadas.
Strings de conexão reais.
Segredos JWT.
Credenciais OCI.
Chaves SSH privadas.
Dados pessoais reais usados em testes.

O .gitignore inicial já inclui arquivos .env e arquivos locais de ambiente.

9.3. Evoluções previstas

Dependabot.
Secret Scanning.
Análise estática.
Scanner de imagens Docker.
Verificação de dependências.
Análise de cobertura.
SAST e DAST, quando aplicável.

10. Containerização

10.1. Containers previstos

Frontend React
Backend ASP.NET Core
PostgreSQL
Proxy reverso futuro

10.2. Estrutura criada

infrastructure/
└── docker/
    ├── frontend/
    │   ├── Dockerfile
    │   └── nginx.conf
    ├── backend/
    │   └── Dockerfile
    └── docker-compose.yml

10.3. Estado atual

Dockerfile de frontend criado.
Dockerfile de backend criado.
Nginx inicial criado para servir o frontend.
Docker Compose inicial criado.
Serviços previstos: frontend, backend e PostgreSQL.
Execução integrada ainda precisa de validação.

11. CI/CD

11.1. Estrutura criada

.github/
└── workflows/
    ├── ci-backend.yml
    └── ci-frontend.yml

11.2. Workflow do backend

O workflow backend executa:

Checkout
    ↓
Configuração do .NET 10
    ↓
Restore da solução .slnx
    ↓
Build
    ↓
Testes existentes

11.3. Workflow do frontend

O workflow frontend executa:

Checkout
    ↓
Configuração do Node.js
    ↓
Instalação de dependências
    ↓
Lint
    ↓
Build

11.4. Estado atual

Checks de backend aprovados.
Checks de frontend aprovados.
Cobertura coletada na CI, sem meta percentual aprovada.
262 testes de Domain, Application, API e PostgreSQL integrados à main.
Build, scan e publicação multi-arquitetura das imagens versionadas automatizados na CI para tags de release revisadas.
Compose para consumo das imagens publicadas implementado; implantação institucional na OCI ainda não realizada.

12. OCI e implantação futura

12.1. Direcionamento

A OCI será utilizada futuramente para hospedar a aplicação em VM Linux.

A equipe deverá estudar:

IAM.
MFA.
Compartments.
Compute.
VCN.
Subnets.
Security Lists ou NSGs.
IP público.
SSH.
Armazenamento.
Firewall.
Backup.
Monitoramento.
Custos e limites.

12.2. Cenário futuro

Usuário
    ↓
Domínio
    ↓
HTTPS
    ↓
Proxy reverso
    ↓
Container frontend
    ↓
Container backend
    ↓
PostgreSQL
    ↓
Backup e monitoramento

12.3. Estado atual

OCI é um direcionamento de implantação futuro.
VM ainda não criada.
VCN ainda não criada.
Rede ainda não configurada.
Deploy ainda não realizado.

13. Pendências técnicas

13.1. Frontend

Implementar telas e fluxos funcionais do MVP na estrutura existente.
Integrar serviços HTTP aos endpoints quando seus contratos forem definidos.
Prettier.
Vitest.
Testing Library.
Estratégia de autenticação.
Gerenciamento de estado, se necessário.
Design system e tema.

13.2. Backend

Casos de uso da camada Application.
Endpoints de negócio e seus contratos.
Evolução contínua dos testes xUnit conforme novos fluxos e riscos.
FluentAssertions.
Swagger/OpenAPI.
Autenticação.
Autorização.
Formato de erros.
Logging.
Tratamento global de exceções.
Seed de dados.

13.3. Infraestrutura

Validar execução do Docker Compose.
Configurar ambiente de homologação.
Definir proxy reverso.
Configurar HTTPS.
Definir domínio.
Definir monitoramento.
Definir backup e recuperação.
Definir estratégia de deploy.
Definir infraestrutura detalhada na OCI.

14. Consequências da decisão

14.1. Benefícios

Aproveitamento da experiência da equipe em C# e .NET.
Backend orientado a objetos e organizado.
Separação clara entre camadas.
Frontend moderno com React, TypeScript, Vite e Tailwind.
Integração adequada com PostgreSQL.
Compatibilidade com Docker.
Compatibilidade com Linux e OCI.
Base inicial para CI.
Possibilidade de evolução para segurança, auditoria e testes automatizados.

14.2. Custos e riscos

Necessidade de dominar Entity Framework Core e migrations.
Necessidade de configurar autenticação e autorização corretamente.
Necessidade de aprender Docker para .NET, React e PostgreSQL.
Necessidade de estudar OCI, redes, VM e segurança.
Necessidade de manter contratos consistentes entre frontend e backend.
Necessidade de evitar complexidade excessiva na Clean Architecture.
Necessidade de validar a execução integrada do Docker Compose.

14.3. Limites da decisão

Esta decisão não define:

Regras institucionais finais.
Campos obrigatórios finais.
Permissões definitivas.
Necessidade de RG ou CPF.
Ambiente de produção.
Serviços específicos da OCI.
Biblioteca definitiva de autenticação.
Proxy reverso.
Ferramenta definitiva de observabilidade.
Data de implantação.

15. Atualizações documentais

A implementação inicial exige manter sincronizados:

Documento	Atualização necessária
Arquitetura de Software — arc42	Registrar monorepo, camadas backend, estrutura frontend, CI e Docker Compose
Matriz de Ferramentas Técnicas	Registrar ferramentas implementadas, validadas e pendentes
Estratégia de Testes	Registrar os 262 testes integrados e a evolução por risco
Guia de Execução, Configuração, Deploy e Operação	Registrar comandos reais para .NET 10, Vite e Tailwind CSS 4
Segurança e Privacidade	Registrar `.gitignore`, Apache 2.0, proteção de segredos e CI inicial
README do repositório	Registrar estrutura real e instruções locais atualizadas
Status do Projeto	Registrar conclusão da estrutura inicial do monorepo

16. Status, validação e próximas etapas

Documento: Decisão de Stack Tecnológica
Versão: 0.5 Status: Stack, persistência, segurança e fluxos técnicos do MVP implementados; implantação institucional pendente Issue relacionada: #14 — Documentar decisão de stack tecnológica
Issue de implementação: #16 — Estruturar monorepo inicial

Estado da implementação

Item	Situação
Monorepo	Criado e integrado à `main`
Backend	Estrutura inicial criada e compilada
Frontend	Criado, lintado e compilado
Tailwind CSS 4	Configurado e validado
PostgreSQL 16	Configurado no Compose e integrado ao backend
Entity Framework Core 10	DbContext, Fluent API e migrations implementados
Dockerfiles	Frontend e backend criados; endurecimento e scans implementados (#25)
Docker Compose	Frontend, backend e PostgreSQL configurados
GitHub Actions	Criado e validado
Testes de domínio	60 testes integrados à `main`
Testes ampliados	254 de backend e 431 de frontend na baseline de 28/09/2026
Deploy	Ainda não realizado
OCI	Ainda não configurada