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

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