docs/ORGANIZATION_GUIDE.md

# RAG Capstone Project - Code Organization Guide

## 📁 Directory Structure After Code Review

```
RAG Capstone Project/
│
├─ 🎯 CORE APPLICATION (Active Production Code)
│  ├─ run.py ............................ Quick start launcher
│  ├─ streamlit_app.py .................. Main web interface
│  ├─ config.py ......................... Settings & configuration
│  ├─ vector_store.py ................... ChromaDB vector database
│  ├─ llm_client.py ..................... Groq LLM integration
│  ├─ embedding_models.py ............... Embedding factory pattern
│  ├─ chunking_strategies.py ............ Document chunking strategies
│  ├─ dataset_loader.py ................. RAGBench dataset loader
│  ├─ trace_evaluator.py ................ TRACE metric evaluation
│  ├─ advanced_rag_evaluator.py ......... Advanced metrics (RMSE, AUC)
│  └─ evaluation_pipeline.py ............ Evaluation orchestration
│
├─ 🛠️ UTILITIES & RECOVERY (Maintenance Tools)
│  ├─ rebuild_chroma_index.py ........... Rebuild ChromaDB indices
│  ├─ rebuild_sqlite_direct.py .......... Direct SQLite rebuild
│  ├─ recover_chroma_advanced.py ........ Advanced recovery utility
│  ├─ recover_collections.py ............ Collection recovery
│  ├─ rename_collections.py ............. Collection renaming
│  └─ reset_sqlite_index.py ............. Index reset utility
│
├─ 🧪 TEST SCRIPTS
│  ├─ test_llm_audit_trail.py ........... Audit trail testing
│  └─ test_rmse_aggregation.py .......... RMSE metric testing
│
├─ 📦 ARCHIVED (Moved from Main Directory)
│  └─ archived_scripts/
│     ├─ api.py ......................... [UNUSED] FastAPI implementation
│     ├─ audit_collection_names.py ...... [UNUSED] SQLite audit tool
│     ├─ cleanup_chroma.py .............. [UNUSED] Cleanup utility
│     ├─ create_architecture_diagram.py . [UNUSED] Diagram generator
│     ├─ create_ppt_presentation.py ..... [UNUSED] PPT generator
│     ├─ create_trace_flow_diagrams.py .. [UNUSED] Flow diagram generator
│     ├─ example.py ..................... [UNUSED] Example usage
│     └─ README.md ...................... Archive documentation
│
├─ ⚙️ CONFIGURATION & DEPLOYMENT
│  ├─ .env ............................... Environment variables (local)
│  ├─ .env.example ....................... Example environment
│  ├─ requirements.txt ................... Python dependencies
│  ├─ docker-compose.yml ................. Docker orchestration
│  ├─ Dockerfile ......................... Container definition
│  └─ Procfile ........................... Heroku/deployment manifest
│
├─ 💾 DATA & STORAGE
│  ├─ chroma_db/ ......................... ChromaDB vector storage
│  ├─ data_cache/ ........................ Cached datasets
│  ├─ venv/ ............................. Python virtual environment
│  └─ __pycache__/ ....................... Python bytecode cache
│
├─ 📚 DOCUMENTATION
│  ├─ CODE_REVIEW_REPORT.md ............. [NEW] Comprehensive code review
│  ├─ README.md .......................... Project documentation
│  └─ docs/ ............................. Additional documentation
│
└─ 📊 GENERATED OUTPUT
   ├─ RAG_Architecture_Diagram.png ....... System architecture
   ├─ RAG_Data_Flow_Diagram.png ......... Data flow visualization
   ├─ RAG_Capstone_Project_Presentation.pptx ... Presentation slides
   └─ Sentence_Mapping_Example.png ....... Example output
```

---

## 🎯 Quick Reference by Task

### Running the Application
```bash
python run.py              # Quick start launcher
streamlit run streamlit_app.py  # Direct web interface
```

### Core System Modules
- **Data Pipeline**: `dataset_loader.py` → `vector_store.py` → `embedding_models.py`
- **Query Pipeline**: `llm_client.py` → `trace_evaluator.py`
- **Orchestration**: `evaluation_pipeline.py` (coordinates everything)

### Database Maintenance
- **Corruption detected?** Run recovery scripts:
  - `recover_chroma_advanced.py` (recommended first)
  - `rebuild_chroma_index.py` (full rebuild)
  - `recover_collections.py` (collection-specific)

### Development & Testing
- **Test evaluation**: `test_llm_audit_trail.py`
- **Test metrics**: `test_rmse_aggregation.py`
- **Example usage**: See `archived_scripts/example.py`

---

## 📊 File Statistics

| Category | Count | Status |
|----------|-------|--------|
| Core Production | 11 | ✅ Active |
| Recovery/Utilities | 6 | ✅ In Use |
| Test Scripts | 2 | ✅ In Use |
| Archived | 7 | 📦 Not Used |
| Configuration | 5 | ✅ In Use |
| **Total** | **31** | **Clean** |

---

## 🔄 Why Files Were Moved

### Archived Files (7 total)
These files do NOT have any imports in the active codebase:
- **api.py** - Alternative FastAPI backend (not used; main app is Streamlit)
- **example.py** - Demo script; not part of production pipeline
- **Diagram/PPT generators** - Documentation tools; run standalone only
- **Audit script** - Development debugging tool; not in main flow
- **Cleanup script** - Maintenance utility; not in main flow

### Preserved Files (20 total)
These files ARE actively imported:
- **Core modules** - Required by streamlit_app.py and run.py
- **Recovery tools** - Critical for database maintenance
- **Test scripts** - Part of quality assurance process

---

## ✅ Code Review Highlights

### Strengths Found
✅ Well-structured modular architecture  
✅ Excellent factory pattern implementation  
✅ Intelligent rate limiting for API  
✅ Type-safe configuration with Pydantic  
✅ Clear separation of concerns  

### Improvement Recommendations
⚠️ Add structured logging (replace print statements)  
⚠️ Improve error handling (too many broad exceptions)  
⚠️ Add comprehensive type hints  
⚠️ Add input validation  
⚠️ Add performance monitoring  

**See CODE_REVIEW_REPORT.md for detailed analysis and recommendations**

---

## 📝 Notes

- **Recovery Scripts**: These are NOT "unused" - they're critical maintenance tools kept in main directory
- **Test Scripts**: These are NOT "unused" - they're part of development workflow
- **Archive**: Safe to delete archived_scripts/ if files are never needed again
- **Git**: All files remain in git history; no data is lost

---

**Last Updated**: January 1, 2026  
**Status**: ✅ Code cleanup complete and documented