PROJECT_STRUCTURE.md

Estrutura do Projeto - RAG Template

Estrutura organizada e limpa do projeto após Fase 1.

Estrutura de Diretórios

rag_template/
├── app.py                      # Aplicação principal Gradio
├── requirements.txt            # Dependências Python
├── docker-compose.yml          # PostgreSQL local com pgvector
├── .env.example               # Template de variáveis de ambiente
├── .gitignore                 # Arquivos ignorados pelo Git
│
├── README.md                  # Documentação principal (com YAML do HF Spaces)
├── CHANGELOG.md               # Histórico de versões
├── DEPLOY.md                  # Guia de deploy GitHub/HF Spaces
├── LICENSE                    # Licença MIT
├── PROJECT_STRUCTURE.md       # Este arquivo
│
├── src/                       # Módulos backend
│   ├── __init__.py
│   ├── config.py             # Configurações centralizadas
│   ├── database.py           # PostgreSQL + pgvector
│   ├── embeddings.py         # Sentence Transformers com cache
│   ├── chunking.py           # 4 estratégias de chunking
│   ├── document_processing.py # Extração PDF/TXT
│   ├── generation.py         # LLM generation (multi-provider)
│   ├── cache.py              # Sistema de cache (memória + disco)
│   ├── logging_config.py     # Logging estruturado
│   └── llms/                 # Módulo de LLM providers
│       ├── __init__.py
│       ├── base.py           # Classe base abstrata
│       ├── factory.py        # Factory com fallback
│       ├── huggingface.py    # Provider HuggingFace
│       ├── openai.py         # Provider OpenAI
│       ├── anthropic.py      # Provider Anthropic
│       └── ollama.py         # Provider Ollama
│
├── ui/                        # Componentes de interface
│   ├── __init__.py
│   ├── custom_css.py         # Design system (Inter + #ffbe00)
│   ├── ingestion_tab.py      # Aba de ingestão (4 estratégias)
│   ├── exploration_tab.py    # Aba de exploração
│   ├── chat_tab.py           # Aba de chat RAG (multi-LLM)
│   ├── playground_tab.py     # Aba de playground
│   ├── chunking_comparison_tab.py # Aba de comparação (NOVO)
│   └── monitoring_tab.py     # Aba de monitoramento
│
├── docs/                      # Documentação adicional
│   ├── ROADMAP.md            # Planejamento 6 fases
│   ├── SUPABASE_SETUP.md     # Setup Supabase
│   ├── DESIGN_SYSTEM.md      # Especificações de design
│   └── MULTI_USER_SETUP.md   # Opções de multi-user
│
├── db/                        # Scripts de banco de dados
│   ├── init/
│   │   ├── 01_init.sql       # Inicialização pgvector
│   │   └── 02_indexes.sql    # Índices IVFFLAT
│   ├── migrations/           # Migrações SQL (NOVO)
│   │   ├── 001_add_metadata_columns.sql
│   │   └── 002_optimize_indexes.sql
│   └── migrate.py            # Script de migração (NOVO)
│
└── tests/                     # Testes automatizados
    ├── __init__.py
    ├── test_units.py         # Testes unitários
    ├── test_integration_db.py # Testes de integração
    └── test_llms.py          # Testes de LLM providers (NOVO)

## Arquivos Não Versionados (.gitignore)

- `.env` - Variáveis de ambiente locais
- `venv/`, `.venv/` - Ambientes virtuais Python
- `__pycache__/`, `*.pyc` - Cache Python
- `*.log` - Arquivos de log
- `.DS_Store` - Metadata macOS
- `*.db`, `*.sqlite` - Bancos de dados locais
- `gradio_cached_examples/` - Cache do Gradio

## Variáveis de Ambiente (.env)

```bash
# Database
DATABASE_URL=postgresql://user:pass@host:port/db

# Hugging Face
HF_TOKEN=seu_token_aqui
HF_MODEL_ID=mistralai/Mistral-7B-Instruct-v0.2

# Embeddings
EMBEDDING_MODEL_ID=sentence-transformers/all-MiniLM-L6-v2
EMBEDDING_DIM=384

# App
APP_PORT=7860

Fluxo de Dados

1. UPLOAD
   User → ingestion_tab.py → document_processing.py → Text

2. CHUNKING
   Text → chunking.py → Chunks

3. EMBEDDINGS
   Chunks → embeddings.py (SentenceTransformer) → Vectors

4. STORAGE
   Vectors → database.py → PostgreSQL (pgvector)

5. RETRIEVAL
   Query → embeddings.py → Vector → database.py (similarity) → Top-K Chunks

6. GENERATION
   Chunks + Query → generation.py (HF API) → Response

Tecnologias por Módulo

Módulo	Tecnologia	Versão
Interface	Gradio	4.36.0+
Database	PostgreSQL + pgvector	Latest
Embeddings	sentence-transformers	2.6.1+
LLM	Mistral-7B-Instruct-v0.2	HF API
Backend	Python	3.10+
ORM/Driver	psycopg	3.1.18+
PDF	pypdf	5.0.0+

Convenções de Código

Nomenclatura

• Arquivos: snake_case.py
• Classes: PascalCase
• Funções: snake_case()
• Constantes: UPPER_SNAKE_CASE

Docstrings

def function_name(param: Type) -> ReturnType:
    """
    Breve descrição da função

    Args:
        param: Descrição do parâmetro

    Returns:
        Descrição do retorno
    """

Imports

# Standard library
import os
import time

# Third-party
import gradio as gr
import psycopg

# Local
from src.config import DATABASE_URL
from src.database import DatabaseManager

Próximos Passos (Fase 2 - Roadmap)

Melhorias Técnicas

• Testes unitários completos
• Testes de integração
• CI/CD com GitHub Actions
• Type hints completos
• Logging estruturado

Otimizações

• Cache de embeddings
• Batch processing otimizado
• Connection pooling
• Lazy loading de modelos

Features

• Suporte DOCX, HTML, Markdown
• Reranking com cross-encoder
• Hybrid search (vetorial + BM25)
• Visualização de embeddings

Manutenção

Adicionar Nova Funcionalidade

1. Criar módulo em src/ se backend
2. Criar componente em ui/ se interface
3. Atualizar app.py com integração
4. Adicionar testes em tests/
5. Documentar em docs/
6. Atualizar CHANGELOG.md

Atualizar Dependências

pip list --outdated
pip install -U package_name
pip freeze > requirements.txt

Rodar Testes

pytest tests/ -v
pytest tests/test_units.py -v
pytest tests/test_integration_db.py -v

---

Última atualização: Janeiro 2026 - Fase 1 Completa Versão: 1.1.0