Plataforma OLP — Documentação Técnica
Sistema de gestão de olimpíadas científicas para escolas brasileiras.
Produção: https://olp.digital/
Preview: https://id-preview--b4188062-97f3-4ab8-aba4-214ee32684a0.lovable.app
Supabase: https://supabase.com/dashboard/project/mjvuzsizjlcalyfmbquy
Stack Tecnológica
| Camada | Tecnologia |
|---|---|
| Frontend | React 18 + TypeScript + Vite + TailwindCSS + shadcn/ui |
| Backend | Supabase Edge Functions (Deno) |
| Banco de Dados | PostgreSQL (Supabase) |
| Autenticação | JWT customizado (HS256) via cookies HttpOnly |
| Mensagens | WhatsApp (Wasender) |
| Gateway | Cloudflare Worker (produção) |
Ambientes e Infraestrutura
| Ambiente | URL | Infra | Função |
|---|---|---|---|
| Produção | olp.digital | Lovable Hosting + CF Worker gateway.olp.digital | App principal |
| Staging | staging.olp.digital | CF Pages olp-staging + CF Worker gateway-staging.olp.digital | Validação pré-deploy, CI/CD |
| Docs | docs.olp.digital | CF Pages olp-docs (Direct Upload) + CF Worker olp-docs-auth | Documentação técnica (admin only) |
text
┌─────────────────────────────────────────────────────────────────────┐
│ olp.digital (DNS Cloudflare) │
├───────────────────┬───────────────────┬─────────────────────────────┤
│ │ │ │
│ olp.digital │ staging.olp.digital│ docs.olp.digital │
│ (Lovable Host) │ (CF Pages) │ (CF Pages Direct Upload) │
│ │ │ │ │ │ │
│ ▼ │ ▼ │ ▼ │
│ gateway.olp │ gateway-staging │ olp-docs-auth │
│ .digital │ .olp.digital │ (CF Worker — auth only) │
│ (CF Worker) │ (CF Worker) │ │
│ │ │ │ │ │
│ ▼ │ ▼ │ │
│ Supabase PROD │ Supabase STAGING │ │
│ mjvuzsizjlca... │ nrgcajnhpjmw... │ │
└───────────────────┴───────────────────┴─────────────────────────────┘Índice de Documentação
🏗️ Arquitetura
| Documento | Descrição |
|---|---|
| OVERVIEW.md | Visão geral do sistema, papéis, fluxo de dados |
| DATABASE_SCHEMA.md | Schema completo — tabelas, relações, enums |
| EDGE_FUNCTIONS_CATALOG.md | Catálogo das 45+ Edge Functions |
| NAVIGATION_AND_ROUTING.md | Rotas, sidebar, navegação interna |
| CLOUDFLARE_WORKER_GATEWAY.md | Gateway de produção — cookies, geo, CORS |
| THIRD_PARTY_INTEGRATIONS.md | Adapter Pattern — integrações com terceiros (Wasender, Mercado Pago) |
| REALTIME.md | Supabase Realtime — token dual, presença, notificações |
| CLOUDFLARE_WORKER_CODE.md | Código-fonte anotado do Cloudflare Worker Gateway |
| CANARY_RELEASE_SYSTEM.md | Sistema de Canary Release, Feature Flags, versionamento |
| CNPJ_ALFANUMERICO.md | Adaptação para CNPJ alfanumérico (jul/2026) |
| MULTI_ESCOLA.md | Arquitetura multi-escola, isolamento por escola_id |
| MESSAGING_RATE_LIMITS.md | Rate limits específicos do sistema de mensagens |
| FUTURE_ARGON2ID_OFFLOAD_PLAN.md | Plano de offload do Argon2id para Worker dedicado |
| VITEPRESS_SETUP.md | Infraestrutura docs.olp.digital (VitePress + CF Pages + auth Worker) |
| ADR_SERVICE_ROLE_USAGE.md | ADR: service_role vs RLS + padrão de nomenclatura de clientes Supabase |
🔒 Segurança
| Documento | Descrição |
|---|---|
| AUTHENTICATION.md | Login unificado, OTP, JWT, cookies, CORS |
| RLS_POLICIES.md | Row Level Security por papel, SECURITY DEFINER |
| RATE_LIMITS.md | Rate limits, lockouts, anti-timing |
| AUDIT_LOG.md | Sistema de logs, formato, geolocalização |
| IP_RETENTION_LGPD.md | Retenção de IPs — LGPD + Marco Civil, anonimização 6 meses |
| SECURITY_AUDIT_2026-02-28.md | Relatório de auditoria formal |
| INACTIVITY_TIMEOUT.md | Timeout de inatividade 3h, throttle, UX de aviso |
| PASSWORD_HASHING_ARCHITECTURE.md | Arquitetura de hashing de senhas (Argon2id) |
| BENCHMARK_ARGON2.md | Benchmark de performance do Argon2id em Edge Functions |
| SILENT_DATA_LOSS_AUDIT.md | Auditoria de perda silenciosa de dados (RLS silent failures) |
| RLS_DESIGN_GUIDE.md | Guia de design de RLS seguras by design — templates, anti-padrões, validação |
💻 Desenvolvimento
| Documento | Descrição |
|---|---|
| GETTING_STARTED.md | Setup local, variáveis de ambiente |
| CODING_STANDARDS.md | Padrões de código, helpers, toast, Feature Directory Pattern |
| FRONTEND_UI_STANDARDS.md | Padrões de UI/UX (Select, Dialog, Tooltip, cabeçalhos, tokens) |
| NAMING_CONVENTIONS.md | Convenções de idioma e casing por camada (banco, backend, frontend) |
| PROBLEM_SOLVING.md | Metodologia de resolução de problemas — diagnóstico, causa raiz, anti-padrões |
| NEW_EDGE_FUNCTION.md | Template + checklist para nova Edge Function |
| NEW_HOOK.md | Template + checklist para novo hook React |
| REACT_QUERY_CACHE.md | Critérios de cache obrigatório, staleTime por categoria |
| DEV_WORKFLOW.md | Workflow de desenvolvimento (@workflow) — processo obrigatório de entrega |
| TESTING_MASTER.md | Documento mestre de testes (pirâmide, usuários, CI) |
| TESTING_PORTAL_RATE_LIMIT.md | Script de stress test do portal, relatórios MD |
| TEST_ERROR_PLAYBOOK.md | Acervo SSOT de erros E2E — catálogo, diagnóstico, padrões |
| IMPORT_SYSTEM_STANDARD.md | Padrão obrigatório para sistemas de importação (Excel/CSV) |
| MIGRATION_GUIDELINES.md | Diretrizes para migrations resilientes multi-ambiente (guards, idempotência) |
| MIGRATION_SAFETY_PROTOCOL.md | Protocolo obrigatório pré-entrega para mudanças críticas (banco, RLS, Edge Functions) |
| DOCUMENTATION_MAINTENANCE.md | Manutenção e publicação de documentação — checklist, sidebar, hierarquia |
| STATE_OF_THE_ART.md | Estado da arte — práticas e padrões adotados |
| ATOMIC_RENDERING.md | Padrão de renderização atômica para componentes |
| AUDIT_CHECKLIST.md | Checklist de auditoria para entregas (@audit) |
| TEST_MIGRATION_REPORT.md | Relatório de migração de testes |
🧪 Staging
| Documento | Descrição |
|---|---|
| STAGING_WHY.md | Motivações, decisões arquiteturais e trade-offs |
| STAGING_REFERENCE.md | Referência rápida do staging (URLs, secrets, dados) |
| STAGING_SETUP.md | Guia de setup do zero |
| seed_test_users.sql | Referência de usuários de teste |
⚙️ Operações
| Documento | Descrição |
|---|---|
| DEPLOYMENT.md | Deploy, domínio, Cloudflare Worker |
| DATABASE_CLEANUP.md | Limpeza e manutenção do banco |
| CRON_JOBS.md | Jobs agendados, monitoramento |
| ALERTAS_PUSH.md | Alertas push via ntfy.sh |
| NOTIFICATIONS_MAP.md | Mapa completo de notificações (in-app, push, WhatsApp) |
| INCIDENT_POLICY.md | Política de classificação e resposta a incidentes |
| TROUBLESHOOTING.md | Erros comuns, debug |
| DEPENDABOT_ANALYSIS.md | Análise de dependências e atualizações |
🎓 Mural Olímpico (legado — ver Features SSOT)
| Documento | Descrição |
|---|---|
| MURAL_OVERVIEW.md | Arquitetura do Mural Olímpico (legado — consolidado em docs/features/MURAL.md) |
| MURAL_LIBERACOES.md | Liberação de resultados (legado — consolidado em docs/features/MURAL.md) |
📋 Features (SSOT)
Documentação end-to-end por feature: frontend, schema, backend, padrões, testes.
Regra: Toda feature com ≥2 componentes + edge function DEVE ter doc em docs/features/.
| Documento | Descrição |
|---|---|
| TEMPLATE.md | Template padrão para novas features |
| CONTROLE.md | Seção Controle do coordenador (ações-chave, aplicações, kanban) |
| MURAL.md | Mural Olímpico (aluno, responsável, liberação, snapshots) |
| RESULTADOS.md | Gestão de Resultados (inserção, importação, premiação, mural sync) |
| ONBOARDING.md | Onboarding de escolas (9 etapas: cadastro → assinatura → acessos → alunos → turmas) |
Backlog: Gestão de Alunos, Agenda, Olimpíadas, Turmas — a documentar.
💰 Negócio
| Documento | Descrição |
|---|---|
| SUBSCRIPTION_BILLING.md | Planos, assinaturas, faturamento |
📋 Planos Futuros
| Documento | Descrição |
|---|---|
| SESSION_MANAGEMENT_ALERTS.md | Alertas de gestão de sessão |
| ANOMALY_DETECTION.md | Design: detecção de anomalias de acesso (futuro) |
| ROLE_BASED_RESTRUCTURE.md | Reestruturação por papel (aprovado, aguardando) |
| UPSTASH_REDIS_MIGRATION.md | Migração para Upstash Redis |
🔍 Auditorias
| Documento | Descrição |
|---|---|
| AUDIT_CALENDARIO_TRIAL_CADASTRO_2026-03-30.md | Auditoria Calendário Trial Mar/2026 |
| RESULTADOS_REFACTOR_AUDIT.md | Auditoria de refactor de resultados |
| SECURITY_AUDIT_PLAN.md | Plano de auditoria de segurança (fases concluídas) |
| PLANO_MIGRACAO_RLS_SUPABASE_SYSTEM.md | Plano mestre: migração de ~20 EFs de supabaseSystem para RLS |
| AUDIT_CODE_SPLITTING_2026-04-08.md | Auditoria de splits e reestruturação (dívida técnica) |
| AUDIT_CONTROLE_2026-04-12.md | Auditoria completa da seção Controle (anti-flash, performance, documentação) |
| AUDIT_FASES_POR_NIVEL_2026-04-12.md | Reestruturação fases por nível — migration, regressões, dívidas técnicas |
| AUDIT_RESPONSAVEL_LGPD_2026-04-13.md | Auditoria técnica do módulo Responsável — base LGPD |
Links Rápidos
- Custom Knowledge: Regras globais estão no prompt do sistema (knowledge document)
- Supabase Secrets: 14 secrets configurados (OLP_JWT_SECRET, WASENDER_*, MP_ACCESS_TOKEN, etc.)
- Storage Buckets: banners-login, curso-thumbnails, tutoriais-thumbnails, mural-imagens (todos públicos)