Plataforma HÉLICO
Esta página nivelar o leitor antes da narrativa sequencial (páginas 02-09). Ela responde a uma pergunta simples: o que é a Plataforma HÉLICO, como está construída e quem faz o quê?
Não é necessário ler os ADRs antes de começar aqui — esta página é o ponto de entrada.
O que é a Plataforma HÉLICO
A HÉLICO é uma plataforma de preparação para concursos jurídicos. Ela aplica a Metodologia HÉLICO — um sistema pedagógico próprio baseado em Ciclos de Desempenho e Aprendizagem (CDA) — para organizar o estudo de cada Aluno de forma personalizada, progressiva e mensurável.
Do ponto de vista técnico, a plataforma tem dois lados:
- Backend — Moodle LMS com o plugin
local_helico(PHP). Concentra todas as regras de negócio, persistência, processamento pedagógico e exposição de API. - Frontend — aplicação NextJS (chamada “Plataforma HÉLICO”). Consome o backend via API REST e apresenta o Roteiro de Estudos, Simulados, Desempenho, Caderno Online e demais visões ao Aluno.
Conteudistas Gestores Pedagógicos Alunos
│ │ │
▼ ▼ ▼
SharePoint ──► local_helico (Backend Moodle) ──► API REST ──► NextJS (Frontend)
│
├── Domínio content — conteúdo entra e evolui
├── Domínio product — oferta comercial vira Trilha Pedagógica
├── Domínio engine — compilação, acesso e execução
├── Domínio activity — cada atividade é executada
├── Domínio metrics — desempenho é consolidado
└── Domínio platform — gateway para o frontendO backend não conhece o frontend — expõe contratos de dados e o frontend os consome. Toda a lógica pedagógica vive no backend.
Stack tecnológico
| Componente | Tecnologia | Papel |
|---|---|---|
| Backend LMS | Moodle (PHP 8.x) | Plataforma base, autenticação, inscrições |
| Plugin pedagógico | local_helico (PHP) |
Domínios, regras, persistência, API REST |
| Framework do plugin | local_middag (PHP) |
Command/Handlers, EventDispatcher, Job/Adhoc, EAV |
| Persistência | MySQL/MariaDB | 4 tabelas EAV + 4 tabelas dedicadas |
| Frontend | NextJS (TypeScript) | Interface do Aluno — consome API REST |
| Documentação de conteúdo | SharePoint / OneDrive | Armazenamento de documentos Word dos Conteudistas |
| Especificação de domínio | LinkML + JSON Schema | Pipeline de tipos PHP, contratos de dados |
O local_middag é o framework interno que fornece os patterns de orquestração — o HÉLICO usa seus patterns, não o estende arbitrariamente.
Os 6 domínios
O local_helico é organizado em 6 domínios (bounded contexts). Cada domínio tem responsabilidade clara e não invade o outro — a comunicação entre eles ocorre via eventos (EventDispatcher) ou via chamadas de serviço bem definidas.
| # | Domínio | Pergunta que responde | Página |
|---|---|---|---|
| 1 | content | Como o conteúdo pedagógico entra, é estruturado e evolui? | 02 |
| 2 | product | Como a oferta comercial vira uma Trilha Pedagógica configurável? | 03 |
| 3 | engine | Como a Trilha vira Plano, como o Aluno acessa e como executa? | 04 / 05 / 06 |
| 4 | activity | Como cada tipo de atividade é executado e registrado? | 07 |
| 5 | metrics | Como o desempenho do Aluno é consolidado e seu nível classificado? | 08 |
| 6 | platform | Como o frontend NextJS consome tudo via gateway? | 09 |
Subdomains
Três domínios têm subdomains internos:
| Domínio | Subdomain | Escopo resumido |
|---|---|---|
| content | content.management |
Sync SharePoint, pré-processamento de documentos Word |
| content | content.base |
Disciplina, Unidade, Tópico, Questão — a Base de Conteúdo |
| content | content.change |
Detecção de impacto e resolução de conflitos de conteúdo |
| product | product.commercial |
SKU, Modalidade, Oferta, Campanha, Pedido, Política de acesso |
| product | product.learning_path |
As 9 etapas de configuração da Trilha Pedagógica |
| engine | engine.algorithm |
Algoritmo de compilação — Trilha → Plano de Estudo |
| engine | engine.plan |
Plano de Estudo, Plano do Aluno, Fluxos, Blocos, Etapas |
| engine | engine.access |
Matrícula, Vigência, Concessão de Acesso |
| engine | engine.onboarding |
Onboarding do Aluno, Questionário de Perfil, HabitTracker |
| engine | engine.session |
Sessão de Execução — agrupa registros de atividade em runtime |
Persistência
O local_helico usa dois padrões de persistência:
EAV (Entity-Attribute-Value) — para entidades de configuração, estrutura e execução estrutural. Usa 4 tabelas próprias (helico_items, helico_itemmeta, helico_item_revision, helico_item_revision_meta), independentes do middag.
Tabelas dedicadas — para dados transacionais de alto volume (respostas, resultados, métricas, caderno). 4 tabelas:
| Tabela | Domínio | Conteúdo |
|---|---|---|
helico_metrics |
metrics | Classificações + Relatórios (via campo type) |
helico_response |
activity | Respostas e submissões de atividades |
helico_result |
activity | Resultados computados (nota, elegibilidade) |
helico_notebook |
activity | Artefatos do Caderno Online (versionados) |
Total: 8 tabelas. Os domínios content, product e engine inteiros vivem no EAV.
Para critérios de decisão EAV vs tabela própria, ver ADR-10.
Ciclo de vida pedagógico
O percurso de um Aluno na HÉLICO passa por 4 fases distintas. Cada fase tem responsabilidades, entidades e componentes próprios.
Fase 1 — Configuração
Admin configura a Trilha Pedagógica (88+ parâmetros)
→ Entidade: trail (product)
Fase 2 — Compilação
CompilationEngine transforma a Trilha em Plano de Estudo (artefato estático e versionado)
→ Entidade: plan (product → engine)
Fase 3 — Instanciação
Inscrição do Aluno gera Matrícula + Vigência + Plano do Aluno (cópia executável do Plano de Estudo)
→ Entidades: enrolment, roadmap (engine)
Fase 4 — Execução
Motor Pedagógico executa o Plano do Aluno: progressão, atividades, classificação, métricas
→ Entidades: study_flow, study_block, stage, cda_cycle, response, result, classification (engine/activity/metrics)Uma mudança na Configuração (Fase 1) não afeta Planos de Estudo já compilados. Uma recompilação (Fase 2) não afeta Alunos já com Plano do Aluno ativo. Cada fase evolui independentemente.
Para detalhes, ver ADR-02.
Princípios arquiteturais
Quatro princípios estruturam o design do local_helico:
1. Separação de responsabilidades — regra pedagógica não depende de detalhes de persistência. Domínio (decisão pedagógica), Aplicação (Command/Handlers), Infraestrutura (adapters, $DB) e Entrada (controllers) têm motivos de mudança distintos. Ver ADR-01.
2. Ciclo de vida em 4 fases — configuração, compilação, instanciação e execução são fases independentes. Uma mudança em Fase N não propaga automaticamente para Fases N+1. Ver ADR-02.
3. Eventos para desacoplamento — domínios comunicam-se via eventos (EventDispatcher do middag). O emissor não conhece o receptor. Ver ADR-04.
4. Contratos de interface para tipos polimórficos — atividades, regras de scoring e outros tipos variáveis são resolvidos via interfaces, não via switch/if em cascata. Ver ADR-05.
Glossário mínimo
Termos que aparecem em todas as páginas desta especificação. Para o glossário completo, ver glossário publicado.
Base de Conteúdo — conjunto de Disciplinas, Unidades, Tópicos e Questões materializados a partir dos documentos Word. É o repositório de conteúdo pedagógico consumido por todos os outros domínios.
Ciclo CDA (Ciclo de Desempenho e Aprendizagem) — unidade de execução central da Metodologia HÉLICO. Cada Ciclo CDA contém Segmentos (DI — Diagnóstico Inicial e SVD — Simulado de Validação do Desempenho) intercalados com Revisão e estudo dirigido.
Disciplina — agrupamento de Unidades com identidade própria (IDNUMBER), originada de um documento Word do Conteudista.
Fluxo de Estudo — conjunto ordenado de Blocos de Estudo dentro do Plano do Aluno. Cada Fluxo corresponde a um período de estudo (ex: Fluxo Semanal, Módulo).
Matrícula — vínculo pedagógico entre o Aluno e uma Trilha Pedagógica. Criada a partir da inscrição no Curso-Produto do Moodle.
Plano de Estudo — artefato compilado e versionado, gerado pelo CompilationEngine a partir da Trilha Pedagógica. Imutável após gerado.
Plano do Aluno (Roteiro de Estudos) — cópia executável do Plano de Estudo, personalizada para o Aluno no momento da Instanciação. É o que o Aluno enxerga e executa.
Produto Comercial — item comercializável (SKU) associado a um Curso-Produto no Moodle e a exatamente uma Trilha Pedagógica.
Trilha Pedagógica — contrato pedagógico configurável que transforma a Base de Conteúdo em estudo organizado. Configurada em 9 etapas pelo Gestor Pedagógico.
Unidade — subdivisão de uma Disciplina. Unidades contêm Tópicos de Conteúdo e são a unidade de progressão pedagógica.
Vigência — período de acesso do Aluno ao Plano. Controla a disponibilidade de Fluxos ao longo do tempo.
Como ler esta especificação
A leitura é sequencial — cada página habilita a próxima:
| Passo | Página | O que habilita entender |
|---|---|---|
| — | Esta página | Stack, domínios, ciclo de vida, vocabulário |
| 1–3 | Content | Como o conteúdo existe no sistema |
| 4 | Product | Como o conteúdo vira Trilha configurável |
| 5 | Engine — Compilação | Como a Trilha vira Plano de Estudo |
| 6 | Engine — Acesso | Como o Aluno acessa e recebe seu Plano |
| 7 | Engine — Execução | Como o Aluno executa o Plano em runtime |
| 8 | Activity | Como cada atividade individual funciona |
| 9 | Metrics | Como o desempenho é computado |
| 10 | Platform | Como o frontend recebe tudo via API |
Decisões arquiteturais que sustentam esta especificação estão em adrs/. Specs de implementação (algoritmos, pseudocódigo, critérios de aceitação) estão nos REFs vinculados a cada ADR.
→ Content — como o conteúdo entra no sistema