Arquitetura C4 Component

Introdução ao documento

Este documento descreve a visão de componentes do repositório em um nível C4-like, focando no que sustenta os fluxos principais do sistema e no que tende a quebrar a aplicação quando falha. O escopo é o frontend Next.js com App Router e a camada BFF embutida em src/app/api.

Evidências:

• src/app/layout.tsx:60-93
• src/app/(protected-routes)/layout.tsx:21-74
• src/app/services/api.ts:12-311
• src/app/api/classes/route.ts:10-87
• src/app/api/submissions/route.ts:4-91

Versionamento

Baseline derivado do estado atual do repositório em 2026-03-20. Atualizar este documento quando houver mudança estrutural em:

• rotas do App Router;
• providers de contexto;
• handlers BFF em src/app/api;
• adaptadores HTTP em src/app/services;
• integrações externas consumidas pela UI.

Evidências:

• src/app/layout.tsx:41-93
• src/app/providers/UserProvider.tsx:79-141
• src/app/providers/ScheduleProvider.tsx:49-229
• src/app/services/api.ts:12-311

Referencial teórico

O documento usa:

• C4 Model como referência para decomposição por responsabilidade;
• leitura de código-fonte como fonte primária;
• Mermaid para manter o diagrama versionado em texto.

Evidências:

• docs/adr/0001-architecture-overview.md:1-57
• src/app/services/api.ts:12-311
• src/utils/authOptions.ts:7-117

Responsabilidade do serviço/app

O repositório implementa uma aplicação web que:

• autentica usuários com NextAuth e credenciais;
• carrega contexto de turma/tema no layout protegido;
• renderiza fluxos de agenda, salas, quiz, presença e atividades;
• expõe uma BFF local para encapsular autenticação, composição e proxy para serviços externos;
• inicializa telemetria client-side e integra componentes de atendimento/chat e videoconferência.

Evidências:

• src/utils/authOptions.ts:8-117
• src/app/(protected-routes)/layout.tsx:21-57
• src/app/api/auth/[...nextauth]/route.ts:1-6
• src/app/api/envs/route.ts:6-27
• src/app/start/DatadogStart.tsx:10-50

Dependências

Banco de dados

Não foi observada camada de banco embutida neste repositório. O código local acessa dados de negócio apenas via HTTP para serviços externos.

Evidências:

• src/app/services/api.ts:115-311
• src/utils/consts.ts:1-11

Cache

Há dois mecanismos observados:

• cache em memória no processo Node/browser via memory-cache para fetches reutilizáveis;
• estratégias HTTP/Next (revalidate, no-store, force-dynamic, Cache-Control) em páginas e handlers.

Evidências:

• src/hooks/useGetDataWithCache.ts:1-26
• src/app/(protected-routes)/layout.tsx:15-15
• src/app/api/envs/route.ts:4-4
• src/app/api/submissions/api-token/route.ts:2-16
• src/app/api/submissions/files/[...path]/route.ts:48-60

Fila / workers

Não foi localizada integração explícita com fila, broker ou worker assíncrono dedicado. Os efeitos de negócio observados são síncronos via fetch, SDKs client-side e temporizadores no navegador.

Evidências:

• src/app/services/api.ts:12-311
• src/components/MeetingRoom/MeetingRoom.component.tsx:206-220

Storage

O sistema depende de storage externo para arquivos de submissão e templates, acessado por URL e por proxies locais de download.

Evidências:

• src/app/api/submissions/files/[...path]/route.ts:17-60
• src/app/api/download/route.ts:19-51
• src/components/EnvioDeAtividades/EnvioDeAtividades.component.tsx:285-285
• src/components/ActivityManagement/components/ActivitiesSlider/ActivitiesSlider.component.tsx:448-452

Serviços externos

Dependência	Papel arquitetural	Evidência
Backend WordPress / Dhedalos API (API_URL)	autenticação, turmas, tema, usuário, salas, presença, ciclos, logs	src/utils/authOptions.ts:59-68, src/app/services/external/ClassService.ts:21-325, src/app/services/external/LogsService.ts:3-15
Schedule Manager (SCHEDULE_URL)	agenda, slots, agendamentos, bloqueios	src/utils/consts.ts:2-5, src/app/services/external/ScheduleService.ts:15-116
Serviço de submissões (SUBMISSIONS_URL)	submissões, templates, token temporário, ZIPs	src/utils/consts.ts:10-11, src/app/api/submissions/route.ts:4-91, src/app/api/activity-template/route.ts:3-201
Object storage (SUBMISSIONS_STORAGE_URL)	servir e baixar arquivos binários	src/app/api/submissions/files/[...path]/route.ts:17-60, src/app/api/download/route.ts:19-51
Quiz API (QUIZ_API_URL)	questionários e respostas	src/app/api/envs/route.ts:23-25, src/services/quizApi.ts:19-242
Jitsi	videoconferência em sala e reunião	src/app/api/jitsi/config/route.ts:3-18, src/components/MeetingRoom/MeetingRoom.component.tsx:131-183
Blip Chat	atendimento ao usuário	src/app/api/blip/config/route.ts:3-9, src/components/AttendanceButton/AttendanceButton.component.tsx:56-90
Datadog RUM/Logs	telemetria client-side	src/app/start/DatadogStart.tsx:14-47, src/app/api/envs/route.ts:7-25
Google Analytics	analytics client-side	src/app/layout.tsx:6-7, src/app/layout.tsx:90-90

Componentes internos agrupados por camada

1. Borda web e composição de página

Componente	Responsabilidade	Evidência
RootLayout	inicializa providers globais, metadados, Datadog, GA e globalThis	src/app/layout.tsx:41-93
PrivateLayout	valida sessão, busca tema/turmas e decide bootstrap do shell protegido	src/app/(protected-routes)/layout.tsx:21-74
Rotas protegidas em src/app/(protected-routes)	expõem os módulos de negócio: agenda, consultoria, sala, quiz, presença, gestão e atividades estratégicas	src/app/(protected-routes)/agenda/page.tsx:1-33, src/app/(protected-routes)/quiz/page.tsx:21-220, src/app/(protected-routes)/sala-de-reuniao/[slug]/page.tsx:1-78
Rotas públicas	login e entrypoint por slug/curso	src/app/page.tsx:8-28, src/app/(public-routes)/[slug]/page.tsx:1-45

2. Estado e orquestração de cliente

Componente	Responsabilidade	Evidência
SessionProvider	disponibiliza sessão NextAuth no cliente	src/app/providers/SessionProvider.tsx:1-17
UserProvider	mantém turma ativa, classes remapeadas, tema, agenda do usuário e erros	src/app/providers/UserProvider.tsx:18-141
ScheduleProvider	normaliza agenda semanal e agrupa mentoria em grupo para a UI	src/app/providers/ScheduleProvider.tsx:10-229
SubmissionsProvider	mantém o estado incremental de submissões no cliente	src/app/providers/SubmissionsProvider.tsx:11-70
Hooks utilitários	encapsulam cache, Jitsi config, submissões, templates e flags de execução única	src/hooks/useGetDataWithCache.ts:1-26, src/hooks/useJitsiConfig.ts:1-29, src/hooks/useSubmissions.ts:34-175, src/hooks/useActivityTemplates.ts:25-134, src/hooks/useRunOnce.ts:1-53

3. Componentes de domínio

Grupo	Responsabilidade	Evidência
Login, ClientLayout, Sidebar	shell de navegação, seleção de turma e entrada do usuário	src/components/Login/Login.component.tsx:77-122, src/components/ClientLayout/ClientLayout.component.tsx:1-106, src/components/Sidebar/Sidebar.component.tsx:1-170
Consultorias, AppointmentModal, Schedule	escolha de slots, confirmação de mentoria e visualização de agenda	src/components/Consultorias/Consultorias.component.tsx:136-259, src/components/AppointmentModal/AppointmentModal.component.tsx:100-136, src/components/Schedule/Schedule.component.tsx:1-280
EnvioDeAtividades, ActivityManagement, ActivityEvaluation	upload, listagem, avaliação e templates de atividades estratégicas	src/components/EnvioDeAtividades/components/Upload.component.tsx:136-202, src/components/ActivityManagement/components/ActivitiesSlider/ActivitiesSlider.component.tsx:161-182, src/components/ActivityEvaluation/ ActivityEvaluation.component.tsx:177-285
MeetingRoom, MeetRoom, MeetingRecoverCard	videoconferência, auto-presença e recuperação	src/components/MeetingRoom/MeetingRoom.component.tsx:131-229, src/components/MeetRoom/MeetRoom.component.tsx:1-106, src/components/MeetingRecoverCard/MeetingRecoverCard.tsx:56-207
QuizBackend e página de quiz	descoberta de quiz, execução e submissão de respostas	src/app/(protected-routes)/quiz/page.tsx:84-209, src/components/Quiz/QuizBackend.component.tsx:1-252
AtendimentoButton	bootstrap do chat Blip	src/components/AttendanceButton/AttendanceButton.component.tsx:53-109

4. BFF local

Componente	Responsabilidade	Evidência
Handlers em src/app/api	adaptam autenticação, filtram parâmetros, proxiam payloads e normalizam respostas	src/app/api/classes/route.ts:10-87, src/app/api/schedule/slot/route.ts:7-64, src/app/api/submissions/route.ts:4-91, src/app/api/activity-template/route.ts:3-201
auth/[...nextauth]	expõe o ponto de entrada HTTP do NextAuth	src/app/api/auth/[...nextauth]/route.ts:1-6
health/config endpoints	expõem readiness, ambiente e chaves públicas necessárias ao cliente	src/app/api/health/route.ts:3-31, src/app/api/envs/route.ts:6-27, src/app/api/blip/config/route.ts:3-9, src/app/api/jitsi/config/route.ts:3-18

5. Adaptadores de integração

Componente	Responsabilidade	Evidência
proxyRequest	cliente do frontend para o próprio /api/*, com retry para GET e suporte E2E	src/app/services/api.ts:12-113
wpRequest	adaptador autenticado para backend WordPress/Dhedalos	src/app/services/api.ts:115-185
scheduleRequest	adaptador para Schedule Manager	src/app/services/api.ts:187-244
submissionRequest	adaptador para serviço de submissões	src/app/services/api.ts:246-311
serviços external/*	encapsulam contratos externos por domínio	src/app/services/external/ClassService.ts:21-325, src/app/services/external/ScheduleService.ts:15-116
serviços bff/*	encapsulam consumo do BFF local a partir da UI	src/app/services/bff/ClassService.ts:15-130, src/app/services/bff/ScheduleService.ts:14-80, src/app/services/bff/SubmissionService.ts:17-197

Fluxos críticos

1. Login e bootstrap da área protegida

Fluxo:

1. Login chama signIn('credentials') com CPF/senha e persiste course_id em localStorage.
2. NextAuth autentica contra ${baseUrl}/api/jwt-auth/v1/token.
3. PrivateLayout exige sessão, carrega ThemeSettings e ClassesByUser.
4. ClientLayout e UserProvider inicializam o shell e o contexto de turma.

Por que é crítico:

• falha aqui impede acesso a todo o sistema protegido;
• depende simultaneamente de NextAuth, backend WordPress e bootstrap de tema/turmas.

Evidências:

• src/components/Login/Login.component.tsx:100-122
• src/utils/authOptions.ts:59-88
• src/app/(protected-routes)/layout.tsx:21-57
• src/app/providers/UserProvider.tsx:79-141

2. Consulta e criação de agenda/mentoria

Fluxo:

1. Consultorias usa classesData para datas e tipo de reunião.
2. O cliente consulta slots via serviços BFF de agenda.
3. AppointmentModal confirma a mentoria e chama createAppointment.
4. O BFF resolve facilitador, injeta client_id/employee_id e envia ao Schedule Manager.
5. Em modo participante, o cliente ainda registra participant-mode-log.

Por que é crítico:

• quebra afeta agenda individual e de grupo;
• mistura dependência do WordPress para facilitador com Schedule Manager para efetivar o agendamento.

Evidências:

• src/components/Consultorias/Consultorias.component.tsx:136-243
• src/components/AppointmentModal/AppointmentModal.component.tsx:100-136
• src/app/api/schedule/appointment/create/route.ts:24-66
• src/app/services/external/ScheduleService.ts:68-70

3. Envio e gestão de atividades estratégicas

Fluxo:

1. Upload monta FormData com participante, turma, ciclo, facilitador e arquivos.
2. SubmissionService obtém token temporário e posta para /api/submissions.
3. O handler BFF proxia o multipart/form-data para o serviço de submissões.
4. ActivityEvaluation atualiza ou remove a submissão; ActivityManagement administra templates.
5. Downloads usam submissions/download, download e submissions/files.

Por que é crítico:

• é o fluxo mais acoplado a arquivos binários, token temporário, serviço de submissões e storage externo;
• falhas aqui afetam entrega, avaliação, reenvio, templates e download.

Evidências:

• src/components/EnvioDeAtividades/components/Upload.component.tsx:146-202
• src/app/services/bff/SubmissionService.ts:54-197
• src/app/api/submissions/route.ts:4-91
• src/app/api/submissions/[id]/route.ts:4-84
• src/app/api/activity-template/route.ts:3-201
• src/app/api/download/route.ts:6-56

4. Sala de reunião, auto-presença e recuperação

Fluxo:

1. A UI busca credenciais de sala e configuração Jitsi.
2. MeetingRoom escolhe a URL do servidor e normaliza o nome da sala.
3. Para participantes em ClassRoom, um temporizador agenda a auto-presença.
4. No fluxo de recuperação, MeetingRecoverCard usa StatusService, reproduz vídeo e registra presença de recuperação no final.

Por que é crítico:

• combina vídeo, presença, recuperação e redirecionamento para atividade complementar;
• depende de sala Jitsi, backend WordPress, rota de status mockada/local e persistência em sessão/storage.

Evidências:

• src/components/MeetingRoom/MeetingRoom.component.tsx:131-229
• src/components/MeetRoom/MeetRoom.component.tsx:35-72
• src/components/MeetingRecoverCard/MeetingRecoverCard.tsx:56-207
• src/services/StatusService.ts:31-113
• src/app/api/presence/auto/route.ts:21-27
• src/app/api/presence/recovery/route.ts:21-29

5. Quiz carregado por slug

Fluxo:

1. A página de quiz resolve slug e userId a partir de searchParams, sessão e turma corrente.
2. quizApi.ts busca a base da Quiz API via /api/envs.
3. O cliente executa as chamadas de quiz diretamente contra a Quiz API, com auth_token opcional do localStorage.
4. QuizBackend conduz a experiência do questionário.

Por que é crítico:

• é o único fluxo principal que sai do BFF local e vai do browser direto para API externa;
• falha de /api/envs ou de QUIZ_API_URL quebra o módulo inteiro.

Evidências:

• src/app/(protected-routes)/quiz/page.tsx:21-209
• src/services/quizApi.ts:19-124
• src/app/api/envs/route.ts:23-25

Diagrama Mermaid

Evidências:

• src/app/layout.tsx:60-93
• src/app/(protected-routes)/layout.tsx:21-57
• src/app/services/api.ts:12-311
• src/services/quizApi.ts:19-124
• src/components/MeetingRoom/MeetingRoom.component.tsx:131-183
• src/components/AttendanceButton/AttendanceButton.component.tsx:56-90

Pendências

• Confirmar ownership e contratos versionados dos serviços externos WordPress, Schedule Manager e Submissions, porque este repositório só mostra os adaptadores HTTP locais.
• Não há evidência local de banco, fila ou broker dedicados; se existirem na infraestrutura dos serviços externos, precisam ser documentados nos respectivos repositórios.
• O fluxo de quiz sai direto do browser para a Quiz API; seria útil confirmar se isso é decisão arquitetural definitiva ou etapa transitória.
• A rota de status/recovery ainda mistura lógica local mockada com consumo indireto de submissões; o boundary desse componente merece ADR próprio se continuar evoluindo.