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
```python
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
```python
# 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
```bash
pip list --outdated
pip install -U package_name
pip freeze > requirements.txt
```

### Rodar Testes
```bash
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