first working version

exam_system/docs/folder-structure.md

@@ -0,0 +1,112 @@
+# Reorganized Folder Structure
+
+## New Hierarchy
+
+### Input Folder (Exams by Subject and Month)
+```
+data/input/
+├── python/
+│   ├── 2025-10/
+│   │   ├── python-easy-v1.json
+│   │   ├── python-intermediate-v1.json
+│   │   └── python-advanced-v1.json
+│   └── 2025-11/
+│       └── python-lists-quiz.json
+├── django/
+│   └── 2025-10/
+│       ├── django-basics-v1.json
+│       └── django-models-v1.json
+└── angular/
+    └── 2025-10/
+        └── angular-components-v1.json
+```
+
+### Output Folder (Results by Username, Subject, Month)
+```
+data/output/
+├── testuser/
+│   ├── python/
+│   │   └── 2025-10/
+│   │       ├── python-easy-v1_attempt-001.json
+│   │       ├── python-easy-v1_attempt-002.json
+│   │       └── python-intermediate-v1_attempt-001.json
+│   └── django/
+│       └── 2025-10/
+│           └── django-basics-v1_attempt-001.json
+└── john/
+    └── python/
+        └── 2025-10/
+            └── python-easy-v1_attempt-001.json
+```
+
+### Attempts Folder (by Username, Subject, Month)
+```
+data/attempts/
+├── testuser/
+│   ├── python/
+│   │   └── 2025-10/
+│   │       ├── python-easy-v1/
+│   │       │   └── attempt-001.json
+│   │       └── python-intermediate-v1/
+│   │           └── attempt-001.json
+│   └── django/
+│       └── 2025-10/
+│           └── django-basics-v1/
+│               └── attempt-001.json
+└── john/
+    └── python/
+        └── 2025-10/
+            └── python-easy-v1/
+                └── attempt-001.json
+```
+
+## Manifest Format Update
+
+```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": {}
+}
+```
+
+## Path Patterns
+
+### Input
+- Pattern: `input/{subject}/{YYYY-MM}/{examId}.json`
+- Example: `input/python/2025-10/python-easy-v1.json`
+
+### Attempts
+- Pattern: `attempts/{username}/{subject}/{YYYY-MM}/{examId}/{attemptId}.json`
+- Example: `attempts/testuser/python/2025-10/python-easy-v1/attempt-20251020-143022.json`
+
+### Output
+- Pattern: `output/{username}/{subject}/{YYYY-MM}/{examId}_{attemptId}.json`
+- Example: `output/testuser/python/2025-10/python-easy-v1_attempt-20251020-143022.json`
+
+## Benefits
+
+1. **Better Organization**: Easy to find exams by subject and time
+2. **Scalability**: Can handle thousands of exams
+3. **User Separation**: Each user's data isolated
+4. **Time-based Filtering**: Easy to archive old exams
+5. **Subject-based Filtering**: Easy to find all exams for a subject
+6. **Cleaner Structure**: Hierarchical instead of flat
+