Coria - Sistema de Gestão de Conhecimento

Sistema de gestão de conhecimento para processamento de transcrições de reuniões com empreendedores da base da pirâmide (BOP). O sistema utiliza IA para extrair indicadores de desenvolvimento e gerar resumos executivos automaticamente.

📋 Visão Geral

O Coria é uma plataforma que permite:

• Gerenciar projetos de consultoria empresarial
• Organizar empresas e empreendedores por projeto
• Definir indicadores de crescimento e desenvolvimento
• Processar transcrições de reuniões automaticamente
• Extrair valores de indicadores usando IA
• Gerar resumos executivos das reuniões
• Visualizar progresso ao longo do tempo

🏗️ Arquitetura do Sistema

graph TB
    subgraph "Frontend (React + Vite)"
        UI[Interface do Usuário]
        Pages[Páginas: Dashboard, Transcrições, Indicadores]
        API_Client[API Client - Axios]
    end
    
    subgraph "Backend (FastAPI)"
        Router[API Routers]
        Services[AI Services]
        DB_ORM[(SQLAlchemy ORM)]
    end
    
    subgraph "Banco de Dados"
        DB[(SQLite Database)]
        Tables[Projects, Companies, Entrepreneurs,<br/>Indicators, IndicatorValues,<br/>Transcriptions]
    end
    
    subgraph "IA & Processamento"
        OpenAI[OpenAI GPT-4o-mini<br/>Resumos Executivos]
        Embeddings[Sentence Transformers<br/>Embeddings]
        BM25[BM25<br/>Busca por Palavras-chave]
        Reranker[Cross-encoder<br/>Reranking]
    end
    
    UI --> Pages
    Pages --> API_Client
    API_Client --> Router
    Router --> Services
    Router --> DB_ORM
    DB_ORM --> DB
    DB --> Tables
    Services --> OpenAI
    Services --> Embeddings
    Services --> BM25
    Services --> Reranker
    
    style UI fill:#e1f5ff
    style Router fill:#fff4e1
    style DB fill:#e8f5e9
    style OpenAI fill:#fce4ec
    style Embeddings fill:#fce4ec
    style BM25 fill:#fce4ec
    style Reranker fill:#fce4ec

Loading

🔄 Fluxo de Dados

1. Criação de Projeto e Configuração

sequenceDiagram
    participant U as Usuário
    participant F as Frontend
    participant B as Backend
    participant DB as Database
    
    U->>F: Criar Projeto
    F->>B: POST /api/projects
    B->>DB: Criar Project
    DB-->>B: Project criado
    B-->>F: Project data
    F-->>U: Projeto exibido
    
    U->>F: Criar Empresa/Empreendedor
    F->>B: POST /api/entrepreneurs (se novo)
    B->>DB: Criar Entrepreneur
    F->>B: POST /api/companies
    B->>DB: Criar Company (link Entrepreneur)
    
    U->>F: Criar Indicador Template
    F->>B: POST /api/indicators
    B->>DB: Criar Indicator (template)

Loading

2. Upload e Processamento de Transcrição

sequenceDiagram
    participant U as Usuário
    participant F as Frontend
    participant B as Backend
    participant AI as AI Services
    participant DB as Database
    
    U->>F: Upload Transcrição + Metadados
    F->>B: POST /api/transcriptions/upload
    B->>DB: Salvar Transcription
    DB-->>B: Transcription criada
    
    B->>AI: Gerar Resumo Executivo
    AI->>AI: OpenAI GPT-4o-mini
    AI-->>B: Executive Summary
    B->>DB: Atualizar Transcription.summary
    
    B->>AI: Extrair Indicadores
    loop Para cada Indicator Template
        AI->>AI: Hybrid Search<br/>(Embeddings + BM25)
        AI->>AI: Reranking
        AI->>AI: LLM Extraction
        AI-->>B: IndicatorValue
        B->>DB: Salvar IndicatorValue
    end
    
    B-->>F: Transcription + Summary + Values
    F-->>U: Resultado exibido

Loading

3. Visualização e Análise

sequenceDiagram
    participant U as Usuário
    participant F as Frontend
    participant B as Backend
    participant DB as Database
    
    U->>F: Acessar Dashboard
    F->>B: GET /api/indicator-values?project_id=X
    B->>DB: Query IndicatorValues
    DB-->>B: Time-series data
    B-->>F: Aggregated indicators
    F-->>U: Gráficos e métricas
    
    U->>F: Filtrar por Empresa/Reunião
    F->>B: GET /api/indicator-values?company_id=Y
    B->>DB: Filtered query
    DB-->>B: Filtered data
    B-->>F: Filtered results
    F-->>U: Dados filtrados

Loading

📊 Modelo de Dados

erDiagram
    Project ||--o{ Company : "has"
    Project ||--o{ Entrepreneur : "has"
    Project ||--o{ Indicator : "defines"
    Project ||--o{ Transcription : "contains"
    
    Entrepreneur ||--o{ Company : "owns"
    
    Company ||--o{ Transcription : "has"
    Company ||--o{ IndicatorValue : "measures"
    
    Indicator ||--o{ IndicatorValue : "has values"
    
    Transcription ||--o{ IndicatorValue : "extracts"
    
    Project {
        int id PK
        string name
        text description
        datetime created_at
    }
    
    Entrepreneur {
        int id PK
        int project_id FK
        string name
        string email
        string phone
        text notes
    }
    
    Company {
        int id PK
        int project_id FK
        int entrepreneur_id FK
        string name
        boolean is_formal_company
        text description
    }
    
    Indicator {
        int id PK
        int project_id FK
        string name
        string indicator_type
        string category
        text description
        text extraction_query
    }
    
    Transcription {
        int id PK
        int project_id FK
        int company_id FK
        string filename
        text content
        text executive_summary
        datetime meeting_date
        string participants
        string meeting_type
    }
    
    IndicatorValue {
        int id PK
        int indicator_id FK
        int company_id FK
        int transcription_id FK
        float value
        text text_value
        datetime measured_at
    }

Loading

🎯 Funcionalidades Principais

1. Gestão de Projetos

• Criar e gerenciar múltiplos projetos
• Cada projeto é isolado com seus próprios dados

2. Gestão de Empresas e Empreendedores

• Criar empreendedores associados a projetos
• Associar empresas a empreendedores
• Suporte para empresas formais e informais

3. Definição de Indicadores

• Indicadores Template: Definições reutilizáveis por projeto
• Tipos de Indicadores:
  • company_growth: KPIs de crescimento da empresa
  • entrepreneur_development: KPIs de desenvolvimento do empreendedor
  • project: Indicadores específicos do projeto
• Extraction Query: Consulta personalizada para melhorar extração pela IA

4. Processamento Inteligente de Transcrições

• Upload com metadados (data, participantes, tipo de reunião)
• Geração Automática de Resumos Executivos usando OpenAI
• Extração Automática de Indicadores usando:
  • Hybrid Search: Combinação de busca semântica (embeddings) e busca por palavras-chave (BM25)
  • Reranking: Reordenação de resultados usando cross-encoder
  • LLM Extraction: Extração de valores usando LLM

5. Visualização e Análise

• Dashboard Agregado: Visão geral de todos os indicadores
• Filtros: Por empresa, por reunião (sessão de consultoria)
• Time-series Data: Valores de indicadores com timestamps para visualização temporal
• Histórico de Reuniões: Timeline de todas as reuniões com resumos

🛠️ Stack Tecnológica

Backend

• FastAPI: Framework web assíncrono
• SQLAlchemy 2.0: ORM para banco de dados
• SQLite: Banco de dados (desenvolvimento)
• Pydantic v2: Validação de dados
• OpenAI API: Geração de resumos executivos
• Sentence Transformers: Embeddings para busca semântica
• BM25: Busca por palavras-chave
• Cross-encoder: Reranking de resultados

Frontend

• React: Biblioteca UI
• Vite: Build tool e dev server
• React Router DOM: Roteamento
• TailwindCSS: Estilização
• Axios: Cliente HTTP

Infraestrutura

• Docker: Containerização
• Docker Compose: Orquestração de containers

📁 Estrutura do Projeto

coria/
├── backend/
│   ├── data/              # Banco de dados SQLite (persistente)
│   ├── uploads/           # Arquivos de transcrição
│   ├── routers/           # API endpoints
│   │   ├── projects.py
│   │   ├── companies.py
│   │   ├── entrepreneurs.py
│   │   ├── indicators.py
│   │   ├── indicator_values.py
│   │   ├── transcriptions.py
│   │   ├── reports.py
│   │   ├── ai_processing.py
│   │   └── meetings_history.py
│   ├── services/          # Lógica de negócio e IA
│   │   ├── ai_extraction.py    # Extração de indicadores
│   │   └── summary_generation.py  # Geração de resumos
│   ├── models.py          # Modelos SQLAlchemy
│   ├── schemas.py         # Schemas Pydantic
│   ├── database.py        # Configuração do banco
│   └── main.py            # Aplicação FastAPI
│
├── frontend/
│   ├── src/
│   │   ├── api/           # Clientes API
│   │   ├── components/    # Componentes React
│   │   ├── contexts/      # Context API
│   │   ├── pages/         # Páginas da aplicação
│   │   └── App.jsx        # Roteamento principal
│   └── ...
│
└── docker-compose.yml     # Configuração Docker

🚀 Configuração e Execução

Pré-requisitos

• Docker e Docker Compose
• OpenAI API Key (para geração de resumos)

Variáveis de Ambiente

Crie um arquivo .env na raiz do projeto (opcional):

OPENAI_API_KEY=sua_chave_aqui

Executando o Projeto

# Iniciar containers
docker-compose up -d

# Ver logs do backend
docker-compose logs -f backend

# Executar comandos no backend
docker exec -it coria_backend bash

# Parar containers
docker-compose down

Persistência de Dados

Os dados são persistidos em volumes Docker:

• Banco de dados: backend/data/app.db
• Uploads: backend/uploads/

Nota: Esses diretórios estão no .gitignore e não são versionados.

📡 API Endpoints Principais

Projetos

• GET /api/projects/ - Listar projetos
• POST /api/projects/ - Criar projeto
• GET /api/projects/{id} - Obter projeto
• DELETE /api/projects/{id} - Deletar projeto

Empresas

• GET /api/companies/?project_id={id} - Listar empresas
• POST /api/companies/ - Criar empresa
• GET /api/companies/{id} - Obter empresa

Empreendedores

• GET /api/entrepreneurs/?project_id={id} - Listar empreendedores
• POST /api/entrepreneurs/ - Criar empreendedor
• GET /api/entrepreneurs/{id} - Obter empreendedor

Indicadores

• GET /api/indicators/?project_id={id} - Listar templates
• POST /api/indicators/ - Criar template
• DELETE /api/indicators/{id} - Deletar template

Valores de Indicadores

• GET /api/indicator-values/?project_id={id}&company_id={id}&transcription_id={id} - Listar valores
• POST /api/indicator-values/ - Criar valor manualmente

Transcrições

• POST /api/transcriptions/upload - Upload de transcrição
• GET /api/transcriptions/?project_id={id} - Listar transcrições
• GET /api/transcriptions/{id} - Obter transcrição

IA e Processamento

• POST /api/ai/process-transcription/{id} - Reprocessar transcrição
• POST /api/meetings/generate-summary/{id} - Gerar resumo executivo

Relatórios

• GET /api/reports/project/{id} - Relatório do projeto
• GET /api/reports/company/{id} - Relatório da empresa

🔍 Como Funciona a Extração de Indicadores

1. Upload da Transcrição: Usuário faz upload com metadados (data, participantes, etc.)

2. Busca Híbrida: Para cada indicador template:

   • Dense Search: Gera embeddings da query e do texto, calcula similaridade de cosseno
   • BM25: Busca por palavras-chave com expansão de sinônimos
   • Combinação: Média ponderada (60% dense, 40% BM25)

3. Reranking: Usa cross-encoder para reordenar os chunks mais relevantes

4. Extração com LLM: Envia os chunks mais relevantes para o LLM extrair o valor do indicador

5. Armazenamento: Salva IndicatorValue com:

   • indicator_id: Referência ao template
   • company_id: Empresa associada
   • transcription_id: Transcrição de origem
   • value ou text_value: Valor extraído
   • measured_at: Data da reunião (para time-series)

🎨 Interface do Usuário

Navegação Principal

• Topbar: Link "Projetos" para voltar à lista de projetos

Dentro de um Projeto

• Navegação Secundária:
  • Dashboard (visão agregada)
  • Transcrições (gerenciamento)
  • Indicadores (templates)
• Botões de Ação (no canto direito da navegação):
  • "+ Empresa": Criar empresa/empreendedor
  • "+ Indicador": Criar indicador template

Dashboard

• Filtros por empresa e reunião
• Visualização agregada de indicadores
• Botões para upload e visualização de transcrições

📝 Notas de Desenvolvimento

• Migrações: Use scripts de migração (migrate_db.py, migrate_entrepreneurs.py) para alterar o schema
• Comandos no Backend: Sempre execute dentro do container Docker
• Comandos no Frontend: Execute localmente na pasta frontend/
• Banco de Dados: SQLite para desenvolvimento, pode ser migrado para PostgreSQL em produção

🔐 Segurança

• CORS configurado para desenvolvimento local
• API keys armazenadas em variáveis de ambiente
• Validação de dados com Pydantic
• Sanitização de uploads de arquivos

📄 Licença

Copyright 2025. Todos os direitos reservados.