Pular para o conteúdo principal

C4 - Componentes (L3)

Introdução ao documento​

Este documento descreve a arquitetura de componentes do serviço activity-delivery-api no nível C4 L3.

Versionamento​

  • Versão do documento: 1.0.0
  • Última atualização: 2026-03-04
  • Responsável: Time Dhedalos

Referencial teórico​

Escopo​

  • Serviço/app: activity-delivery-api
  • Fontes: app/Http/Controllers/, app/Services/, app/Models/, app/Http/Middleware/, routes/api.php, routes/web.php, routes/backpack/custom.php

Responsabilidade​

API REST para gestão do ciclo de vida de atividades entregáveis (submissão, avaliação, reenvio) com painel administrativo integrado via Laravel Backpack.

Dependências​

  • Banco: MySQL 8.0 (dev) / PostgreSQL (produção) — Evidência: config/database.php:46,85, docker-compose.yml:25
  • Cache: Redis 7 / database — Evidência: config/cache.php, .env.example:44
  • Fila: Database driver — Evidência: config/queue.php, .env.example:37
  • Storage: AWS S3 / local — Evidência: config/filesystems.php
  • Externos: Novu API (notificações) — Evidência: app/Services/NotificationService.php:23

Componentes internos​

1. API Layer — Controllers REST​

  • SubmissionController — CRUD de submissões + geração de JWT + download ZIP + status summary
    • Evidência: app/Http/Controllers/Api/SubmissionController.php:87-755
  • ActivityTemplateFileController — CRUD de arquivos modelo de atividades
    • Evidência: app/Http/Controllers/Api/ActivityTemplateFileController.php:12

2. Admin Layer — Backpack CRUD Controllers​

  • DeliverableSubmissionCrudController — gerenciamento visual de submissões
    • Evidência: app/Http/Controllers/Admin/DeliverableSubmissionCrudController.php
  • UserCrudController — gerenciamento de usuários e roles
    • Evidência: app/Http/Controllers/Admin/UserCrudController.php
  • NovuKeyCrudController — gerenciamento de chaves Novu
    • Evidência: app/Http/Controllers/Admin/NovuKeyCrudController.php
  • ActivityTemplateFileCrudController — gerenciamento de arquivos modelo
    • Evidência: app/Http/Controllers/Admin/ActivityTemplateFileCrudController.php
  • RoleCrudController / PermissionCrudController — RBAC via Spatie
    • Evidência: app/Http/Controllers/Admin/RoleCrudController.php, app/Http/Controllers/Admin/PermissionCrudController.php

3. Middleware Layer — Autenticação e Autorização​

  • ApiKeyMiddleware (api.key) — valida API Key no header Authorization contra tabela api_keys
    • Evidência: app/Http/Middleware/ApiKeyMiddleware.php:15
  • JwtAuthenticate (jwt.auth) — valida JWT Bearer token (HS256) usando JWT_SECRET
    • Evidência: app/Http/Middleware/JwtAuthenticate.php:13
  • CheckIfAdmin — autoriza acesso ao painel Backpack
    • Evidência: app/Http/Middleware/CheckIfAdmin.php

4. Service Layer — Lógica de Negócio​

  • NotificationService — envia notificações via Novu HTTP API (4 workflows: send-submission, submission-received, submission-evaluated, request-resubmission)
    • Evidência: app/Services/NotificationService.php:23
  • SubmissionFileService — upload/substituição de arquivos de submissão no S3/local
    • Evidência: app/Services/SubmissionFileService.php:14
  • TemplateFileService — upload/substituição de arquivos modelo de atividade
    • Evidência: app/Services/TemplateFileService.php:23

5. Model Layer — Entidades de Domínio​

  • DeliverableSubmission — submissão de atividade (status: pending, submitted, submitted_external, evaluated)
    • Evidência: app/Models/DeliverableSubmission.php:15
  • SubmissionFile — arquivo anexo de uma submissão
    • Evidência: app/Models/SubmissionFile.php:15
  • ActivityTemplateFile — arquivo modelo de atividade
    • Evidência: app/Models/ActivityTemplateFile.php:18
  • ApiKey — chave de acesso à API
    • Evidência: app/Models/ApiKey.php:14
  • NovuKey — chave de workflow Novu
    • Evidência: app/Models/NovuKey.php:13
  • User, Role, Permission — autenticação e RBAC
    • Evidência: app/Models/User.php:19, app/Models/Role.php, app/Models/Permission.php

6. Auth Layer — Fortify Actions​

  • CreateNewUser, ResetUserPassword, UpdateUserPassword, UpdateUserProfileInformation
    • Evidência: app/Actions/Fortify/

7. Observability Layer​

  • Telescope — debug dashboard (local: tudo; produção: apenas erros)
    • Evidência: app/Providers/TelescopeServiceProvider.php
  • Pulse — monitoramento de performance
    • Evidência: config/pulse.php
  • Log Viewer — visualização de logs no admin
    • Evidência: routes/backpack/custom.php:28

Fluxos críticos​

1. Submissão de atividade (participante)​

App Mobile → [API Key] → POST /api/submissions/token → JWT
App Mobile → [JWT] → POST /api/submissions (files) → SubmissionController::store
  → SubmissionFileService::replaceFiles (upload S3)
  → NotificationService::sendNotification (send-submission → participante)
  → NotificationService::sendNotification (submission-received → facilitador)

2. Avaliação de submissão (facilitador)​

App Mobile → [API Key] → POST /api/submissions/{id} → SubmissionController::update
  → Atualiza status/score/comment
  → SubmissionFileService::replaceFiles (se novos arquivos)
  → NotificationService::sendNotification (submission-evaluated → participante)

3. Reenvio de submissão (facilitador solicita)​

App Mobile → [API Key] → DELETE /api/submissions/{id}?action=resend → SubmissionController::destroy
  → SoftDelete da submissão
  → Remove arquivos do S3
  → NotificationService::sendNotification (request-resubmission → participante)

Diagrama Mermaid​

Pendências​

  • ⚠️ PENDÊNCIA: Detalhar fluxo de autenticação Fortify (login admin) com diagrama de sequência.
  • ⚠️ PENDÊNCIA: Mapear integração com serviços Kubernetes (ingress, probes) a partir dos Helm charts.
  • ⚠️ PENDÊNCIA: Identificar se há comunicação direta com o dhedalos-app-backend-wordpress ou se a integração é via app mobile.