# Scholar Notes Data Model

## Overview

The scholar notes system enables users to capture insights, reflections, and
learning notes while engaging with platform content. Notes support rich text,
tagging, search, organization, and can be linked to specific content items.

## Neo4j Schema Design

### Node Types

#### 1. NOTE

Represents a user's note or reflection.

**Properties:**

- `id`: UUID (unique identifier)
- `user_id`: UUID (owner of the note)
- `title`: string (note title/heading)
- `content`: string (note body in markdown format)
- `content_id`: UUID (optional - linked content item)
- `content_type`: enum ('lecture', 'practice', 'concept', 'curriculum',
  'lesson', null)
- `curriculum_id`: UUID (optional - if note is within a curriculum context)
- `lesson_id`: UUID (optional - if note is within a lesson context)
- `created_at`: datetime
- `updated_at`: datetime
- `tags`: string[] (searchable keywords)
- `privacy`: enum ('private', 'friends', 'public')
- `pinned`: boolean (pinned to top of user's notes)
- `archived`: boolean (soft delete)
- `word_count`: integer
- `reading_time_minutes`: integer (estimated)

#### 2. NOTE_VERSION

Tracks note revision history.

**Properties:**

- `id`: UUID
- `note_id`: UUID (parent note)
- `content`: string (content snapshot)
- `version_number`: integer
- `created_at`: datetime
- `created_by`: UUID (user who made the edit)
- `change_summary`: string (optional description of changes)

#### 3. NOTE_COLLECTION

Organizes notes into user-defined collections.

**Properties:**

- `id`: UUID
- `user_id`: UUID (owner)
- `name`: string (collection name)
- `description`: string (optional)
- `created_at`: datetime
- `updated_at`: datetime
- `privacy`: enum ('private', 'friends', 'public')
- `color`: string (hex color for UI)
- `icon`: string (icon identifier)

#### 4. NOTE_HIGHLIGHT

Represents highlighted text from content.

**Properties:**

- `id`: UUID
- `user_id`: UUID
- `content_id`: UUID (source content)
- `content_type`: enum ('lecture', 'practice', 'concept')
- `highlighted_text`: string
- `context_before`: string (surrounding text)
- `context_after`: string (surrounding text)
- `position_start`: integer (character offset)
- `position_end`: integer
- `color`: string (highlight color)
- `created_at`: datetime
- `note_id`: UUID (optional - associated note)

### Relationships

#### Note Organization

```cypher
(user:USER)-[:CREATED]->(note:NOTE)
(note:NOTE)-[:IN_COLLECTION]->(collection:NOTE_COLLECTION)
(note:NOTE)-[:HAS_VERSION]->(version:NOTE_VERSION)
(note:NOTE)-[:REFERENCES]->(content:LECTURE|PRACTICE|CONCEPT)
(note:NOTE)-[:RELATED_TO_CURRICULUM]->(curriculum:CURRICULUM)
(note:NOTE)-[:RELATED_TO_LESSON]->(lesson:LESSON)
```

#### Highlights

```cypher
(user:USER)-[:HIGHLIGHTED]->(highlight:NOTE_HIGHLIGHT)
(highlight:NOTE_HIGHLIGHT)-[:FROM_CONTENT]->(content:LECTURE|PRACTICE|CONCEPT)
(highlight:NOTE_HIGHLIGHT)-[:ATTACHED_TO_NOTE]->(note:NOTE)
```

#### Social Features

```cypher
(user:USER)-[:LIKES]->(note:NOTE)
(user:USER)-[:SHARED]->(note:NOTE)-[:WITH]->(friend:USER)
(note:NOTE)-[:REPLIES_TO]->(parent_note:NOTE)
```

## API Endpoints

### Note Management

#### POST /v1/notes

Create a new note.

**Request Body:**

```json
{
  "title": "Key Insights from Buddhist Meditation",
  "content": "## Main Points\n\n- Breath awareness is foundational\n- Practice consistency matters more than duration",
  "content_id": "lecture-uuid",
  "content_type": "lecture",
  "curriculum_id": "curr-uuid",
  "lesson_id": "lesson-uuid",
  "tags": ["meditation", "breath", "practice"],
  "privacy": "private"
}
```

**Response:**

```json
{
  "note": {
    "id": "uuid",
    "user_id": "uuid",
    "title": "Key Insights from Buddhist Meditation",
    "content": "## Main Points\n\n- Breath awareness...",
    "content_id": "lecture-uuid",
    "content_type": "lecture",
    "tags": ["meditation", "breath", "practice"],
    "created_at": "2025-10-16T20:00:00Z",
    "updated_at": "2025-10-16T20:00:00Z",
    "privacy": "private",
    "pinned": false,
    "archived": false,
    "word_count": 15,
    "reading_time_minutes": 1
  }
}
```

#### GET /v1/notes

List user's notes with filtering and search.

**Query Parameters:**

- `tags`: Filter by tags (comma-separated)
- `content_type`: Filter by content type
- `curriculum_id`: Filter by curriculum
- `collection_id`: Filter by collection
- `search`: Full-text search query
- `pinned`: Filter pinned notes (true/false)
- `archived`: Include archived notes (true/false)
- `sort`: Sort by (created_at, updated_at, title, word_count)
- `order`: Sort order (asc, desc)
- `limit`: Pagination limit (default: 20)
- `offset`: Pagination offset (default: 0)

**Response:**

```json
{
  "notes": [
    {
      "id": "uuid",
      "title": "Key Insights",
      "content": "...",
      "tags": ["meditation"],
      "created_at": "2025-10-16T20:00:00Z",
      "word_count": 150,
      "content_reference": {
        "id": "lecture-uuid",
        "type": "lecture",
        "title": "Introduction to Breath Meditation"
      }
    }
  ],
  "total": 45,
  "limit": 20,
  "offset": 0
}
```

#### GET /v1/notes/:id

Get single note with full details.

**Response:**

```json
{
  "note": {
    "id": "uuid",
    "user_id": "uuid",
    "title": "Key Insights",
    "content": "Full markdown content...",
    "content_id": "lecture-uuid",
    "content_type": "lecture",
    "curriculum_id": "curr-uuid",
    "lesson_id": "lesson-uuid",
    "tags": ["meditation", "breath"],
    "privacy": "private",
    "pinned": false,
    "archived": false,
    "word_count": 250,
    "reading_time_minutes": 2,
    "created_at": "2025-10-15T10:00:00Z",
    "updated_at": "2025-10-16T15:00:00Z",
    "version_count": 3,
    "collections": [
      {
        "id": "coll-uuid",
        "name": "Meditation Notes"
      }
    ],
    "content_reference": {
      "id": "lecture-uuid",
      "type": "lecture",
      "title": "Introduction to Breath Meditation"
    }
  }
}
```

#### PUT /v1/notes/:id

Update a note.

**Request Body:**

```json
{
  "title": "Updated Title",
  "content": "Updated content...",
  "tags": ["new", "tags"],
  "pinned": true,
  "privacy": "friends"
}
```

#### DELETE /v1/notes/:id

Archive/delete a note.

**Query Parameters:**

- `permanent`: Permanently delete (true/false, default: false)

### Note Collections

#### POST /v1/notes/collections

Create a new collection.

**Request Body:**

```json
{
  "name": "Meditation Insights",
  "description": "Notes from meditation practices",
  "privacy": "private",
  "color": "#4A90E2",
  "icon": "lotus"
}
```

#### GET /v1/notes/collections

List user's collections.

**Response:**

```json
{
  "collections": [
    {
      "id": "uuid",
      "name": "Meditation Insights",
      "description": "...",
      "note_count": 25,
      "created_at": "2025-10-01T00:00:00Z",
      "color": "#4A90E2",
      "icon": "lotus"
    }
  ]
}
```

#### POST /v1/notes/:note_id/collections/:collection_id

Add note to collection.

#### DELETE /v1/notes/:note_id/collections/:collection_id

Remove note from collection.

### Highlights

#### POST /v1/highlights

Create a highlight.

**Request Body:**

```json
{
  "content_id": "lecture-uuid",
  "content_type": "lecture",
  "highlighted_text": "The breath is the anchor of awareness",
  "position_start": 150,
  "position_end": 189,
  "color": "#FFEB3B",
  "note_id": "uuid"
}
```

#### GET /v1/highlights

List user's highlights.

**Query Parameters:**

- `content_id`: Filter by content
- `content_type`: Filter by type
- `color`: Filter by highlight color

#### DELETE /v1/highlights/:id

Remove a highlight.

### Search and Discovery

#### GET /v1/notes/search

Advanced search with full-text and filters.

**Query Parameters:**

- `q`: Search query (full-text)
- `tags`: Filter by tags
- `date_from`: Filter by date range
- `date_to`: Filter by date range
- `content_types`: Filter by content types
- `limit`, `offset`: Pagination

#### GET /v1/notes/tags

Get all user's tags with usage counts.

**Response:**

```json
{
  "tags": [
    {
      "tag": "meditation",
      "count": 45
    },
    {
      "tag": "breath",
      "count": 32
    }
  ]
}
```

#### GET /v1/notes/recent

Get recently accessed/updated notes.

**Query Parameters:**

- `limit`: Number of recent notes (default: 10)

### Version History

#### GET /v1/notes/:id/versions

Get note version history.

**Response:**

```json
{
  "versions": [
    {
      "id": "uuid",
      "version_number": 3,
      "created_at": "2025-10-16T15:00:00Z",
      "created_by": "uuid",
      "change_summary": "Added meditation technique details"
    }
  ]
}
```

#### GET /v1/notes/:id/versions/:version_number

Get specific version content.

## Use Cases

### 1. Active Learning Notes

Users take notes while watching lectures or reading content, with automatic
linking to source material.

### 2. Reflection Journals

Post-practice reflections and insights captured in markdown with rich
formatting.

### 3. Highlight and Annotate

Users highlight important passages and attach notes explaining why it resonates.

### 4. Organized Knowledge Base

Collections help users organize notes by topic, curriculum, or personal
categorization.

### 5. Search and Rediscovery

Full-text search enables finding past insights when needed.

### 6. Learning Progress Tracking

Notes linked to curricula help track learning journey and retention.

### 7. Social Learning

Users can share selected notes with friends for collaborative learning.

## Implementation Notes

### Performance Optimization

- Index on `user_id`, `created_at`, `updated_at`, `tags`
- Full-text search index on `title` and `content`
- Cache frequently accessed notes in Redis
- Paginate results for large note collections

### Access Control

- Private notes: Only owner can access
- Friends: Shared with approved connections
- Public: Discoverable by all users
- Collection privacy inherits to contained notes

### Data Validation

- Content max length: 50,000 characters
- Title max length: 200 characters
- Tags max: 20 per note
- Tag length: 2-30 characters
- Word count and reading time calculated server-side

### Search Features

- Full-text search using Neo4j full-text indexes
- Tag autocomplete from user's existing tags
- Search within collections
- Filter by date ranges, content types, curricula

### Version Control

- Auto-save versions on significant edits (>100 char change)
- Keep last 10 versions per note
- Version diff view in UI
- Restore to previous version capability
