Kharis Sistema Educacional

Sobre

Plataforma SaaS multi-tenant que idealizei e construí: serve professores, alunos, pedagogos, diretores e responsáveis num único sistema, com 6 perfis distintos. Em produção. Diferenciais técnicos: arenas ao vivo (alunos competem em tempo real via WebSockets), homework adaptativo gerado por IA Claude que cruza tags dos erros dos últimos 60 dias (duas janelas de 30) e classifica cada tag em improving/worsening/stable antes de injetar no prompt, e tutor socrático que explica conceitos sem dar gabarito.

Stack

• NestJS·
• TypeORM·
• PostgreSQL·
• Next.js·
• React·
• TypeScript·
• WebSockets·
• Claude API (Anthropic)·
• Meta WhatsApp Cloud API·
• Evolution API·
• BullMQ·
• AWS S3·
• JWT·
• PWA

Decisões

• Multi-tenancy por instituição com papéis diferentes por usuário em escolas diferentes — um professor pode ser pai noutra escola, modelado M:N entre User e Institution.
• Arenas em tempo real via WebSocket gateway com timer server-side (não confia no cliente) e shuffle determinístico por (studentId, questionId) — anti-cola sem precisar de criptografia exótica.
• IA Claude não-decorativa: cross-join temporal de tags injetado no prompt com classificação improving/worsening/stable — não é IA pra parecer moderno, é IA usando dado real do aluno.
• Tutor socrático com constraint negativa explícita no prompt — adicionada DEPOIS de incidente real onde modelo vazou o gabarito sob pressão. Prompt engineering iterativo, não escrito uma vez.
• Idempotência em 3 camadas via unique constraints: XP nunca double-count por (student, referenceId, reason), badges nunca duplicam por (student, type), questões IA personalizadas nunca duplicam por (student, homework).
• WhatsApp em 2 provedores: Meta Cloud API oficial pra escolas com Business verificado, Evolution self-hosted como fallback pra quem não tem. Seleção por instituição, tokens armazenados criptografados AES-256-GCM com envelope versionado backward-compatible.
• JSON puro em vez de Tools API do Claude — testaram Tools, voltaram pra JSON por previsibilidade.
• PWA com offline em 5 telas críticas (deveres, calendário, boletim, central do aluno, arenas) — aluno em rede ruim continua estudando.

Desafios técnicos

• Tutor socrático que vazou gabarito em produção: corrigido com constraint negativa explícita no prompt. Lição: prompt design é iterativo, exige red-teaming.
• Sincronizar 30+ alunos numa arena ao vivo sem lag visível: auto-avanço com guard duplo contra race entre timer server-side e 'todos responderam'.
• Fila WhatsApp resiliente: BullMQ com retry e tracking de status (sent/delivered/read/failed) por mensagem.
• Onboarding de escola com importação de turmas/alunos: validação de CSV com erros agrupados em vez de batch-and-pray.
• Multi-tenancy com papéis complexos: 6 perfis × N instituições resolvido em runtime via guard NestJS, não regra-em-regra-em-regra.

Galeria