ADR 0001: Architecture Overview

Introdução ao documento

• Status: Proposed
• Data desta baseline: 2026-03-20

Este ADR registra a decisão de documentar o sistema, neste momento, como uma aplicação Next.js que combina UI, sessão local e uma camada fina de API interna para integração com serviços externos.

Contexto

• O fluxo principal está centrado em detalhe de curso, inscrição, OTP, confirmação e redirecionamento para grupo.
• A autenticação usa NextAuth com credenciais cpf, coexistindo com uma integração opcional AMEI baseada em @dhedalos/auth.
• As integrações externas dominantes são WordPress, backend de WhatsApp, Datadog e Meta.
• O deploy é realizado via Docker, Helm, Kubernetes e GitHub Actions.

Evidências:

• app/[slug]/page.tsx#L16-L47
• app/[slug]/inscricao/page.tsx#L15-L24
• pages/api/auth/[...nextauth].ts#L25-L153
• src/features/components/CourseRegistration/CourseRegistration.component.tsx#L41-L75
• src/features/api/external/wp/index.ts#L1-L6
• src/features/api/external/whats/index.ts#L1-L2
• app/components/DatadogInit.tsx#L8-L29
• .github/workflows/ci-cd-pipeline.yaml#L13-L153

Decisão

Adotar, para a baseline de documentação, o seguinte enquadramento arquitetural:

• O repositório é o frontend principal do onboarding.
• app/ concentra as páginas e a experiência do usuário.
• pages/api/ e app/api/ formam a API interna/BFF local.
• A persistência e as regras de negócio mais profundas estão fora deste repositório, principalmente em serviços WordPress e WhatsApp.
• A documentação padrão passa a ser mantida em docs/, com contratos HTTP em OpenAPI e alterações arquiteturais relevantes registradas via ADR.

Evidências:

• app/[slug]/page.tsx#L16-L47
• pages/api/v1/participantes/[cpf].ts#L23-L48
• app/api/envs/route.ts#L4-L19
• src/features/api/external/wp/getCustomization/getCustomization.ts#L27-L34
• src/features/api/external/whats/otpSend/otpSend.ts#L20-L32

Consequências

• A documentação passa a explicitar que o modelo de dados e parte dos contratos pertencem a serviços externos.
• Mudanças em integrações, APIs internas e fluxo principal precisam atualizar docs/.
• O repositório ainda precisa mapear oficialmente os sistemas de origem das bibliotecas internas @dhedalos/*.

Pendências

• Validar este ADR com responsáveis de arquitetura e produto.
• Confirmar se a camada pages/api/ será mantida ou migrada gradualmente para app/api/.
• Registrar ADRs complementares para autenticação, observabilidade e operação, se necessário.

Versionamento

Este ADR deve ser mantido historicamente. Novas decisões não devem sobrescrever o contexto decisório; devem gerar novos ADRs ou atualizar o status deste documento quando necessário.

Evidência:

• .github/workflows/docs-governance.yml

Referencial teórico

• Architecture Decision Records.
• C4 Model.
• OpenAPI como contrato de integração.