Formação Base

Contexto e Desafio de Engenharia

Sistemas de gestão de aprendizado (LMS) corporativos tradicionais frequentemente falham ao tentar conciliar escalabilidade, segurança e localização global em arquiteturas multi-tenant. O principal desafio técnico deste projeto consistiu em projetar um ecossistema B2B2C SaaS de alta performance capaz de atender de forma isolada a três atores simultaneamente: a holding administradora central, as empresas compradoras (clientes B2B) e os colaboradores finais (consumidores).

Adquirido por uma organização em Portugal, o software exigia o cumprimento rigoroso de requisitos enterprise de nível internacional: isolamento absoluto de dados (data segregation) via RLS, internacionalização nativa (i18n), controle de limites dinâmicos de licenças contratadas (user_limit) e uma esteira automatizada de Inteligência Artificial Generativa capaz de traduzir e localizar trilhas complexas de aprendizado (Cursos, Módulos, Aulas e Quizzes) sob demanda, mantendo a estrutura original do banco de dados relacional e eliminando o risco de quebra de layouts ou alucinações.

Engenharia da Arquitetura e Divisão de Camadas

1. Apresentação, UX Premium e Estado Reativo (Frontend)

• Core Stack & Runtime: Desenvolvido em React 18, TypeScript e Vite, utilizando o Bun como gerenciador de pacotes e runtime de alta velocidade para otimizar os ciclos de compilação e pipelines de deploy.
• Componentização & Interface Premium: Layout responsivo construído com Tailwind CSS e componentes de alta acessibilidade baseados em primitives da Radix UI (via Shadcn UI). O design system adota tokens customizados com paletas harmônicas em HSL, sombras suaves que reagem a estados de hover (--shadow-hover) e técnicas de carregamento assíncrono baseadas em Skeletons para aprimorar o Largest Contentful Paint (LCP).
• Sincronização do Estado do Servidor: O gerenciamento de cache de rede, sincronizações globais e mutações assíncronas são inteiramente governados pelo TanStack Query (React Query), minimizando o overhead de requisições desnecessárias às APIs de dados.

2. Persistência e Isolamento Multi-Tenant (Supabase & PostgreSQL)

• Modelagem Relacional de Internacionalização: Estrutura normalizada composta por entidades core (companies, profiles, courses, enrollments, modules, lessons, quizzes) interligadas de forma resiliente a tabelas satélites de tradução (content_translations, project_translations) por meio de restrições de integridade referencial com comportamento ON DELETE CASCADE.
• Zero-Trust Data Isolation: A segurança e a separação lógica das organizações não dependem de validações manuais no client-side; elas são forçadas nativamente ao nível do banco de dados por meio de políticas de Row-Level Security (RLS) no PostgreSQL. Consultas de mutação ou leitura são interceptadas na origem, cruzando o token JWT do usuário autenticado (auth.uid()) com funções autorizativas em PL/pgSQL (has_role, is_sindico_of_condo), impedindo vazamento de informações entre tenants.

3. Controle de Acesso Baseado em Papéis (RBAC de Grão Fino)

A navegação segura no cliente é coordenada de forma declarativa pelo componente guardião <ProtectedRoute /> integrado ao react-router-dom v6. O ecossistema avalia a sessão ativa e separa a experiência do usuário em 3 níveis restritos de permissão estruturados na tabela user_roles:

• Administrador Global (Admin): Gestão central do SaaS, criação do catálogo macro de cursos e provisionamento/licenciamento de novas organizações B2B.
• Administrador Corporativo (Company): Painel analítico exclusivo da empresa compradora para gerenciar colaboradores vinculados unicamente à sua tenant e acompanhar o progresso em tempo real da sua força de trabalho.
• Colaborador / Aluno (Employee): Área imersiva de consumo de conteúdo, equipada com reprodutor de vídeo e engine de execução de avaliações (Quizzes) validadas dinamicamente com base em notas de corte (passing_score).

🧠 4. Engine de Tradução Automática por IA (AI-Driven Compute)

Um dos maiores diferenciais de engenharia do sistema é o seu ecossistema distribuído de localização de conteúdo. Ele permite estender trilhas de aprendizado completas para equipes globais em segundos, operando com total controle de custos, tratamento de estados assíncronos e processamento estruturado de linguagem natural.

Arquitetura de Integração e Fluxo de Execução:

1. Chamada Assíncrona via Edge Serverless Compute: O administrador dispara a solicitação de tradução na plataforma web, o que aciona o hook triggerTranslation. A requisição autenticada com o token do usuário é recebida e processada por uma Supabase Edge Function escrita em TypeScript e executada em ambiente isolado Deno.
2. Prompt Engineering & Modo JSON Estruturado: A Edge Function interage com a API do OpenRouter utilizando o modelo Google Gemini 2.5 Flash Lite (altamente otimizado para processamento contextual e com excelente custo-benefício de tokens). O modelo é forçado a operar em JSON Mode através do parâmetro response_format, recebendo o payload original e aplicando regras estritas de engenharia de prompt:
   • Preservação de Chaves: A LLM traduz apenas os valores textuais associados às strings de conteúdo, mantendo as chaves do JSON estruturado totalmente intocadas.
   • Integridade de Tags HTML: Todas as tags de formatação rica contidas no texto original (ex: <p>, <strong>, <a href="...">) precisam ser mantidas exatamente na mesma posição dentro do texto traduzido.
   • Consistência de Arrays: A ordem, o índice e a quantidade de elementos de arrays estruturados (como as alternativas de múltipla escolha de um Quiz) são preservados de forma imutável, evitando a quebra da lógica de correção automática no backend.
3. Validação Dinâmica de Integridade no Backend: Antes de persistir os dados no PostgreSQL, a Edge Function realiza um parse rígido e executa rotinas de validação recursiva no retorno da IA. Ela valida se todas as chaves obrigatórias foram preenchidas e se o comprimento das opções do quiz bate com o registro original. Caso ocorra qualquer inconsistência de estrutura, a transação sofre rollback automático de forma segura.
4. Telemetria de Custos & Cache de Latência Zero: As traduções validadas são salvas na tabela content_translations. Para auditoria de custos e observabilidade da infraestrutura, o sistema armazena o tempo de execução em milissegundos (translation_time_ms) e os tokens de entrada e saída consumidos (tokens_input, tokens_output).
5. Renderização Otimizada no Front-end: O consumo do lado do aluno é gerenciado pelo hook customizado useTranslation e integrado ao cache inteligente do TanStack Query. Quando o usuário altera o idioma do sistema (i18n), o utilitário applyTranslation mescla instantaneamente a tradução pré-calculada do banco diretamente na UI. Isso elimina chamadas redundantes à API de Inteligência Artificial, reduzindo o custo operacional e derrubando a latência de renderização para 0ms nas execuções subsequentes.

Resultados e Impacto de Engenharia

• Validação Comercial e Escala Internacional: Produto altamente escalável comercializado e implantado com sucesso no mercado corporativo europeu (Portugal), comprovando a robustez da arquitetura de software fim a fim.
• Isolamento e Segurança de Nível Enterprise: Vazamento zero de registros corporativos ou dados de progresso entre organizações concorrentes devido à centralização de regras de segurança via PostgreSQL RLS.
• Eficiência de Custos Orientada a IA: A combinação do modelo econômico Gemini 2.5 Flash Lite ao modo JSON estrito com validações em Deno e cache reativo no TanStack Query resultou em uma arquitetura de inteligência artificial extremamente barata, resiliente e blindada contra falhas ou alucinações de layout.