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:

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