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:

```go
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](../specs/links.md).

### 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:

```go
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