🌐 LearnFlow AI — Web MCP Semantic Navigator & On-Device AI Platform

AI Navigation Layer & Autonomous Agentic Web: Transformando aplicações web em ecossistemas nativamente compreensíveis e navegáveis por agentes de IA através do Model Context Protocol (MCP), Chrome Built-in AI (Gemini Nano on-device) e Visão Multimodal com Gemini.

📌 Sobre o Projeto

O LearnFlow AI é uma plataforma educacional corporativa desenvolvida para demonstrar a fronteira da engenharia de software frontend: aplicações web preparadas para agentes de inteligência artificial autônomos.

Diferente de abordagens tradicionais frágeis (como automações visuais por screen scraping ou injeção de dezenas de milhares de tokens de HTML cru no contexto de um LLM), este projeto implementa um AI Navigation Layer:

1. Contrato Semântico no DOM: Componentes visuais expõem atributos declarativos padronizados (data-mcp-*).

2. Scanner Semântico Ultracompacto: Higieniza a árvore DOM, remove dados sensíveis (PII) e extrai um mapa semântico ultraleve (redução de 98% no consumo de tokens).

3. Servidor Web MCP Integrado: Expõe ferramentas RPC para o agente inspecionar o estado, pesquisar rotas e solicitar navegação.

4. IA Local no Browser (Chrome Built-in AI / Gemini Nano): Inferência 100% on-device via window.ai / window.LanguageModel, operando com zero latência de rede, privacidade absoluta e sem necessidade de API Keys.

5. Visão Computacional & OCR Multimodal (Gemini 2.5 Flash / Pro): Processamento e extração estruturada de dados a partir de fotos de documentos (CNH/RG/Diplomas) para preenchimento autônomo com guardrails.

6. Hierarquia de Páginas em Múltiplos Níveis (3 Níveis de Profundidade): O agente reconhece estruturas aninhadas ("página dentro de outra página", como Requerimentos → Cursos → [React | Arquitetura | Next.js] e Trilhas → Módulos → Laboratórios), navegando de forma contextualizada.

7. Governança & Segurança RBAC: A IA nunca atua como camada de autorização. O sistema emprega resolução segura de rotas em whitelist e gates determinísticos de permissão.

Related MCP server: ecobrowser MCP server

🏗️ Diagrama de Arquitetura

flowchart TD
    User([Usuário / Pergunta em Linguagem Natural]) -->|Input Texto / Imagem| ChatUI[AI Chat Widget & Document Ingestor]
    ChatUI --> AIService[AI Service Orchestrator]
    
    subgraph AI Providers Engine
        AIService --> Nano[Chrome Built-in AI / Gemini Nano (Local Browser)]
        AIService --> Gemini[Google Gemini Multimodal API (Vision & Pro)]
        AIService --> Mock[LearnFlow Deterministic Heuristic Provider]
    end

    subgraph Browser Semantic DOM
        HTML[React Components com data-mcp-*] --> Scanner[MCP DOM Semantic Scanner]
        Scanner --> SemanticMap[Lightweight Semantic Resources Map]
    end

    subgraph Model Context Protocol Engine
        SemanticMap --> MCPServer[In-App Web MCP Server]
        AIProviders -->|Tool Calls (JSON-RPC)| MCPClient[MCP Client]
        MCPClient -->|search_resources / navigate_to_resource| MCPServer
    end

    subgraph Security & Governance Layer
        MCPServer --> IntentValidator[Zod Schema Validator]
        IntentValidator --> AuthEngine[RBAC Policy Gate (Public / Student / Teacher / Admin)]
        AuthEngine -->|Autorizado| SafeRegistry[Safe Route Registry (Whitelist)]
        AuthEngine -->|Bloqueado| DenyGuardrail[ai.navigation.denied Event]
        SafeRegistry --> ClientRouter[Next.js Client Router (Turbopack)]
        SafeRegistry --> VisualPulse[DOM Visual Pulse Highlighter]
    end

    ClientRouter --> TelemetryBus[Observability & Event Bus]
    DenyGuardrail --> TelemetryBus

✨ Principais Funcionalidades

1. 🤖 Gemini Nano On-Device (Chrome Built-in AI)

• Executa nativamente no browser do usuário através da nova Prompt API do Chrome (window.ai / window.LanguageModel).

• Suporte completo aos ciclos de vida do modelo: available, downloadable, downloading e unavailable.

• Zero custos de API, zero dependência de servidores externos e total privacidade de dados.

• Console dedicado de diagnóstico e benchmark local em /ai-test.

2. 👁️ Visão Multimodal & OCR de Documentos

• Ingestão e upload de imagens (PNG, JPG, WebP) de documentos estudantis e identificações oficiais (CNH, RG).

• Pipeline de codificação Base64 e formatação no padrão inline_data para modelos Gemini Multimodais.

• Extração estruturada em JSON tipado: Nome, CPF, Data de Nascimento, Filiação e Categoria.

• Preenchimento automático inteligente no formulário de matrícula em /dashboard/students/new.

3. 🛡️ Formulário Inteligente com Guardrails para Agentes

• Formulário de cadastro com proteção contra edição indevida de campos sensíveis por agentes autônomos.

• Matriz de campos permitidos vs. proibidos: o agente pode preencher dados cadastrais básicos validados, mas é expressamente impedido de alterar campos protegidos (como percentual de bolsa, matrícula interna e registros de auditoria).

4. 🗂️ Arquitetura de Páginas Aninhadas em 3 Níveis

O agente compreende hierarquias profundas de navegação, discernindo relações pai-filho:

• Nível 1 (Menu Principal): /dashboard/requirements — Central de Requerimentos Acadêmicos.

• Nível 2 (Subpágina): /dashboard/requirements/courses — Requerimentos por Cursos.

• Nível 3 (Sub-subpáginas Específicas):

  • /dashboard/requirements/courses/react — Critérios de Aprovação em React Avançado.

  • /dashboard/requirements/courses/architecture — Critérios de Arquitetura de Software & MCP.

  • /dashboard/requirements/courses/nextjs — Critérios de Server Components & Performance.

• Academy Tracks (/dashboard/tracks): 3 Módulos de Especialização e 9 Laboratórios práticos com foco óptico animado (Pulso Visual).

5. 🔒 Segurança & RBAC Rigoroso

• Nenhum router.push(arbitraryUrl): A aplicação bloqueia integralmente qualquer tentativa de redirecionamento para URLs não registradas na whitelist.

• Prevenção de Prompt Injection: Comandos maliciosos do usuário que tentem forçar o agente a executar ações administrativas ou pular etapas pedagógicas são bloqueados deterministicamente pelo guardrail no código.

• Telemetria Criptografada: Todos os eventos MCP geram hashes SHA-256 e são monitorados em tempo real no dashboard de observabilidade em /observability.

🧩 Contrato de Atributos Semânticos (DOM Layer)

🛠️ Stack Tecnológica

• Framework: Next.js 15+ com App Router e Turbopack.

• Linguagem: TypeScript 5 (Tipagem estrita em ponta a ponta).

• Interface & Estilização: React 19, Tailwind CSS v4, Glassmorphism e Dark Mode nativo.

• Ícones: Lucide React.

• Protocolo de IA: Model Context Protocol (MCP).

• Modelos de IA Suportados:

  • Google Gemini Nano (Chrome Built-in AI, execução local on-device).

  • Google Gemini 2.5 Flash / Pro (Visão multimodal e tool calling).

  • LearnFlow Native Heuristic Provider (Determinístico, sem dependência externa).

• Validação de Schemas: Zod.

• Testes: Jest & React Testing Library.

🚀 Como Executar o Projeto

Pré-requisitos

• Node.js: Versão 20 ou superior recomendada.

• Navegador: Google Chrome Canary ou Dev (para testar a flag do Chrome Built-in AI / Gemini Nano).

Passo a Passo

# 1. Clone o repositório
git clone https://github.com/seu-usuario/web-mcp-semantic-navigator.git
cd web-mcp-semantic-navigator

# 2. Instale as dependências
npm install
# ou
yarn install

# 3. Inicie o servidor de desenvolvimento
npm run dev
# ou
yarn dev

Abra http://localhost:3000 no navegador.

Habilitando o Gemini Nano Local (Chrome Built-in AI)

Para testar a inferência local sem API Key:

1. Abra o Chrome (versão 128+) e acesse chrome://flags.

2. Habilite Enables optimization guide on device para Enabled BypassPerfRequirement.

3. Habilite Prompt API for Gemini Nano para Enabled.

4. Reinicie o navegador e abra /ai-test para verificar o status available.

🧪 Testes Automatizados

O projeto possui uma suíte rigorosa de 75 testes automatizados cobrindo todas as camadas do sistema:

npm test

PASS tests/nested-requirements.test.ts (13 tests)
PASS tests/three-level-tracks.test.ts (12 tests)
PASS tests/student-form.test.ts (8 tests)
PASS tests/gemini-nano.test.ts (9 tests)
PASS tests/vision-client.test.ts (7 tests)
PASS tests/document-extractor.test.ts (4 tests)
PASS tests/scanner.test.ts (5 tests)
PASS tests/registry.test.ts (5 tests)
PASS tests/permissions.test.ts (5 tests)
PASS tests/mcp-tools.test.ts (4 tests)
PASS tests/intent-and-flow.test.ts (3 tests)

Test Suites: 11 passed, 11 total
Tests:       75 passed, 75 total
Snapshots:   0 total
Time:        5.794 s

🗺️ Mapa de Rotas do Projeto

📄 Licença

Distribuído sob a licença MIT. Veja LICENSE para mais detalhes.