quicknotes/specs/notes.md

Notes Specification

Overview

The Notes module is a core component of QuickNotes that allows users to create, edit, view, and link notes. It supports a wiki-style linking system and provides a graph visualization of note connections.

Data Model

Note

The Note entity has the following attributes:

Field	Type	Description
ID	string	Unique identifier for the note (UUID)
Title	string	Title of the note
Content	string	Content of the note in Markdown format
CreatedAt	timestamp	When the note was created
UpdatedAt	timestamp	When the note was last updated
LinksTo	[]*Note	Notes that this note links to
LinkedBy	[]*Note	Notes that link to this note

NoteLink

The NoteLink entity represents a connection between two notes:

Field	Type	Description
SourceNoteID	string	ID of the source note
TargetNoteID	string	ID of the target note
CreatedAt	timestamp	When the link was created

Features

Note Management

1. Create Note: Users can create new notes with a title and content
2. Edit Note: Users can edit existing notes
3. Delete Note: Users can delete notes
4. View Note: Users can view notes with rendered Markdown content
5. List Notes: Users can view a list of all notes

Note Linking

The application now supports an enhanced linking syntax that allows users to reference items from various domains using the following format:

[[<domain>:::<uuid>]]

Where:

• <domain> is one of the following keywords: note, feed, entry, doc, or post.
• <uuid> is the unique identifier of the target item.

For example, to link to a note, a user might write:

[[note:::123e4567-e89b-12d3-a456-426614174000]]

This link will be processed and rendered as a clickable hyperlink that navigates to the corresponding detail page.

Backend Implementation Changes

1. Link Extraction: Update the link extraction function (e.g., ExtractLinks) to recognize the new pattern. A suggested regular expression is:

re := regexp.MustCompile(`\[\[([a-z]+):::(.+?)\]\]`)

This regex captures the domain and UUID portions.

2. Validation and URL Generation: After extraction, validate that the domain is one of the allowed values. Then, generate the appropriate URL for the link:

   • For note: /notes/<uuid>
   • For feed: /feeds/<uuid>
   • For entry: /feeds/entries/<uuid>
   • For doc: /documents/<uuid>
   • For post: /posts/<uuid> (if posts are implemented in the future)

3. Link Storage and Updates: Ensure that link creation, updates, and deletions in the note service properly handle the new syntax.

Frontend Implementation Changes

1. Rendering: Modify the markdown or HTML rendering component to detect the new link format and replace it with an HTML <a> tag with the generated URL.

2. Routing: Use client-side routing to navigate to the appropriate detail view when the link is clicked.

3. Styling: Apply specific styling to these links to indicate they are interactive.

For a complete description of the enhanced linking functionality, please refer to the standalone Links Specification.

Note Graph

1. Graph Visualization: Users can view a graph visualization of note connections
2. Interactive Navigation: Users can click on nodes in the graph to navigate to notes
3. Force-directed Layout: The graph uses a force-directed layout for optimal visualization

Obsidian Import

1. Import Vault: Users can import notes from an Obsidian vault (zip file)
2. Markdown Compatibility: Imported Markdown files are converted to QuickNotes format
3. Link Preservation: Links between notes are preserved during import

API Endpoints

Method	Endpoint	Description
GET	/api/notes	List all notes
POST	/api/notes	Create a new note
GET	/api/notes/:id	Get a specific note by ID
PUT	/api/notes/:id	Update a specific note
DELETE	/api/notes/:id	Delete a specific note
POST	/api/notes/import	Import notes from an Obsidian vault

Frontend Routes

Route	Description
/	Home page with list of notes
/notes/new	Create a new note
/notes/:id	View a specific note
/notes/:id?edit=true	Edit a specific note
/notes/graph	View the notes graph

Implementation Details

Link Extraction

The system extracts links from note content using a regular expression that matches the [[note-title]] pattern:

func (n *Note) ExtractLinks(content string) []string {
    re := regexp.MustCompile(`\[\[(.*?)\]\]`)
    matches := re.FindAllStringSubmatch(content, -1)
    titles := make([]string, 0, len(matches))
    for _, match := range matches {
        if len(match) > 1 {
            titles = append(titles, match[1])
        }
    }
    return titles
}

Link Management

When a note is created or updated, the system:

1. Extracts all links from the note content
2. Finds the corresponding target notes by title
3. Creates link records in the database
4. Updates the note's relationships

Graph Visualization

The notes graph is implemented using D3.js with a force-directed layout:

1. Nodes represent notes
2. Edges represent links between notes
3. Node size can be based on the number of connections
4. Users can zoom, pan, and click on nodes to navigate

User Interface

Note List

• Displays a list of all notes with titles and snippets
• Provides search functionality to filter notes
• Includes buttons for creating, editing, and deleting notes

Note Editor

• Markdown editor with preview functionality
• Auto-completion for note links
• Save and cancel buttons

Note Viewer

• Rendered Markdown content
• Clickable links to other notes
• Edit button to switch to editor mode

Graph View

• Interactive visualization of note connections
• Zoom and pan controls
• Search functionality to find specific notes in the graph