Pular para o conteúdo principal

Lucent Minds Central (Convers-A-Tron) - Visão Geral

Plataforma multi-tenant de workspace com IA para times corporativos, unificando chat, agentes, governança e analytics em uma única experiência.

1. Visão Geral do Projeto​

  • Nome do Projeto: Lucent Minds Central (Convers-A-Tron)
  • Status: 🟢 Desenvolvimento Ativo
  • Repositório: https://github.com/LucentMinds-ai/lucentminds-central
  • Frontend: React 18 + Vite + TypeScript + shadcn/ui
  • Backend: Express + Node.js + TypeScript + Supabase
  • Data de referência desta documentação: 13 de fevereiro de 2026

2. Objetivo de Negócio​

A plataforma foi projetada para oferecer um ambiente centralizado para uso de LLMs com foco em:

  • Governança de acesso por usuário e grupo
  • Controle de custo e consumo (tokens/custo por período)
  • Produtividade com agentes e conhecimento reutilizável
  • Visibilidade executiva por meio de analytics e tracking

3. Arquitetura do Sistema​

3.1 Arquitetura de Alto Nível​

3.2 Componentes da Arquitetura​

ComponenteTecnologiaPortaFunção
FrontendReact 18 + Vite + TypeScript8080Interface SPA com roteamento, i18n, TanStack Query
Backend APIExpress + TypeScript4000API REST com autenticação JWT, RBAC, streaming SSE
DatabaseSupabase PostgreSQL-Armazenamento com RLS, auth integrado
StorageMinIO/GCS/S3/Azure-Abstração multi-cloud para uploads
MLflow WorkerNode.js + TypeScript-Tracking assíncrono de métricas e custos
Topic WorkerNode.js + TypeScript-Classificação automática de conversas
Analytics WorkersNode.js + TypeScript-ETL e qualidade de dados

3.3 Fluxo de Dados - Chat com Streaming​

4. Provedores de LLM Suportados​

A plataforma suporta múltiplos provedores de LLM através de uma arquitetura unificada de streaming.

4.1 OpenAI​

Modelos Suportados:

  • gpt-4o - Modelo mais avançado, multimodal
  • gpt-4o-mini - Versão otimizada e econômica
  • gpt-4-turbo - Alta performance
  • gpt-4 - Modelo base GPT-4
  • gpt-3.5-turbo - Modelo econômico para uso geral
  • gpt-3.5-turbo-16k - Versão com contexto expandido

Características:

  • Streaming nativo via OpenAI SDK
  • Suporte a visão (GPT-4 Vision)
  • Pricing: $0.0025-$0.03 por 1K tokens (input)

4.2 Anthropic Claude​

Modelos Suportados:

  • claude-sonnet-4-20250514 - Última geração Sonnet
  • claude-opus-4-20250514 - Modelo mais poderoso
  • claude-3-5-sonnet-20241022 - Sonnet 3.5
  • claude-3-opus-20240229 - Opus 3
  • claude-3-sonnet-20240229 - Sonnet 3
  • claude-3-haiku-20240307 - Modelo rápido e econômico
  • claude-2.1 / claude-2.0 - Versões anteriores
  • claude-instant-1.2 - Versão instantânea

Características:

  • Streaming via Anthropic SDK
  • Suporte a visão (Claude 3+)
  • Contexto longo (até 200K tokens)
  • Pricing: $0.00025-$0.075 por 1K tokens (input)

4.3 Google Gemini​

Modelos Suportados:

  • gemini-2.5-pro - Modelo principal de alta performance
  • gemini-2.5-flash - Versão rápida e econômica
  • gemini-pro-1.5 - Versão Pro 1.5
  • gemini-2.0-flash-exp - Versão experimental

Características:

  • Streaming via Google Generative AI SDK
  • Multimodal nativo (texto, imagem, vídeo)
  • Pricing: $0.000075-$0.00125 por 1K tokens (input)

4.4 AWS Bedrock​

Modelos Suportados:

Claude via Bedrock:

  • anthropic.claude-3-5-sonnet-20241022-v2:0
  • anthropic.claude-3-5-haiku-20241022-v1:0
  • anthropic.claude-3-opus-20240229-v1:0

Meta Llama via Bedrock:

  • meta.llama3-3-70b-instruct-v1:0
  • meta.llama3-1-70b-instruct-v1:0
  • meta.llama3-1-8b-instruct-v1:0

Amazon Titan:

  • amazon.titan-text-premier-v1:0
  • amazon.titan-text-express-v1

Características:

  • Acesso via AWS SDK
  • Integração com infraestrutura AWS
  • Pricing variável por modelo

4.5 OpenRouter​

Modelos Suportados:

  • Acesso a múltiplos modelos através de API unificada
  • openai/gpt-4o, openai/gpt-4-turbo
  • anthropic/claude-sonnet-4-20250514
  • anthropic/claude-3.5-sonnet
  • google/gemini-2.0-flash-exp
  • google/gemini-pro-1.5
  • meta-llama/llama-3.1-70b-instruct
  • meta-llama/llama-3.1-8b-instruct

Características:

  • Gateway unificado para múltiplos provedores
  • API compatível com OpenAI
  • Pricing transparente por modelo

4.6 DeepSeek​

Modelos Suportados:

  • deepseek-chat - Modelo de chat geral
  • deepseek-coder - Otimizado para código

Características:

  • API compatível com OpenAI
  • Pricing econômico: $0.00014 por 1K tokens (input)
  • Excelente para tarefas de código

4.7 Outros Provedores​

Inception Models:

  • mercury - Modelo geral
  • mercury-coder - Versão para código

5. Como Funciona​

5.1 Autenticação e Autorização​

Fluxo:

  1. Usuário faz login via Supabase Auth
  2. Frontend recebe JWT token
  3. Todas as requisições incluem Authorization: Bearer <token>
  4. Middleware valida token e extrai userId
  5. RBAC verifica role (admin ou standard_user)
  6. Verifica acesso ao modelo via grupo do usuário
  7. Permite ou bloqueia requisição

5.2 Sistema de Grupos e Acesso a Modelos​

Características:

  • Usuários pertencem a grupos
  • Grupos têm acesso a modelos específicos
  • Modelos podem ser marcados como "default" por grupo
  • Admin pode gerenciar grupos e modelos

5.3 Streaming de Chat​

O sistema usa Server-Sent Events (SSE) para streaming em tempo real:

  1. Frontend envia requisição POST para /api/chat
  2. Backend configura headers SSE (Content-Type: text/event-stream)
  3. Chat Service seleciona provedor baseado no modelId
  4. Provedor LLM retorna stream de chunks
  5. Backend formata chunks como data: {content: "...", done: false}
  6. Frontend recebe chunks e renderiza incrementalmente
  7. Finalização: data: [DONE] + tokens + custo

5.4 Sistema de Agentes​

Como Funciona:

  • Agentes são instruções customizadas criadas por admins
  • Agentes são associados a grupos
  • Quando uma conversa tem agent_id, as instruções são prependidas ao prompt
  • Permite personalização de comportamento por grupo/use case

5.5 Knowledge Base e Mensagens Fixadas​

Fluxo:

  1. Usuário fixa mensagem importante no chat
  2. Opcionalmente atribui a uma pasta
  3. Mensagem aparece na Knowledge Base
  4. Busca permite encontrar conteúdo
  5. Deep link retorna ao chat original

5.6 Analytics e Tracking​

Métricas Coletadas:

  • Tokens (input/output) por mensagem
  • Custo por mensagem e conversa
  • Tempo de resposta
  • Modelo utilizado
  • Usuário e grupo
  • Tópicos classificados

6. Funcionalidades Principais​

6.1 Chat Multi-Provedor​

  • ✅ Streaming SSE em tempo real
  • ✅ Suporte a múltiplos modelos simultaneamente
  • ✅ Roteamento inteligente por grupo
  • ✅ Suporte a visão (imagens)
  • ✅ Contexto de documentos
  • ✅ Histórico de conversas

6.2 Governança e Controle​

  • ✅ RBAC: Roles (admin, standard_user)
  • ✅ Grupos: Controle de acesso por grupo
  • ✅ Limites: Tokens ou custo por período (diário/semanal/mensal)
  • ✅ Avisos: Banner de aviso em 90% de uso
  • ✅ Bloqueio: Desabilita chat em 100% de limite

6.3 Agentes​

  • ✅ Instruções customizadas por grupo
  • ✅ Associação automática em conversas
  • ✅ Múltiplos agentes por grupo
  • ✅ Gerenciamento via admin UI

6.4 Knowledge Base​

  • ✅ Fixar mensagens importantes
  • ✅ Organização em pastas
  • ✅ Busca full-text
  • ✅ Deep linking para contexto
  • ✅ Exportação e cópia

6.5 Analytics Administrativos​

  • ✅ Métricas de Uso: Mensagens, tokens, conversas
  • ✅ Análise de Custo: Por modelo, usuário, grupo, período
  • ✅ Champions: Usuários mais ativos
  • ✅ Adoção: Taxa de uso por grupo
  • ✅ Exportação CSV: Relatórios completos
  • ✅ Visualizações: Gráficos interativos

6.6 Feature Flags​

  • ✅ Habilitação gradual de features
  • ✅ Controle por ambiente/tenant
  • ✅ UI administrativa
  • ✅ Features disponíveis:
    • Message pinning
    • Voice input
    • Attachments
    • Advanced analytics

6.7 Classificação de Tópicos​

  • ✅ Classificação automática de conversas
  • ✅ Múltiplos provedores (Ollama, OpenAI, Anthropic)
  • ✅ Scores de confiança
  • ✅ Categorias configuráveis

6.8 Playground (Recursos Experimentais)​

HR Recruitment​

  • ✅ Análise de candidatos via IA
  • ✅ Upload de CVs (PDF)
  • ✅ Integração LinkedIn
  • ✅ Deduplicação e detecção de fraude
  • ✅ Comparação lado a lado
  • ✅ Scores e recomendações

CRM Deal Quality Auditing​

  • ✅ Análise de pipeline de vendas
  • ✅ KPIs e métricas de qualidade
  • ✅ Flags de risco
  • ✅ Recomendações acionáveis
  • ✅ Dashboard interativo

6.9 MCP (Model Context Protocol)​

  • ✅ Catálogo de ferramentas
  • ✅ Conexão e execução de ferramentas
  • ✅ Governança de acesso
  • ✅ Integração com agentes

6.10 Internacionalização​

  • ✅ Suporte a 3 idiomas: en, pt_BR, es
  • ✅ Interface traduzida
  • ✅ Relatórios localizados
  • ✅ Seletor de idioma

7. Segurança​

7.1 Autenticação​

  • ✅ JWT Supabase com validação server-side
  • ✅ Session expiration automática
  • ✅ Inactivity timeout (15 minutos)
  • ✅ Logout automático em 401

7.2 Autorização​

  • ✅ RBAC middleware em todas as rotas
  • ✅ Verificação de ownership antes de operações
  • ✅ Controle de acesso a modelos por grupo
  • ✅ RLS policies no Supabase

7.3 Rate Limiting​

EndpointLimiteJanelaProteção
Global API1000 req15 minDoS, abuso
/api/chat10 req1 minGastos ilimitados
/api/upload5 req1 minExaustão de storage
HR Analysis2 req1 minOperações caras

7.4 Validação de Input​

  • ✅ Schema validation com Zod
  • ✅ Limites de recursos:
    • Mensagens: 1-50 por request
    • Caracteres: 1-50,000 por mensagem
    • Imagens: Máximo 10 por request
  • ✅ Sanitização XSS com DOMPurify
  • ✅ Prevenção SQL Injection via UUID validation

7.5 Security Headers​

  • ✅ Content-Security-Policy
  • ✅ Strict-Transport-Security
  • ✅ X-Frame-Options
  • ✅ X-Content-Type-Options
  • ✅ Referrer-Policy
  • ✅ Permissions-Policy
  • ✅ Cross-Origin-Resource-Policy

8. Stack Técnico Detalhado​

8.1 Frontend​

TecnologiaVersãoUso
React18.3.1UI framework
TypeScript5.8.3Type safety
Vite5.4.19Build tool
shadcn/ui-Componentes UI
TailwindCSS3.4.17Estilização
TanStack Query5.83.0Server state
React Router6.30.1Roteamento
i18next25.6.0Internacionalização

8.2 Backend​

TecnologiaVersãoUso
Express4.19.2Web framework
TypeScript5.8.3Type safety
Supabase JS2.75.0Database client
OpenAI SDK4.63.0OpenAI integration
Anthropic SDK0.65.0Claude integration
AWS SDK3.928.0Bedrock integration
Google AI SDK0.24.1Gemini integration

8.3 Database​

  • PostgreSQL via Supabase
  • Row-Level Security (RLS) para multi-tenancy
  • RPC Functions para lógica complexa
  • Realtime subscriptions para updates

8.4 Storage​

  • Abstração multi-cloud:
    • MinIO (desenvolvimento)
    • Google Cloud Storage (GCS)
    • AWS S3 (futuro)
    • Azure Blob Storage (futuro)

9. Principais Rotas da API​

9.1 Autenticação​

  • POST /api/auth/signup - Registro
  • POST /api/auth/signin - Login
  • POST /api/auth/signout - Logout
  • GET /api/users/me - Perfil do usuário

9.2 Chat​

  • POST /api/chat - Chat com streaming SSE

9.3 Conversas​

  • GET /api/conversations - Lista conversas
  • POST /api/conversations - Cria conversa
  • GET /api/conversations/:id - Detalhes
  • PUT /api/conversations/:id - Atualiza
  • DELETE /api/conversations/:id - Deleta

9.4 Modelos e Grupos​

  • GET /api/models - Lista modelos disponíveis
  • GET /api/groups - Lista grupos
  • POST /api/groups - Cria grupo
  • PUT /api/groups/:id - Atualiza grupo

9.5 Agentes​

  • GET /api/agents - Lista agentes
  • POST /api/agents - Cria agente
  • PUT /api/agents/:id - Atualiza agente
  • DELETE /api/agents/:id - Deleta agente

9.6 Knowledge Base​

  • GET /api/pinned-messages - Lista mensagens fixadas
  • POST /api/pinned-messages - Fixa mensagem
  • DELETE /api/pinned-messages/:id - Remove fixação
  • GET /api/folders - Lista pastas
  • POST /api/folders - Cria pasta

9.7 Analytics​

  • GET /api/analytics/usage - Métricas de uso
  • GET /api/analytics/cost - Análise de custo
  • GET /api/analytics/champions - Usuários champions
  • GET /api/adoption - Métricas de adoção

9.8 Limites​

  • GET /api/limits/check - Verifica limites
  • GET /api/limits/usage - Uso atual

9.9 Playground​

  • GET /api/playground/hr-recruitment/experiments - Lista experimentos HR
  • POST /api/playground/hr-recruitment/experiments/:id/analyze - Analisa candidatos
  • GET /api/playground/crm-auditing/dashboard - Dashboard CRM

10. Comandos de Desenvolvimento​

# Frontend
npm run dev              # Vite dev server (port 8080)

# Backend
npm run dev:server       # Express API (port 4000)

# Workers
npm run worker:mlflow    # MLflow tracking worker
npm run worker:topics    # Topic classification worker
npm run worker:knowledge # Knowledge base worker
npm run worker:analytics-etl    # Analytics ETL worker
npm run worker:data-quality     # Data quality worker

# Tudo junto
npm run dev:all          # Frontend + Backend + Workers essenciais

# Build e Testes
npm run build            # Production build
npm run lint             # ESLint + TypeScript checks
npm run test:server      # Backend tests (Vitest)

11. Variáveis de Ambiente​

11.1 Frontend (.env.local)​

VITE_SUPABASE_URL=your-supabase-url
VITE_SUPABASE_ANON_KEY=your-anon-key

11.2 Backend (.env)​

# Supabase
SUPABASE_SERVICE_ROLE_KEY=your-service-role-key

# LLM Providers
OPENAI_API_KEY=your-openai-key
ANTHROPIC_API_KEY=your-anthropic-key
DEEPSEEK_API_KEY=your-deepseek-key
OPENROUTER_API_KEY=your-openrouter-key

# Storage
STORAGE_PROVIDER=minio  # ou gcs, s3, azure
MINIO_ENDPOINT=localhost
MINIO_PORT=9000
MINIO_ACCESS_KEY=minioadmin
MINIO_SECRET_KEY=minioadmin
MINIO_BUCKET_NAME=uploads

# MLflow (opcional)
MLFLOW_ENABLED=true
MLFLOW_TRACKING_URI=http://localhost:5000
MLFLOW_EXPERIMENT_NAME=chat-experiments

# Topic Classification (opcional)
TOPIC_CLASSIFICATION_ENABLED=true
TOPIC_CLASSIFICATION_PROVIDER=ollama  # ou openai, anthropic
OLLAMA_ENDPOINT=http://localhost:11434
OLLAMA_MODEL=llama3:8b

# Server
PORT=4000
NODE_ENV=development

12. Referências Técnicas​

12.1 Arquivos Principais​

Frontend:

  • src/App.tsx - Entry point
  • src/routes/routes.config.tsx - Configuração de rotas
  • src/pages/Index.tsx - Chat principal
  • src/pages/AdminDashboard.tsx - Dashboard admin
  • src/pages/KnowledgeBase.tsx - Knowledge base
  • src/pages/Settings.tsx - Configurações

Backend:

  • server/index.ts - Bootstrap Express
  • server/routes.ts - Registro de rotas
  • server/chat.ts - Chat endpoint
  • server/services/chat/orchestration-service.ts - Orquestração de chat
  • server/middleware/auth.ts - Autenticação
  • server/middleware/rbac.ts - RBAC
  • server/utils/pricing.ts - Cálculo de custos

Workers:

  • server/workers/mlflow-worker.ts - Tracking MLflow
  • server/workers/topic-classification-worker.ts - Classificação
  • server/workers/analytics-etl-worker.ts - ETL analytics
  • server/workers/knowledge-worker.ts - Knowledge base

12.2 Database Schema​

Principais tabelas:

  • profiles - Usuários
  • conversations - Conversas
  • messages - Mensagens
  • models - Catálogo de modelos
  • model_providers - Provedores
  • groups - Grupos
  • user_groups - Associação usuário-grupo
  • group_models - Associação grupo-modelo
  • agents - Agentes
  • agent_groups - Associação agente-grupo
  • pinned_messages - Mensagens fixadas
  • folders - Pastas knowledge base
  • feature_flags - Feature flags
  • tracking_queue - Fila MLflow
  • conversation_topics - Tópicos classificados

13. Roadmap e Melhorias Futuras​

13.1 Em Desenvolvimento​

  • Melhorias no sistema de guardrails
  • Expansão de integrações MCP
  • Otimizações de performance
  • Novos módulos de playground

13.2 Planejado​

  • Suporte a mais provedores de LLM
  • Melhorias na Knowledge Base
  • Analytics avançados
  • API pública para integrações

Última Atualização: 13 de fevereiro de 2026
Mantido Por: Equipe Lucent Minds