# Project Structure

## Root Directory (Minimal & Clean)

```
Simulated_Assessment_Engine/
├── README.md                    # Complete documentation (all-in-one)
├── .gitignore                   # Git ignore rules
├── .env                         # API key (create this, not in git)
│
├── main.py                      # Simulation engine (Step 2)
├── config.py                    # Configuration
├── check_api.py                 # API connection test
├── run_complete_pipeline.py    # Master orchestrator (all 3 steps)
│
├── data/                        # Data files
│   ├── AllQuestions.xlsx        # Question mapping (1,297 questions)
│   ├── merged_personas.xlsx    # Merged personas (3,000 students, 79 columns)
│   └── demo_answers/           # Demo output examples
│
├── support/                     # Support files (required for Step 1)
│   ├── 3000-students.xlsx      # Student demographics
│   ├── 3000_students_output.xlsx  # Student CPIDs from database
│   └── fixed_3k_personas.xlsx  # Persona enrichment (22 columns)
│
├── scripts/                     # Utility scripts
│   ├── prepare_data.py          # Step 1: Persona preparation
│   ├── comprehensive_post_processor.py  # Step 3: Post-processing
│   ├── final_production_verification.py  # Production verification
│   └── [other utility scripts]
│
├── services/                    # Core services
│   ├── data_loader.py          # Load personas and questions
│   ├── simulator.py            # LLM simulation engine
│   └── cognition_simulator.py  # Cognition test simulation
│
├── output/                      # Generated output (gitignored)
│   ├── full_run/               # Production output (34 files)
│   └── dry_run/                # Test output (5 students)
│
└── docs/                        # Additional documentation
    ├── README.md               # Documentation index
    ├── DEPLOYMENT_GUIDE.md     # Deployment instructions
    ├── WORKFLOW_GUIDE.md       # Complete workflow guide
    ├── PROJECT_STRUCTURE.md    # This file
    └── [other documentation]
```

## Key Files

### Core Scripts
- **`main.py`** - Main simulation engine (processes all students)
- **`config.py`** - Configuration (API keys, settings, paths)
- **`run_complete_pipeline.py`** - Orchestrates all 3 steps
- **`check_api.py`** - Tests API connection

### Data Files
- **`data/AllQuestions.xlsx`** - All 1,297 questions with metadata
- **`data/merged_personas.xlsx`** - Unified persona file (79 columns, 3,000 rows)
- **`support/3000-students.xlsx`** - Student demographics
- **`support/3000_students_output.xlsx`** - Student CPIDs from database
- **`support/fixed_3k_personas.xlsx`** - Persona enrichment data

### Services
- **`services/data_loader.py`** - Loads personas and questions
- **`services/simulator.py`** - LLM-based response generation
- **`services/cognition_simulator.py`** - Math-based cognition test simulation

### Scripts
- **`scripts/prepare_data.py`** - Step 1: Merge personas
- **`scripts/comprehensive_post_processor.py`** - Step 3: Post-processing
- **`scripts/final_production_verification.py`** - Verify standalone status

## Documentation

- **`README.md`** - Complete documentation (beginner to expert)
- **`docs/`** - Additional documentation (deployment, workflow, etc.)

## Output

- **`output/full_run/`** - Production output (34 Excel files)
- **`output/dry_run/`** - Test output (5 students)

---

**Note**: Root directory contains only essential files. All additional documentation is in `docs/` folder.