# Structured Curricula Data Model

## Overview

The curricula system provides structured learning paths that guide users through
curated content sequences across traditions, practices, and concepts.

## Neo4j Schema Design

### Node Types

#### 1. CURRICULUM

Represents a complete learning path.

**Properties:**

- `id`: UUID (unique identifier)
- `title`: string (e.g., "Introduction to Buddhist Meditation")
- `description`: string (detailed overview)
- `tradition`: string (Buddhism, Stoicism, etc.)
- `level`: enum ('beginner', 'intermediate', 'advanced')
- `estimated_duration_minutes`: integer
- `created_at`: datetime
- `updated_at`: datetime
- `created_by`: string (curator ID)
- `status`: enum ('draft', 'published', 'archived')
- `tags`: string[] (searchable keywords)
- `language`: string (ISO 639-1 code)

#### 2. MODULE

A major section within a curriculum.

**Properties:**

- `id`: UUID
- `curriculum_id`: UUID (parent curriculum)
- `title`: string
- `description`: string
- `order_index`: integer (sequential position)
- `estimated_duration_minutes`: integer
- `created_at`: datetime
- `updated_at`: datetime

#### 3. LESSON

An individual unit within a module.

**Properties:**

- `id`: UUID
- `module_id`: UUID (parent module)
- `title`: string
- `description`: string
- `order_index`: integer
- `estimated_duration_minutes`: integer
- `lesson_type`: enum ('lecture', 'practice', 'reflection', 'assessment')
- `created_at`: datetime
- `updated_at`: datetime

#### 4. USER_CURRICULUM_PROGRESS

Tracks user's progress through a curriculum.

**Properties:**

- `id`: UUID
- `user_id`: UUID
- `curriculum_id`: UUID
- `status`: enum ('not_started', 'in_progress', 'completed', 'paused')
- `started_at`: datetime
- `last_accessed_at`: datetime
- `completed_at`: datetime (nullable)
- `completion_percentage`: float (0-100)
- `current_module_id`: UUID (nullable)
- `current_lesson_id`: UUID (nullable)

#### 5. USER_LESSON_COMPLETION

Tracks completion of individual lessons.

**Properties:**

- `id`: UUID
- `user_id`: UUID
- `lesson_id`: UUID
- `completed_at`: datetime
- `time_spent_minutes`: integer
- `notes`: string (optional user notes)
- `rating`: integer (1-5, optional)

### Relationships

#### Curriculum Structure

```cypher
(curriculum:CURRICULUM)-[:HAS_MODULE {order: 1}]->(module:MODULE)
(module:MODULE)-[:HAS_LESSON {order: 1}]->(lesson:LESSON)
(lesson:LESSON)-[:INCLUDES_CONTENT]->(content:LECTURE|PRACTICE|CONCEPT)
```

#### Prerequisites

```cypher
(module:MODULE)-[:REQUIRES]->(prerequisite_module:MODULE)
(lesson:LESSON)-[:REQUIRES]->(prerequisite_lesson:LESSON)
```

#### User Progress

```cypher
(user:USER)-[:ENROLLED_IN]->(curriculum:CURRICULUM)
(user:USER)-[:HAS_PROGRESS]->(progress:USER_CURRICULUM_PROGRESS)
(user:USER)-[:COMPLETED]->(lesson:LESSON)
```

#### Content Association

```cypher
(lesson:LESSON)-[:INCLUDES_CONTENT]->(lecture:LECTURE)
(lesson:LESSON)-[:INCLUDES_CONTENT]->(practice:PRACTICE)
(lesson:LESSON)-[:INCLUDES_CONTENT]->(concept:CONCEPT)
```

## API Endpoints

### Curriculum Management

#### GET /v1/curricula

List all curricula with filtering.

**Query Parameters:**

- `tradition`: Filter by tradition
- `level`: Filter by difficulty level
- `status`: Filter by status
- `tags`: Filter by tags (comma-separated)
- `limit`: Pagination limit (default: 20)
- `offset`: Pagination offset (default: 0)

**Response:**

```json
{
  "curricula": [
    {
      "id": "uuid",
      "title": "Introduction to Buddhist Meditation",
      "description": "...",
      "tradition": "Buddhism",
      "level": "beginner",
      "estimated_duration_minutes": 480,
      "module_count": 6,
      "lesson_count": 24,
      "status": "published",
      "tags": ["meditation", "mindfulness", "basics"]
    }
  ],
  "total": 15,
  "limit": 20,
  "offset": 0
}
```

#### GET /v1/curricula/:id

Get detailed curriculum with modules and lessons.

**Response:**

```json
{
  "curriculum": {
    "id": "uuid",
    "title": "Introduction to Buddhist Meditation",
    "description": "...",
    "tradition": "Buddhism",
    "level": "beginner",
    "estimated_duration_minutes": 480,
    "modules": [
      {
        "id": "uuid",
        "title": "Module 1: Foundations",
        "description": "...",
        "order_index": 1,
        "estimated_duration_minutes": 80,
        "lessons": [
          {
            "id": "uuid",
            "title": "What is Meditation?",
            "description": "...",
            "order_index": 1,
            "lesson_type": "lecture",
            "estimated_duration_minutes": 20,
            "content_ids": ["lecture-uuid-1", "concept-uuid-1"]
          }
        ]
      }
    ]
  }
}
```

#### POST /v1/curricula

Create a new curriculum (curator only).

**Request Body:**

```json
{
  "title": "Introduction to Buddhist Meditation",
  "description": "...",
  "tradition": "Buddhism",
  "level": "beginner",
  "estimated_duration_minutes": 480,
  "tags": ["meditation", "mindfulness"],
  "modules": [
    {
      "title": "Foundations",
      "description": "...",
      "order_index": 1,
      "lessons": [
        {
          "title": "What is Meditation?",
          "description": "...",
          "order_index": 1,
          "lesson_type": "lecture",
          "content_ids": ["lecture-uuid-1"]
        }
      ]
    }
  ]
}
```

#### PUT /v1/curricula/:id

Update curriculum (curator only).

#### DELETE /v1/curricula/:id

Archive curriculum (curator only).

### User Progress

#### POST /v1/curricula/:id/enroll

Enroll user in curriculum.

**Response:**

```json
{
  "enrollment": {
    "id": "uuid",
    "curriculum_id": "uuid",
    "user_id": "uuid",
    "status": "not_started",
    "enrolled_at": "2025-10-16T20:00:00Z"
  }
}
```

#### GET /v1/curricula/:id/progress

Get user's progress in curriculum.

**Response:**

```json
{
  "progress": {
    "id": "uuid",
    "curriculum_id": "uuid",
    "user_id": "uuid",
    "status": "in_progress",
    "started_at": "2025-10-15T10:00:00Z",
    "last_accessed_at": "2025-10-16T15:00:00Z",
    "completion_percentage": 45.5,
    "current_module": {
      "id": "uuid",
      "title": "Module 3: Breathing Techniques"
    },
    "current_lesson": {
      "id": "uuid",
      "title": "Anapanasati Practice"
    },
    "completed_lessons": 11,
    "total_lessons": 24
  }
}
```

#### POST /v1/curricula/:curriculum_id/lessons/:lesson_id/complete

Mark lesson as completed.

**Request Body:**

```json
{
  "time_spent_minutes": 25,
  "notes": "Found this very helpful for understanding breath awareness",
  "rating": 5
}
```

#### GET /v1/users/:user_id/curricula

Get all curricula for user with progress.

**Response:**

```json
{
  "enrollments": [
    {
      "curriculum": {
        "id": "uuid",
        "title": "Introduction to Buddhist Meditation"
      },
      "progress": {
        "status": "in_progress",
        "completion_percentage": 45.5,
        "started_at": "2025-10-15T10:00:00Z"
      }
    }
  ]
}
```

## Use Cases

### 1. Guided Learning Paths

Users follow structured sequences through topics, building knowledge
progressively.

### 2. Progress Tracking

System tracks completion, time spent, and user notes for each lesson.

### 3. Personalization

Curricula can be customized based on user preferences, tradition interests, and
skill level.

### 4. Prerequisites

Ensure users complete foundational content before advanced topics.

### 5. Analytics

Track curriculum effectiveness, completion rates, and user engagement.

## Implementation Notes

### Performance Optimization

- Index on `curriculum.status`, `curriculum.tradition`, `curriculum.level`
- Index on `user_id` in progress tracking nodes
- Cache popular curricula in Redis

### Access Control

- Public: List and view published curricula
- Authenticated: Enroll, track progress, complete lessons
- Curator: Create, edit, publish, archive curricula

### Data Validation

- Order indices must be sequential within modules/lessons
- Estimated durations must be positive integers
- Status transitions must follow valid state machine
- Content references must exist in knowledge graph
