lnet_tutor/exam_system/NEW_FOLDER_STRUCTURE.md

# ✅ New Hierarchical Folder Structure Implemented

## Overview

The exam system now uses an organized hierarchical folder structure instead of flat files.

## Folder Organization

### Input Folder (Exams by Subject → Month)

```
data/input/
├── python/
│   ├── 2025-10/
│   │   └── python-easy-v1.json
│   ├── 2025-11/
│   └── 2025-12/
├── django/
│   └── 2025-10/
└── angular/
    └── 2025-10/
```

**Pattern:** `data/input/{subject}/{YYYY-MM}/{examId}.json`

### Output Folder (Results by Username → Subject → Month)

```
data/output/
├── testuser/
│   ├── python/
│   │   └── 2025-10/
│   │       ├── python-easy-v1_attempt-20251020-143022.json
│   │       └── python-easy-v1_attempt-20251020-150530.json
│   └── django/
│       └── 2025-10/
├── john/
│   └── python/
│       └── 2025-10/
└── guest_default/
    └── python/
        └── 2025-10/
```

**Pattern:** `data/output/{username}/{subject}/{YYYY-MM}/{examId}_{attemptId}.json`

### Attempts Folder (by Username → Subject → Month → Exam)

```
data/attempts/
├── testuser/
│   ├── python/
│   │   └── 2025-10/
│   │       ├── python-easy-v1/
│   │       │   └── attempt-20251020-143022.json
│   │       └── python-intermediate-v1/
│   │           └── attempt-20251020-150530.json
│   └── django/
│       └── 2025-10/
└── john/
    └── python/
        └── 2025-10/
```

**Pattern:** `data/attempts/{username}/{subject}/{YYYY-MM}/{examId}/{attemptId}.json`

## Manifest Format (Updated to v2.0.0)

```json
{
  "version": "2.0.0",
  "exams": [
    {
      "examId": "python-easy-v1",
      "subject": "python",
      "month": "2025-10",
      "path": "python/2025-10/python-easy-v1.json",
      "published": true,
      "version": "1.0.0"
    },
    {
      "examId": "django-basics-v1",
      "subject": "django",
      "month": "2025-10",
      "path": "django/2025-10/django-basics-v1.json",
      "published": true,
      "version": "1.0.0"
    }
  ],
  "users": {}
}
```

## How to Add New Exams

### Step 1: Create Subject and Month Folders

```bash
mkdir -p data/input/{subject}/{YYYY-MM}
```

Example:
```bash
mkdir -p data/input/python/2025-11
mkdir -p data/input/django/2025-10
mkdir -p data/input/angular/2025-10
```

### Step 2: Add Exam JSON

Create your exam file in the appropriate folder:
```bash
data/input/python/2025-11/python-advanced-quiz.json
```

### Step 3: Update Manifest

Add entry with the hierarchical path:
```json
{
  "examId": "python-advanced-quiz",
  "subject": "python",
  "month": "2025-11",
  "path": "python/2025-11/python-advanced-quiz.json",
  "published": true,
  "version": "1.0.0"
}
```

## Benefits

### 1. Better Organization
- Find all Python exams: `data/input/python/`
- Find October exams: `data/input/*/2025-10/`
- Find user's Python results: `data/output/testuser/python/`

### 2. Scalability
- Can handle unlimited exams
- No file name conflicts
- Easy to archive old months
- Clear separation by subject

### 3. User Data Isolation
- Each user has own folder
- Easy to export user's data
- Clear ownership
- Simple backup per user

### 4. Time-based Management
- Archive old months
- Track exam creation timeline
- Seasonal exam organization
- Easy cleanup

## Backward Compatibility

The storage system supports both structures:
- ✓ New: `python/2025-10/exam.json`
- ✓ Old: `exam.json` (flat)

If an exam isn't found in the hierarchical path, it falls back to flat structure.

## Migration Guide

### Migrate Existing Exam

```bash
# Old location
data/input/my-exam.json

# New location (choose subject and month)
data/input/python/2025-10/my-exam.json

# Update manifest path
"path": "python/2025-10/my-exam.json"
```

### Example Commands

```bash
# Create October 2025 Python exams
mkdir -p data/input/python/2025-10
mv data/input/python-*.json data/input/python/2025-10/

# Create November 2025 Django exams
mkdir -p data/input/django/2025-11
# Add your exams there

# List all Python exams
find data/input/python -name "*.json"

# List all October exams across subjects
find data/input/*/2025-10 -name "*.json"
```

## Output Organization Examples

### After Taking Exams

When testuser takes python-easy-v1:
```
data/output/testuser/python/2025-10/python-easy-v1_attempt-20251020-143022.json
```

When john takes the same exam:
```
data/output/john/python/2025-10/python-easy-v1_attempt-20251020-150000.json
```

### View User's Results

```bash
# All of testuser's results
find data/output/testuser -name "*.json"

# testuser's Python results
find data/output/testuser/python -name "*.json"

# All October results for testuser
find data/output/testuser/*/2025-10 -name "*.json"
```

## Current Status

✅ **Implemented:**
- Hierarchical input structure (subject/month)
- Hierarchical output structure (username/subject/month)
- Hierarchical attempts structure (username/subject/month/exam)
- Updated manifest format (v2.0.0)
- Backward compatibility with flat structure
- Automatic folder creation

✅ **Current Exam:**
- Location: `data/input/python/2025-10/python-easy-v1.json`
- Manifest updated with new path
- System working with new structure

✅ **Next Outputs Will Be:**
- Pattern: `data/output/{username}/python/2025-10/python-easy-v1_attempt-XXXXXX.json`
- Organized by username first
- Then by subject
- Then by month

## Ready to Use!

The system is fully operational with the new structure. 

**Refresh http://localhost** and take an exam - the output will be created in the new hierarchical folder automatically! 🚀