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)

{
  "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

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

Example:

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:

data/input/python/2025-11/python-advanced-quiz.json

Step 3: Update Manifest

Add entry with the hierarchical path:

{
  "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

# 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

# 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

# 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! 🚀