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

1. Wiki-style Links: Users can create links between notes using the [[note-title]] syntax
2. Automatic Link Management: Links are automatically created, updated, or removed when notes are saved
3. Bidirectional Links: Links are bidirectional, allowing navigation in both directions

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