Pular para o conteúdo principal

ADR 0001: visão geral da arquitetura

Introdução ao documento​

Este ADR registra a decisão arquitetural base observada no repositório: manter o frontend como uma aplicação Next.js com App Router, autenticação com NextAuth e uma camada BFF local em src/app/api.

Contexto​

  • O repositório contém rotas de interface e rotas HTTP internas no mesmo projeto.
  • As rotas protegidas dependem de getServerSession(nextAuthOptions).
  • Os serviços BFF e externos já estão separados entre src/app/services/bff e src/app/services/external.
  • O projeto integra múltiplos serviços externos: backend WordPress, agenda, submissões, quiz, Jitsi, Blip e Datadog.

Evidências:

  • src/app/(protected-routes)/layout.tsx:21-74
  • src/utils/authOptions.ts:7-117
  • src/app/services/bff/ScheduleService.ts:14-80
  • src/app/services/external/ClassService.ts:21-258
  • src/app/start/DatadogStart.tsx:10-48

Decisão​

Adotar e manter a seguinte organização arquitetural:

  • Interface web, autenticação e BFF no mesmo projeto Next.js.
  • Rotas internas em src/app/api como ponto de integração entre UI e serviços externos.
  • Sessão centralizada em NextAuth para proteger fluxos do App Router.
  • Serviços TypeScript separados por papel: external para dependências externas e bff para consumo do próprio /api.

Consequências​

Positivas​

  • Menor acoplamento do cliente aos endpoints externos.
  • Reuso de sessão do NextAuth nas rotas protegidas e handlers.
  • Menor atrito para versionar UI e BFF juntos.

Custos e riscos​

  • O contrato HTTP interno precisa de documentação disciplinada, porque cresce no mesmo repositório da UI.
  • A aplicação acumula responsabilidade de frontend, autenticação e proxy.
  • A ausência do código dos serviços externos limita a precisão da documentação de domínio e dados.

Alternativas não adotadas neste baseline​

  • Separar o BFF em um repositório próprio.
  • Fazer o cliente consumir diretamente todas as APIs externas.

Justificativa para não registrar como arquitetura vigente:

  • Não há evidência no repositório de que essas alternativas estejam implementadas.

Pendências​

  • Confirmar se existe uma decisão formal anterior para ownership e limites entre frontend e BFF.
  • Confirmar se alguns endpoints em src/app/api deveriam migrar para serviços dedicados.

Versionamento​

  • ADR inicial criado em 2026-03-20.
  • Revisar este ADR quando a estratégia de autenticação, hospedagem ou integração mudar.

Referencial teórico​

  • Architecture Decision Records (ADR).
  • C4 Model para complementar a leitura estrutural.