Arquitetura

Esta seção é referência, no sentido de Diátaxis: fato sobre este serviço específico, organizado pra consulta rápida, com o porquê de cada decisão registrado ao lado do fato. Os conceitos gerais por trás de cada peça (o que é arquitetura hexagonal, o que é CQRS, o que é um ORM) estão em Aprender, não repetidos aqui.

O management-service é a API REST/GraphQL de gerenciamento acadêmico do ecossistema Ladesa, construída com NestJS, TypeORM e PostgreSQL, seguindo arquitetura hexagonal.

Se você precisa	Vá pra
As quatro camadas, a estrutura de diretório, os grupos de módulo	Camadas e estrutura
Entidade, schema, repositório, handler, mapper, com exemplo real	Padrões de código
O padrão de mapeamento entre camadas em detalhe (into, createMapper)	Mapeamento entre camadas
Decisões que já foram tomadas e não devem ser reabertas sem justificativa nova	Decisões arquiteturais
Por que NestJS+Bun, JSONB no contrato do solver, e o ADR de mensageria superado	Decisões de arquitetura da plataforma
Nomenclatura de arquivo, formatação, e os princípios de engenharia adotados	Convenções e princípios
Keycloak, JWT mock, fluxo de autorização	Autenticação e autorização
TypeORM, migrações, triggers, transação automática	Banco de dados e transações
Pipeline HTTP real, GraphQL code-first, paginação, erro	APIs REST e GraphQL
BullMQ sobre PostgreSQL, filas de geração de horário	Message broker
Socket.IO, notificações de estágio em tempo real	WebSockets e notificações
Vitest, tipos de teste, helpers disponíveis	Testes
Pipeline de CI/CD, deploy via GitOps e Argo CD	CI/CD e deploy
Cada tecnologia usada e sua versão	Stack tecnológico
Entidades principais e como se relacionam	Diagrama de entidades

flowchart TB
    Apresentacao["Apresentação\nREST + GraphQL"] --> Aplicacao["Aplicação\ncommand/query handlers"]
    Aplicacao --> Dominio["Domínio\nentidades, contratos"]
    Infraestrutura["Infraestrutura\nTypeORM, Keycloak, BullMQ"] -- "implementa contratos de" --> Dominio