case técnico

Web App • Aula ao vivo / Tempo real

Lousa ao vivo

Plataforma para dar aula em cima de documentos HTML: o professor abre uma aula da biblioteca, todos desenham por cima ao mesmo tempo e a rolagem, as respostas abertas e os campos ficam iguais em todos os aparelhos.

Produto, servidor em tempo real e interface Código aberto Versão pública no GitHub
PHP 8.1 WebSocket JavaScript Canvas Docker Traefik
resumo executivo

Problema

Em aula online o material costuma ficar separado da lousa: o professor compartilha a tela, mas o aluno não interage com o conteúdo nem anota junto.

Solução

Um app em que o próprio documento da aula vira a lousa: todos desenham por cima, o professor guia a rolagem e respostas, campos e botões do documento ficam sincronizados.

Resultado

Aula ao vivo com até 30 pessoas por sala, entrada por link ou código, desenhos guardados por documento e uma biblioteca que sobrevive a atualizações do servidor.

Estado atual

Versão pública no GitHub, pronta para subir numa VPS com Docker e Traefik.

contexto

O documento é a lousa

A ideia é dar aula em cima de páginas HTML de um arquivo só, feitas à mão ou geradas com IA a partir de um prompt padrão. O servidor é escrito em PHP puro, sem bibliotecas: entrega o app, guarda a biblioteca e repassa em tempo real, por WebSocket, os traços, cliques e rolagens de quem está na mesma sala.

objetivos e restrições

Objetivos

  • Desenhar por cima de qualquer documento HTML, no computador ou no celular
  • Sincronizar rolagem, respostas abertas, campos e botões entre todos
  • Entrar numa aula por link ou código, sem criar conta
  • Manter uma biblioteca de aulas protegida por senha de professor
  • Gerar aulas novas com o Claude a partir de um modelo visual comum

Restrições

  • Servidor sem dependências: só PHP 8.1 na linha de comando
  • Documentos importados não podem ler o login nem mexer no app
  • Até 30 pessoas por sala e limite de mensagens por pessoa
  • Cada documento precisa ser um arquivo só, com CSS, JavaScript e imagens embutidos
arquitetura da solução

Front-end

App em HTML, CSS e JavaScript sem framework: um canvas por cima do documento para os traços (caneta, marca-texto e borracha), cursores das outras pessoas e uma ponte (ponte.js) que roda dentro de cada documento e conversa com o app por postMessage.

Back-end

server.php implementa HTTP e WebSocket do zero com stream_select: entrega os arquivos, a API da biblioteca e o login e repassa as mensagens ao vivo para quem está na mesma sala. Roda em Docker, atrás do Traefik, que cuida do HTTPS.

Banco de dados

Sem banco de dados: a biblioteca é um índice JSON, gravado de forma atômica, com os arquivos HTML num volume do Docker que não se perde com git pull, reinício ou nova versão do app.

segurança e prevenções

Documentos isolados

Cada aula é servida com Content-Security-Policy sandbox: o HTML importado roda isolado e não enxerga o login nem os dados do app.

Login de professor

Senha comparada com hash_equals, token assinado com HMAC que vale 30 dias e espera de 15 minutos depois de 10 tentativas erradas.

Tempo real com limites

O WebSocket só aceita conexões da própria origem e limita o tamanho das mensagens, a quantidade por pessoa e o número de pessoas por sala.

processo
01

Servidor em PHP puro

HTTP e WebSocket implementados sobre sockets, sem nenhuma biblioteca.

02

Desenho e sincronização

Canvas por cima do documento, traços enviados em lotes de 50 ms e ponte para sincronizar campos e respostas.

03

Biblioteca e professor

Importar, editar e apagar documentos com senha, guardando tudo num volume do Docker.

04

Aulas com IA

Prompt padrão e modelo de aula para criar documentos novos com o Claude.

05

Versão pública

Repositório aberto com Docker, Traefik e um guia de instalação numa VPS.

bastidores técnicos
app/server.php PHP linhas 572–608
    private function login(int $k, array $h, string $corpo): void
    {
        if ($this->senha === '') {
            $this->responderJson($k, 503, ['erro' => 'A importação está desligada. Defina SENHA_PROFESSOR no arquivo .env da VPS e reinicie.']);
            return;
        }
        $ip = $this->ipDe($k, $h);
        $agora = time();
        $this->falhas[$ip] = array_values(array_filter($this->falhas[$ip] ?? [], fn($t) => $agora - $t < JANELA_FALHAS));
        if (count($this->falhas[$ip]) >= MAX_FALHAS) {
            $this->responderJson($k, 429, ['erro' => 'Muitas tentativas erradas. Espere 15 minutos e tente de novo.']);
            return;
        }
        $d = json_decode($corpo, true);
        $senha = is_array($d) && is_string($d['senha'] ?? null) ? $d['senha'] : '';
        if (!hash_equals($this->senha, $senha)) {
            $this->falhas[$ip][] = $agora;
            $this->log("Senha de professor errada ($ip)");
            $this->responderJson($k, 401, ['erro' => 'Senha incorreta.']);
            return;
        }
        unset($this->falhas[$ip]);
        $exp = $agora + TOKEN_DIAS * 86400;
        $this->responderJson($k, 200, ['token' => $exp . '.' . hash_hmac('sha256', 'aula:' . $exp, $this->senha)]);
    }

    /** @param array<string, string> $h */
    private function autorizado(array $h): bool
    {
        if ($this->senha === '') {
            return false;
        }
        if (!preg_match('/^Bearer\s+(\d{9,12})\.([a-f0-9]{64})$/', $h['authorization'] ?? '', $m)) {
            return false;
        }
        return (int) $m[1] >= time() && hash_equals(hash_hmac('sha256', 'aula:' . $m[1], $this->senha), $m[2]);
    }
Senha comparada em tempo constante, bloqueio por IP depois de 10 erros e token assinado com HMAC no lugar de sessão.
app/server.php PHP linhas 295–326
    private function servirDoc(int $k, string $id, bool $soCab): void
    {
        $html = @file_get_contents($this->arquivoDoc($id));
        $codigo = 200;
        if ($html === false) {
            $codigo = 404;
            $html = '<!doctype html><html lang="pt-BR"><head><meta charset="utf-8"><title>Documento não encontrado</title></head>'
                . '<body style="font:16px/1.5 system-ui,sans-serif;padding:2rem;margin:0">'
                . '<h1 style="font-size:1.4rem">Esse documento não existe mais.</h1>'
                . '<p>Ele pode ter sido apagado da biblioteca. Escolha outro em Documentos.</p></body></html>';
        }
        $temCharset = (bool) preg_match('/<meta[^>]+charset/i', substr($html, 0, 4096));
        $this->responder($k, $codigo, 'text/html' . ($temCharset ? '' : '; charset=utf-8'), $this->injetarPonte($html), $soCab, [
            /* O documento roda isolado: não enxerga o login nem os dados do aplicativo. */
            'Content-Security-Policy' => 'sandbox allow-scripts allow-forms allow-popups allow-popups-to-escape-sandbox allow-modals',
        ]);
    }

    private function injetarPonte(string $html): string
    {
        $tag = '<script src="/ponte.js"></script>';
        foreach (['/<head\b[^>]*>/i', '/<html\b[^>]*>/i'] as $re) {
            if (preg_match($re, $html, $m, PREG_OFFSET_CAPTURE)) {
                $pos = $m[0][1] + strlen($m[0][0]);
                return substr($html, 0, $pos) . $tag . substr($html, $pos);
            }
        }
        if (preg_match('/^\s*<!doctype[^>]*>/i', $html, $m)) {
            return $m[0] . $tag . substr($html, strlen($m[0]));
        }
        return $tag . $html;
    }
Cada documento sai com a ponte injetada no <head> e uma CSP sandbox: roda scripts, mas não acessa o login nem o app.
app/server.php PHP linhas 779–803
    private function texto(int $k, string $txt): void
    {
        $d = json_decode($txt, false, 64);
        if (!($d instanceof stdClass) || !isset($d->tipo) || !is_string($d->tipo)) {
            return;
        }
        switch ($d->tipo) {
            case 'pulso':
                $this->enviarJson($k, ['tipo' => 'pulso']);
                return;
            case 'entrar':
                $this->entrar($k, $d);
                return;
            case 'msg':
                $sala = $this->c[$k]['sala'];
                if ($sala === null || !isset($d->m) || !($d->m instanceof stdClass) || !$this->dentroDoLimite($k)) {
                    return;
                }
                $json = json_encode(['tipo' => 'msg', 'm' => $d->m], JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES);
                if ($json !== false) {
                    $this->paraSala($sala, $json, $k);
                }
                return;
        }
    }
Mensagens do WebSocket: JSON validado, limite por pessoa e repasse para todos da sala, menos quem enviou.
app/public/app.js JavaScript linhas 313–359
  var enviados = 0, timerPts = null;
  cv.addEventListener('pointerdown', function(e){
    if (!ativo || !doc) return;
    if (e.pointerType === 'mouse' && e.button !== 0) return;
    e.preventDefault();
    pointers.set(e.pointerId, e.clientY);
    try { cv.setPointerCapture(e.pointerId); } catch(_){}
    if (pointers.size >= 2){
      if (atual) enviar({t:'del', d:atual.d, id:atual.id});
      atual = null; panning = true; lastPanY = media(); pararDeSeguir(); pedir();
      return;
    }
    if (panning) return;
    var w = ferramenta.tool === 'marca' ? 20 : ferramenta.tool === 'borracha' ? 28 : 3.5;
    var pt = paraPagina(e.clientX, e.clientY);
    atual = {id:meuId + '-' + (++seq), d:doc.id, tool:ferramenta.tool, color:ferramenta.color, w:w, pts:[pt], minY:pt[1], maxY:pt[1]};
    enviados = 1;
    enviar({t:'s0', d:doc.id, id:atual.id, tool:atual.tool, color:atual.color, w:w, p:[r1(pt[0]), r1(pt[1])]});
    pedir();
  });
  cv.addEventListener('pointermove', function(e){
    if (!ativo || !pointers.has(e.pointerId)) return;
    pointers.set(e.pointerId, e.clientY);
    if (panning){ var m = media(); window.scrollBy(0, lastPanY - m); lastPanY = m; return; }
    if (!atual) return;
    var evs = (e.getCoalescedEvents && e.getCoalescedEvents()) || [];
    if (!evs.length) evs = [e];
    evs.forEach(function(ev){
      var pt = paraPagina(ev.clientX, ev.clientY), last = atual.pts[atual.pts.length - 1];
      if (Math.abs(pt[0] - last[0]) + Math.abs(pt[1] - last[1]) < 1.5) return;
      atual.pts.push(pt);
      if (pt[1] < atual.minY) atual.minY = pt[1];
      if (pt[1] > atual.maxY) atual.maxY = pt[1];
    });
    agendarPontos();
    pedir();
  });
  function agendarPontos(){
    if (timerPts || !conectado) return;
    timerPts = setTimeout(function(){
      timerPts = null;
      if (atual && atual.pts.length > enviados){
        enviar({t:'sp', d:atual.d, id:atual.id, pts:atual.pts.slice(enviados).map(function(p){ return [r1(p[0]), r1(p[1])]; })});
        enviados = atual.pts.length;
      }
    }, 50);
  }
Cada traço nasce no pointerdown e os pontos seguem em lotes a cada 50 ms; com dois dedos, o gesto vira rolagem.
app/public/ponte.js JavaScript linhas 102–122
  /* ---------------- o que acontece aqui vai para os outros ---------------- */
  var aplicando = false;

  function aoCampo(e){
    if (aplicando) return;
    var el = e.target;
    if (!el || !/^(INPUT|SELECT|TEXTAREA)$/.test(el.tagName) || ignorarCampo(el)) return;
    var k = chave(el, 'campo');
    if (k) postar({tipo:'evento', e:{k:'campo', id:k, v:valor(el), ev:e.type === 'change' ? 'change' : 'input'}});
  }
  document.addEventListener('input', aoCampo, true);
  document.addEventListener('change', aoCampo, true);

  document.addEventListener('toggle', function(e){
    var d = e.target;
    if (!d || d.tagName !== 'DETAILS') return;
    agendarMedida();
    if (d._aulaRemoto){ d._aulaRemoto = false; return; }
    var k = chave(d, 'det');
    if (k) postar({tipo:'evento', e:{k:'det', id:k, o:d.open}});
  }, true);
Dentro do documento, campos, respostas abertas e botões viram eventos para os outros; senha e arquivo nunca são sincronizados.
impacto

Resultados

Um app de aula ao vivo completo, com um servidor de menos de mil linhas e sem dependências, que sobe com um comando do Docker.

Aprendizados

Implementar o WebSocket na mão mostrou o que as bibliotecas escondem: handshake, frames, máscara, ping e limites. Isolar o conteúdo com sandbox foi o que permitiu aceitar qualquer HTML na biblioteca.