Verse Notes

Overview

The notes feature allows you to add personal annotations, reflections, and insights to any verse in the Bhagavad Gita. Notes help you remember your thoughts and deepen your understanding of the teachings.

How Notes Work

Personal Annotations

Add your own thoughts and reflections to any verse

Easy Editing

Update your notes anytime as your understanding grows

One Note Per Verse

Each verse can have one note that you can edit or replace

Retrieve Anytime

Fetch specific notes or browse all your notes at once

API Endpoint

The notes API is available at /api/notes and supports three HTTP methods:

Get Notes

Retrieve a specific note or all notes for the authenticated user. Endpoint: GET /api/notes Authentication: Required (Clerk) Query Parameters (Optional):

chapter: Chapter number to get a specific note
verse: Verse number to get a specific note

Example 1: Get Specific Note

GET /api/notes?chapter=2&verse=47

Response:

{
  "id": "uuid",
  "user_id": "user_123",
  "chapter": 2,
  "verse": 47,
  "note_text": "This verse reminds me to focus on the process, not the outcome. Applied this at work today.",
  "created_at": "2024-03-10T12:00:00Z",
  "updated_at": "2024-03-10T14:30:00Z"
}

Returns null if no note exists for that verse. Example 2: Get All Notes

GET /api/notes

Response:

[
  {
    "id": "uuid",
    "user_id": "user_123",
    "chapter": 2,
    "verse": 47,
    "note_text": "Focus on duty without attachment to results",
    "created_at": "2024-03-10T12:00:00Z",
    "updated_at": "2024-03-10T12:00:00Z"
  },
  {
    "id": "uuid",
    "user_id": "user_123",
    "chapter": 18,
    "verse": 66,
    "note_text": "Complete surrender - let go of all anxieties",
    "created_at": "2024-03-09T10:00:00Z",
    "updated_at": "2024-03-09T10:00:00Z"
  }
]

Notes are sorted by most recently updated first.

Create or Update Note

Add a new note or update an existing one for a verse. Endpoint: POST /api/notes Authentication: Required (Clerk) Request Body:

{
  "chapter": 2,
  "verse": 47,
  "note_text": "This verse teaches detachment from results. I'm practicing this in my daily work."
}

Validation:

chapter: Integer between 1-18 (required)
verse: Integer, valid for the specified chapter (required)
note_text: String, max 10,000 characters (required)
Whitespace is trimmed automatically

Success Response (200):

{
  "id": "uuid",
  "user_id": "user_123",
  "chapter": 2,
  "verse": 47,
  "note_text": "This verse teaches detachment from results. I'm practicing this in my daily work.",
  "created_at": "2024-03-10T12:00:00Z",
  "updated_at": "2024-03-10T12:00:00Z"
}

Upsert Behavior:

If no note exists for this verse, a new one is created
If a note already exists, it’s updated with the new text
The updated_at timestamp is automatically refreshed

Delete Note

Remove a note from a specific verse. Endpoint: DELETE /api/notes?chapter=2&verse=47 Authentication: Required (Clerk) Query Parameters:

chapter: Chapter number (required)
verse: Verse number (required)

Success Response (200):

{
  "success": true
}

Data Storage

Notes are stored in the verse_notes table in Supabase:

Column	Type	Description
`id`	UUID	Primary key
`user_id`	String	Clerk user identifier
`chapter`	Integer	Chapter number (1-18)
`verse`	Integer	Verse number
`note_text`	Text	User’s note content (max 10,000 chars)
`created_at`	Timestamp	When note was first created
`updated_at`	Timestamp	When note was last modified

Unique Constraint: The combination of user_id, chapter, and verse is unique, ensuring one note per verse per user.

Implementation Details

The notes system is implemented in /app/api/notes/route.ts:

Upsert Logic

POST endpoint uses upsert to create or update seamlessly

Flexible Retrieval

GET endpoint works for both single notes and all notes

Timestamp Tracking

Separate created_at and updated_at for version history

Text Length

Generous 10,000 character limit for detailed reflections

User Interface

The notes feature integrates throughout the GitaChat interface:

Add Note: Click the notes icon next to any verse
Edit Note: Existing notes can be modified anytime
View All Notes: Browse all your notes in one place
Delete Note: Remove notes you no longer need
Rich Text: Notes display with proper formatting

Use Cases

Personal Reflections

Record how a verse applies to your life

Study Journal

Document insights from your study sessions

Action Items

Note specific practices to implement

Questions

Write down questions for further exploration

Cross-References

Link verses to related teachings or scriptures

Progress Tracking

Document your spiritual growth over time

Best Practices

Note-Taking Tips

Be Specific: Reference specific life situations
Update Regularly: Revise notes as understanding deepens
Keep It Personal: Focus on what resonates with you
Use Clear Language: Write for your future self
Combine with Bookmarks: Bookmark verses with important notes

Character Limits

Field	Maximum Length	Purpose
`note_text`	10,000 characters	Allow detailed reflections
Other text fields	5,000 characters	Bookmarks and commentary

The generous 10,000 character limit allows for comprehensive notes while preventing database abuse.

Error Handling

Common error scenarios:

Error	Status	Description
Unauthorized	401	User not logged in
Missing required fields	400	chapter, verse, or note_text missing
Invalid chapter/verse	400	Chapter or verse out of valid range
Note text too long	400	Exceeds 10,000 character limit
Database not configured	503	Supabase connection unavailable
Failed to save/delete	500	Server error occurred

Validation Rules

The API validates all input before processing:

Authentication: User must be logged in via Clerk
Required Fields: chapter, verse, and note_text are mandatory for POST
Chapter Range: Must be between 1 and 18
Verse Range: Must be valid for the specified chapter (varies by chapter)
Text Length: note_text trimmed and must not exceed 10,000 characters
Data Types: chapter and verse must be integers

Privacy

Your Notes are Private

Only you can see your notes
Notes are tied to your Clerk user ID
No other users can access your personal reflections
Data is stored securely in Supabase with proper authentication

Integration with Other Features

Notes work seamlessly with other GitaChat features:

Bookmarks: Add notes to bookmarked verses for enhanced reference
History: Review notes on verses you’ve searched before
Daily Verse: Add notes to your daily verse for ongoing reflection
Search: Find verses, then add notes with your insights

Get Started

Core Features

User Features

Integrations

Overview

How Notes Work

Personal Annotations

Easy Editing

One Note Per Verse

Retrieve Anytime

API Endpoint

Get Notes

Create or Update Note

Delete Note

Data Storage

Implementation Details

Upsert Logic

Flexible Retrieval

Timestamp Tracking

Text Length

User Interface

Use Cases

Personal Reflections

Study Journal

Action Items

Questions

Cross-References

Progress Tracking

Best Practices

Note-Taking Tips

Character Limits

Error Handling

Validation Rules

Privacy

Your Notes are Private

Integration with Other Features

Build docs developers (and LLMs) love

Get Started

Core Features

User Features

Integrations

​Overview

​How Notes Work

Personal Annotations

Easy Editing

One Note Per Verse

Retrieve Anytime

​API Endpoint

​Get Notes

​Create or Update Note

​Delete Note

​Data Storage

​Implementation Details

Upsert Logic

Flexible Retrieval

Timestamp Tracking

Text Length

​User Interface

​Use Cases

Personal Reflections

Study Journal

Action Items

Questions

Cross-References

Progress Tracking

​Best Practices

Note-Taking Tips

​Character Limits

​Error Handling

​Validation Rules

​Privacy

Your Notes are Private

​Integration with Other Features

Build docs developers (and LLMs) love

Overview

How Notes Work

API Endpoint

Get Notes

Create or Update Note

Delete Note

Data Storage

Implementation Details

User Interface

Use Cases

Best Practices

Character Limits

Error Handling

Validation Rules

Privacy

Integration with Other Features