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: datetimeupdated_at: datetimetags: string[] (searchable keywords)privacy: enum ('private', 'friends', 'public')pinned: boolean (pinned to top of user's notes)archived: boolean (soft delete)word_count: integerreading_time_minutes: integer (estimated)
2. NOTE_VERSION#
Tracks note revision history.
Properties:
id: UUIDnote_id: UUID (parent note)content: string (content snapshot)version_number: integercreated_at: datetimecreated_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: UUIDuser_id: UUID (owner)name: string (collection name)description: string (optional)created_at: datetimeupdated_at: datetimeprivacy: enum ('private', 'friends', 'public')color: string (hex color for UI)icon: string (icon identifier)
4. NOTE_HIGHLIGHT#
Represents highlighted text from content.
Properties:
id: UUIDuser_id: UUIDcontent_id: UUID (source content)content_type: enum ('lecture', 'practice', 'concept')highlighted_text: stringcontext_before: string (surrounding text)context_after: string (surrounding text)position_start: integer (character offset)position_end: integercolor: string (highlight color)created_at: datetimenote_id: UUID (optional - associated note)
Relationships#
Note Organization#
(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#
(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#
(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:
{
"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:
{
"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 typecurriculum_id: Filter by curriculumcollection_id: Filter by collectionsearch: Full-text search querypinned: 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:
{
"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:
{
"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:
{
"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:
{
"name": "Meditation Insights",
"description": "Notes from meditation practices",
"privacy": "private",
"color": "#4A90E2",
"icon": "lotus"
}
GET /v1/notes/collections#
List user's collections.
Response:
{
"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:
{
"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 contentcontent_type: Filter by typecolor: 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 tagsdate_from: Filter by date rangedate_to: Filter by date rangecontent_types: Filter by content typeslimit,offset: Pagination
GET /v1/notes/tags#
Get all user's tags with usage counts.
Response:
{
"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:
{
"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
titleandcontent - 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