Pular para o conteúdo principal

C4 - Contexto e Componentes

Escopo​

Sistema: dhedalos-app-backend-wordpress

Complemento visual:

  • Mindmap Mermaid: docs/architecture/mindmap.md

Baseado em:

  • we-dhedalos/functions.php
  • we-dhedalos/functions/rest/**
  • we-dhedalos/functions/post_types/**
  • docker-compose.yml, Dockerfile, docker/nginx.conf
  • helm/**, kubernetes/**, .github/workflows/ci-cd-pipeline.yml

C4 L1 - Contexto​

Atores​

  • Participante (subscriber)
  • Facilitador (facilitator)
  • Supervisor (supervisor)
  • Administrador (administrator)
  • Servicos internos consumidores de API com token (Authorization: Svc <token>)

Sistema em foco​

  • Backend WordPress com logica no tema we-dhedalos.
  • Exposicao HTTP via Nginx + PHP-FPM.
  • Persistencia em MariaDB + cache Redis.

Aplicacoes externas​

  • SimplyBook (agenda e bookings)
  • 8x8/Jitsi (geracao de token/sala)
  • Novu (notificacoes)
  • API de agenda de colaboradores (agenda em ACF options)
  • API de submissoes (API_DELIVERABLE_SUBSCRIPTIONS_URL)
  • ViaCEP (enriquecimento de endereco em importadores)

Dependencias externas de runtime​

  • Docker / Docker Compose
  • Kubernetes / Helm
  • Registro Docker (pipeline CI/CD)

Prefixo de API REST​

O projeto altera o prefixo REST padrao do WordPress:

  • padrao: /wp-json
  • projeto: /api

Implementacao:

  • we-dhedalos/functions/wp/rest_path.php

Exemplo final:

  • /api/dhedalos/v1/search

C4 L3 - Componentes internos​

1) Componente API REST de dominio​

Local: we-dhedalos/functions/rest/**

Responsabilidades:

  • registrar endpoints por modulo (courses, cycles, classes, registration, enroll, live, export, logs, tests),
  • validar autorizacao por token/sessao/role,
  • orquestrar regras de negocio e acesso a dados,
  • acionar integracoes externas.

2) Componente de dominio em WordPress (CPT/Taxonomia/ACF)​

Locais:

  • we-dhedalos/functions/post_types/**
  • we-dhedalos/functions/taxonomies/**
  • we-dhedalos/functions/acfs/**

Responsabilidades:

  • modelar curso, ciclo, turma, matricula e presenca,
  • modelar logs de auditoria e operacao,
  • manter configuracoes funcionais em options (ACF).

3) Componente de autenticacao/autorizacao​

Locais:

  • we-dhedalos/functions/rest/auth_callback.php
  • we-dhedalos/functions/utils/permission.php

Responsabilidades:

  • validar Authorization: Svc <token> com API_SERVICE_TOKEN,
  • validar sessao WordPress,
  • aplicar gates por role (facilitator, supervisor, administrator).

4) Componente de integracoes externas​

Locais:

  • we-dhedalos/functions/3rd/simplybook.php
  • we-dhedalos/functions/3rd/8x8.php
  • we-dhedalos/functions/wp/user.php
  • we-dhedalos/functions/utils/send_*_novu.php
  • we-dhedalos/functions.php (submissions cleanup)

Responsabilidades:

  • agenda/booking,
  • salas/token de video,
  • notificacoes de negocio,
  • sincronizacao de facilitador com API de agenda,
  • limpeza remota de artefatos de submissao.

5) Componente de jobs e automacoes (WP-Cron)​

Locais:

  • we-dhedalos/functions.php
  • we-dhedalos/functions/utils/*_cron.php
  • we-dhedalos/functions/post_types/* (limpeza de logs)

Responsabilidades:

  • notificacao de inicio e ultimo dia de ciclo,
  • cancelamento automatico,
  • identificacao de usuarios inativos,
  • limpeza periodica de logs.

6) Componente de cache​

Locais:

  • we-dhedalos/functions/utils/cache.php
  • we-dhedalos/functions/utils/invalidate_*_cache.php
  • we-dhedalos/functions/wp/rest-cache.php
  • wp/object-cache.php (drop-in)

Responsabilidades:

  • cache de consultas de dominio,
  • cache/transient para integracoes e endpoints live,
  • invalidacao em alteracao de curso/ciclo,
  • flush global em pre_post_update.

7) Componente de runtime e deploy​

Locais:

  • docker-compose.yml, Dockerfile, docker/nginx.conf, docker/php/custom-php.ini
  • helm/**, kubernetes/**, .github/workflows/ci-cd-pipeline.yml

Responsabilidades:

  • empacotar runtime Nginx + PHP-FPM,
  • prover banco/cache,
  • executar pipeline de build e deploy por branch/ambiente.

Fluxos de referencia​

Fluxo 1 - Inscricao​

  1. Cliente chama /api/dhedalos/v1/enroll/{slug} com token de servico.
  2. API valida disponibilidade de ciclo/turma.
  3. API cria students com vinculo user + class.
  4. API atualiza metadados de matricula e contador de turma.
  5. API aciona notificacoes (Novu) quando habilitado.

Fluxo 2 - Mentoria individual​

  1. Usuario logado consulta disponibilidade (/individual/disponibility ou /individual/available-slots).
  2. API resolve provider/cliente no SimplyBook.
  3. API cria booking em /individual/booking.
  4. Usuario consulta agendamentos em /individual/bookings.

Fluxo 3 - Sala de aula​

  1. Usuario logado chama /class_room*.
  2. API valida participacao na turma (ou permissao admin).
  3. Componente 8x8 gera token JWT e payload de acesso.
  4. API retorna token e metadados da sala.

Riscos tecnicos observaveis​

  • Forte acoplamento da logica de negocio ao tema.
  • Alta variacao de contratos de resposta entre endpoints.
  • Regras de autorizacao distribuidas entre permission_callback e callback de negocio.
  • Presenca de callbacks permissivos (__return_true) em rotas sensiveis de dominio.

Pendencias​

  • Nao existe documento formal de fronteiras para eventual migracao de dominio para plugin dedicado.
  • Nao existe threat model versionado no repositorio.
  • Nao existe catalogo versionado de contratos/SLA das integracoes externas.