Notes System

This document explains how the Notes system works in tududi from a user behavior perspective. For technical implementation details, see the backend code in /backend/modules/notes/ and frontend components in /frontend/components/Notes.tsx.

---

Overview

Notes are tududi's flexible capture and reference system - a place to store information, ideas, bookmarks, meeting notes, and any other content that doesn't fit the structured task workflow. Unlike tasks, notes don't have due dates, priorities, or completion states - they're purely informational.

Key characteristics:

• Rich text support via Markdown
• Optional project association
• Tag-based organization
• Color customization (10 predefined colors)
• Focus mode for distraction-free writing
• Auto-save every 1 second
• Search across title and content

URL: /notes or /notes/:uid

---

Core Principles

1. Information, not action

   • Notes store knowledge, not tasks
   • No due dates, priorities, or status tracking
   • Permanent reference material vs. temporary to-dos

2. Flexible structure

   • Can be standalone or linked to projects
   • Tag-based categorization
   • Full Markdown formatting support

3. Seamless capture

   • Auto-save prevents data loss
   • Quick creation from inbox items
   • Inline editing without modals

---

Note Structure

Fields

Field	Type	Required	Description
Title	String	No	Note heading (untitled if empty)
Content	Text	No	Main note body (Markdown supported)
Project	Reference	No	Associated project
Tags	Array	No	Categorization tags
Color	String	No	Background color (visual organization)
Created At	Timestamp	Auto	Creation timestamp
Updated At	Timestamp	Auto	Last modification timestamp

Unique Identifier

• Each note has a UID (unique identifier): uid field
• Used in URLs: /notes/abc123def456
• Immutable - persists through all edits

---

Creating Notes

Method 1: Direct Creation

From Notes page:

1. Navigate to /notes
2. Click + icon in top right
3. New note opens in edit mode
4. Start typing - auto-saves after 1 second
5. No explicit "Save" required

Keyboard shortcut:

• n (while on Notes page) - Create new note

Method 2: From Inbox

Convert inbox item to note:

1. Capture item in Inbox: Article link https://example.com +Reading #bookmark
2. Click "Note" button or press Ctrl+N (Cmd+N on Mac)
3. System creates note with:
   • Title: Fetched from URL (or URL itself if fetch fails)
   • Content: Full inbox text
   • Project: Linked from +Reading
   • Tags: Extracted from #bookmark
4. Inbox item marked as processed

See: Inbox Page documentation for details

Method 3: From Project Page

Via project view:

1. Open project detail page
2. Click "Add Note" in notes section
3. Note pre-linked to current project
4. Start editing

---

Editing Notes

Inline Editing

How it works:

1. Click on a note in the list to preview it
2. Click anywhere on the preview (title or content)
3. Note switches to edit mode
4. Changes auto-save every 1 second
5. Press Escape to save and exit edit mode

Save behavior:

• Auto-save: Triggers 1 second after you stop typing
• Save status indicators:
  • ✓ Saved (green) - Changes persisted
  • Saving... (blue) - Upload in progress
  • • Unsaved changes (amber) - Save failed or pending

What triggers auto-save:

• Typing in title field
• Typing in content field
• Changing project
• Adding/removing tags
• Changing note color

Title Editing

Rules:

• Title is optional - can be blank
• Blank titles show as "Untitled Note" in UI
• Auto-save only triggers if title is non-empty
• Click title in preview mode to enter edit mode

Content Editing

Markdown support:

• Full GitHub-flavored Markdown
• Headings: # H1, ## H2, ### H3
• Lists: - item or 1. item
• Links: `[text](url)`
• Bold: **text**
• Italic: _text_
• Code: `inline` or triple backticks for blocks
• Checkboxes: - [ ] unchecked or - [x] checked

Preview rendering:

• Content renders as formatted Markdown in preview mode
• Click to edit - shows raw Markdown
• Live preview updates on save

Multi-line Editing

Textarea behavior:

• Content field is a resizable textarea
• Minimum height: 300px
• Expands to fill available vertical space
• Shift+Enter for new lines

---

Note Organization

Projects

Linking notes to projects:

1. In edit mode, click project icon or "Add project"
2. Dropdown shows all available projects
3. Select project or choose "No Project" to unlink
4. Auto-saves immediately

Project behavior:

• Notes can belong to 0 or 1 project (not multiple)
• Changing projects moves the note
• Deleting a project unlinks all its notes (notes remain)
• Project appears in note metadata (preview and edit mode)

Permission handling:

• Can only link notes to projects you have write access to
• Shared projects: respects collaboration permissions
• Attempting to link to restricted project shows error

Tags

Adding tags:

1. In edit mode, click tag icon or "Add tags"
2. Tag input field appears
3. Type tag name and press Enter
4. Select from existing tags (autocomplete) or create new
5. Tags save immediately with note

Tag rules:

• Valid characters: Alphanumeric, hyphens, underscores
  • ✅ work, high-priority, q1_2026
  • ❌ tag with spaces, emoji🎉, punctuation!
• Case insensitive: Work = work = WORK
• Auto-create: New tags created on-the-fly
• Multiple tags: No limit on number per note

Removing tags:

• Click X on tag chip in tag input
• Changes save immediately

Tag navigation:

• Click tag name in preview mode → Go to tag page
• Shows all tasks/notes/projects with that tag

Colors

Note color feature:

• Feature flag: ENABLE_NOTE_COLOR (enabled by default)
• 10 predefined colors: Red, Orange, Amber, Green, Teal, Blue, Indigo, Purple, Pink, Grey
• None option: Default white/dark background

Setting color:

1. Click ⋮ menu (three vertical dots) in top right
2. Color palette grid appears
3. Click desired color swatch
4. Background changes immediately
5. Auto-saves

Color behavior:

• Applies to entire note background (edit and preview)
• Text color adjusts automatically (dark text on light colors, light text on dark colors)
• Persists across sessions
• Visible in note preview (full panel uses color)

Accessibility:

• Luminance calculation ensures readable text contrast
• Dark colors → White text (#ffffff)
• Light colors → Dark gray text (#333333)

---

Note Views

List View (Left Panel)

Default behavior:

• Shows all notes in scrollable list
• Most recent first (by default)
• Each item displays:
  • Title (bold, truncated)
  • Content preview (first 100 characters, 2 lines max)
  • Last updated date

Active note indicator:

• Blue vertical bar on left edge
• Highlighted background (white/gray-900)
• Indicates currently selected note

Empty state:

• "No notes found" message
• Appears when search returns zero results
• Or when user has no notes

Preview Mode (Right Panel)

When note selected:

• Full title at top (large, bold)
• Metadata row:
  • 🕐 Last updated date
  • 📁 Project (clickable link if assigned)
  • 🏷️ Tags (clickable links)
• Content rendered as Markdown below
• Click anywhere to enter edit mode

Click behavior:

• Title → Enter edit mode
• Content → Enter edit mode
• Project link → Navigate to project page
• Tag link → Navigate to tag page

Empty state:

• "Select a note to preview" message
• Shows when no note is selected (desktop only)

Edit Mode (Right Panel)

Layout:

• Title input at top (large, 2rem font)
• Metadata controls:
  • 🕐 Last updated or "New"
  • 📁 Project selector
  • 🏷️ Tag manager
• Save status indicator (✓ Saved / Saving... / • Unsaved)
• Content textarea (full height)
• ⋮ menu (options):
  • Color picker
  • Save button
  • Delete button (if note exists)

Back button (mobile):

• ← Back to list
• Appears only on mobile/tablet views
• Saves note before returning

Keyboard shortcuts:

• Esc - Save and exit edit mode (if title exists)
• Ctrl/Cmd+S - Manual save (implicit - auto-save handles this)

---

Focus Mode

Purpose: Distraction-free editing for deep work

Entering focus mode:

1. Click expand icon (↗️) in top right
2. Note expands to full screen
3. Hides sidebar, navigation, and note list

What's visible in focus mode:

• Note title (editable)
• Note content (editable)
• Minimal toolbar:
  • Close button (top right)
  • Save status
• Optional: Project and tag buttons (collapsed)

Exiting focus mode:

• Click X or close button
• Press Esc key
• Returns to standard two-panel view

Auto-save in focus mode:

• Same 1-second debounce
• Save status indicator remains visible
• Changes persist automatically

---

Searching and Filtering

Search

How to search:

1. Enter query in search box (top of note list)
2. Results filter in real-time
3. Searches both title AND content

Search behavior:

• Case insensitive: "markdown" matches "Markdown", "MARKDOWN"
• Substring matching: "task" matches "tasks", "multitasking"
• Multi-word: All words must appear (AND logic)
• No regex: Plain text search only

Search scope:

• Title field
• Content field (full text)
• Does NOT search tags or project names

Sorting

Sort options:

1. Created At (default) - Newest first
2. Title - Alphabetical A-Z
3. Updated - Most recently modified first

How to sort:

• Click sort icon (top of note list)
• Select sort option from dropdown
• List re-orders immediately

Sort persistence:

• Persists during session
• Resets to "Created At" on page reload

Tag Filtering

Via URL query:

• /notes?tag=bookmark - Show only notes with #bookmark tag
• API endpoint: GET /api/notes?tag=bookmark
• Filter by single tag only (not multiple)

No UI filter currently:

• Must use URL directly or navigate via tag page
• Click tag in note preview → Navigates to tag page showing all tagged items

---

Deleting Notes

Confirmation Required

Steps:

1. Select note or enter edit mode
2. Click ⋮ menu (three dots)
3. Click Delete (red text)
4. Confirmation dialog appears:
   • "Are you sure you want to delete this note?"
   • Shows note title
5. Confirm or cancel

What gets deleted:

• Note record (title, content, metadata)
• Tag associations (note-tag links)
• Project association (if any)

What's preserved:

• Project (unlinking only)
• Tags (remain in tag list)
• No note history (deletion is permanent)

No undo:

• Deletion is immediate and irreversible
• No trash/archive feature
• Ensure confirmation before proceeding

---

Responsive Behavior

Desktop (≥768px)

Two-panel layout:

• Left panel: Note list (fixed width: 320px)
• Right panel: Preview/edit (flexible width)
• Both panels visible simultaneously

Auto-selection:

• First note auto-selected on page load
• Clicking note updates right panel
• No "back" navigation needed

Mobile/Tablet (<768px)

Single panel:

• Shows note list OR preview/edit (not both)
• Clicking note → Hides list, shows preview
• "← Back to list" button → Returns to list

Navigation flow:

1. View note list
2. Tap note → Preview opens (list hidden)
3. Tap anywhere → Edit mode
4. Tap "← Back" → Returns to list

---

Integration with Other Features

Inbox Integration

Creating notes from inbox:

• Inbox items with URLs suggest "Note"
• Inbox items with #bookmark tag suggest "Note"
• Conversion preserves tags and project references
• See: Inbox Page documentation

URL title extraction:

• System fetches webpage <title> tag
• 3-second timeout
• Falls back to URL if fetch fails
• Auto-adds #bookmark tag

Project Integration

Notes in project view:

• Project detail page shows associated notes
• "Add Note" button creates pre-linked note
• Notes count appears in project card
• Deleting project unlinks notes (notes remain)

Shared project notes:

• Respects collaboration permissions
• Read-only access: Can view notes, cannot edit
• Read-write access: Can create/edit/delete notes
• Admin access: Full control

Tag Integration

Tag page shows notes:

• /tag/:uid lists all tasks, notes, projects with tag
• Notes appear in dedicated "Notes" section
• Clicking note → Opens in Notes page

Tag management:

• Tags created via notes appear in tag list
• Deleting tag removes from all notes
• Renaming tag (if supported) updates all notes

---

Auto-Save Behavior

Debounced Save

How it works:

1. User types in title or content
2. Save status changes to "• Unsaved changes"
3. After 1 second of inactivity, triggers save
4. Status changes to "Saving..."
5. On success: "✓ Saved"
6. On failure: "• Unsaved changes" (stays amber)

Debounce settings:

• Delay: 1000ms (1 second)
• Trailing: Yes (saves after typing stops)
• Leading: No (doesn't save on first keystroke)

What Triggers Save

Auto-save triggers:

• Title field changes
• Content field changes
• Project selection changes
• Tag additions/removals
• Color changes

No save triggers:

• Focusing input fields
• Scrolling
• Opening dropdowns
• Viewing preview mode

Save Guarantees

When navigation occurs:

• Leaving Notes page → Pending saves complete first
• Selecting different note → Current note saves first
• Mobile "Back" button → Saves before hiding panel

Error handling:

• Network failure → Status shows "• Unsaved changes"
• No automatic retry (user must trigger re-save by editing)
• Console error logged for debugging

Edge case - empty title:

• Auto-save only triggers if title is non-empty
• Empty title note → Not saved to server
• User must enter title to persist note

---

Display and Rendering

Markdown Rendering

Supported syntax:

• Headings: #, ##, ###, ####, #####, ######
• Bold: **text** or __text__
• Italic: *text* or _text_
• Links: `[text](url)` or <url>
• Lists: - item (unordered) or 1. item (ordered)
• Checkboxes: - [ ] todo or - [x] done
• Code: `inline` or ```language\nblock\n```
• Blockquotes: > quote
• Horizontal rules: --- or ***
• Tables: Pipe-separated cells
• Images: `![alt](url)` (rendered as <img>)

Rendering engine:

• Uses MarkdownRenderer component
• Safe HTML escaping (prevents XSS)
• Syntax highlighting for code blocks
• Opens external links in new tab

Title Display

Preview mode:

• Large heading (2rem font size)
• Medium weight (500)
• Truncated if very long (responsive)
• Shows "Untitled Note" if empty

Edit mode:

• Full-width input field
• Same size/weight as preview (2rem/500)
• Placeholder: "Note title..."
• Auto-focus on new note creation

Content Display

Preview mode:

• Rendered Markdown with styling
• Text size: 0.875rem (14px) on mobile, 1rem (16px) on desktop
• Line height: 1.5
• Scrollable if content exceeds viewport

Edit mode:

• Plain textarea (raw Markdown)
• Minimum height: 300px
• Expands to fill vertical space
• Monospace font (not specified, browser default)
• Placeholder: "Write your note content here... (Markdown supported)"

Color-Aware Text

Text color adjustment:

• Background luminance calculated from hex color
• Luminance < 0.4 → White text (#ffffff)
• Luminance ≥ 0.4 → Dark gray text (#333333)
• Applies to title, content, and metadata text

Formula:

luminance = (0.299 * R + 0.587 * G + 0.114 * B) / 255

---

Keyboard Shortcuts

Global (anywhere in app)

Shortcut	Action
g then n	Go to Notes page

On Notes page

Shortcut	Action
n	Create new note
Click note	Open in preview mode

In edit mode

Shortcut	Action
Esc	Save and exit edit mode (if title exists)
Tab	Navigate between fields

In focus mode

Shortcut	Action
Esc	Exit focus mode
Click X	Close focus mode

---

Common Workflows

Workflow 1: Quick Note Capture

Scenario: Capture a fleeting idea

1. Press g then n to open Notes page
2. Click + to create new note
3. Type title: "Product idea - Voice control"
4. Write content:

   ## Overview
   Users want hands-free interaction
   
   ## Features
   - Voice commands for task creation
   - Smart parsing of natural language
   - Integration with existing task flow

5. Auto-saves after 1 second
6. Add tags: #product, #ideas
7. Link to project: "Product Roadmap"
8. Press Esc to exit edit mode

Workflow 2: Meeting Notes

Scenario: Documenting a client meeting

1. Navigate to /notes
2. Create new note
3. Title: "Client Meeting - Acme Corp - 2026-03-14"
4. Content:

   ## Attendees
   - John (Acme Corp CEO)
   - Sarah (Product Manager)
   - Me
   
   ## Discussion
   - Requested new reporting dashboard
   - Timeline: Q2 2026
   - Budget: $50k
   
   ## Action Items
   - [ ] Send proposal by Monday
   - [ ] Schedule follow-up call
   - [ ] Share mockups

5. Link to project: "Acme Corp"
6. Add tags: #meetings, #clients, #acme
7. Auto-saves throughout
8. Click "Focus mode" for distraction-free review

Workflow 3: Bookmark Collection

Scenario: Save an article to read later

1. From Inbox: https://example.com/article +Reading #bookmark
2. Press Ctrl+N (or Cmd+N)
3. System:
   • Fetches title: "10 Tips for Better Focus"
   • Creates note with URL as content
   • Links to "Reading" project
   • Adds #bookmark tag
4. Note auto-saved and opens in edit mode
5. Add notes below URL:

   https://example.com/article
   
   ## Key Takeaways
   - Pomodoro technique
   - Single-tasking
   - Environment matters

6. Press Esc to save and exit

Workflow 4: Knowledge Base

Scenario: Building a personal wiki

1. Create note: "Git Cheatsheet"
2. Content:

   ## Common Commands
   
   ### Branching
   - `git branch <name>` - Create branch
   - `git checkout <name>` - Switch branch
   - `git checkout -b <name>` - Create and switch
   
   ### Committing
   - `git add .` - Stage all changes
   - `git commit -m "message"` - Commit with message
   - `git commit --amend` - Amend last commit
   
   ### Remote
   - `git push origin <branch>` - Push to remote
   - `git pull` - Fetch and merge

3. Add tags: #reference, #git, #dev
4. Link to project: "Developer Resources"
5. Set color: Blue (for tech references)
6. Bookmark /notes/:uid for quick access

Workflow 5: Weekly Review

Scenario: Process and organize accumulated notes

1. Navigate to /notes
2. Sort by "Updated" to see recent notes
3. Search for "meeting" to find unprocessed meeting notes
4. For each note:
   • Review content
   • Extract action items → Convert to tasks
   • Add relevant tags
   • Link to appropriate projects
   • Archive or delete if no longer needed
5. Search for untagged notes (manual review)
6. Ensure all bookmarks are properly categorized

---

Troubleshooting

"Auto-save not working"

Possible causes:

1. Title is empty → Auto-save only triggers with non-empty title
2. Network error → Check browser console for errors
3. Session expired → Re-authenticate
4. Debounce hasn't elapsed → Wait 1 second after typing

Solution:

• Add a title (at minimum)
• Check network connection
• Refresh page and re-login if needed
• Observe save status indicator

"Note disappeared after creating"

Likely cause: Empty title + navigated away

What happened:

• Created note without title
• Auto-save didn't trigger (requires title)
• Navigated away → Note not persisted

Prevention:

• Always add a title before leaving edit mode
• Check for "✓ Saved" status before navigating

"Markdown not rendering"

Check:

1. Are you in edit mode? (shows raw Markdown)
2. Switch to preview mode (click note in list or press Esc)
3. Ensure Markdown syntax is correct
   • ❌ #Heading (no space)
   • ✅ # Heading (space required)

"Can't link note to project"

Possible causes:

1. Project doesn't exist → Create project first
2. No write access to project → Check collaboration permissions
3. Project is archived → Unarchive or choose different project

Solution:

• Verify project exists in project list
• Check permissions with project owner
• Select different project

"Tags not saving"

Check:

1. Tag name has invalid characters?
   • Use only alphanumeric, hyphens, underscores
2. Network error during save?
   • Check browser console
3. Tag input didn't close properly?
   • Click outside tag input to trigger save

"Color not appearing"

Check:

1. Is ENABLE_NOTE_COLOR feature flag enabled?
   • Check with admin/developer
2. Browser caching issue?
   • Hard refresh: Ctrl+Shift+R or Cmd+Shift+R
3. Dark mode conflict?
   • Try switching theme

---

Best Practices

Organization

1. Use consistent tagging:

   • Create a tag hierarchy: #project-ideas, #project-specs, #project-retros
   • Avoid tag proliferation: Reuse existing tags

2. Link notes to projects:

   • Project-specific notes → Link to project
   • General knowledge → Leave unlinked or create "Resources" project

3. Color coding:

   • Develop personal system: Red = urgent, Blue = reference, Green = ideas
   • Or by topic: Purple = client work, Teal = personal

Content

1. Use Markdown effectively:

   • Headings for structure
   • Lists for clarity
   • Checkboxes for tracking follow-ups within notes
   • Code blocks for technical snippets

2. Include metadata:

   • Date in title for meeting notes: "Meeting - Client - 2026-03-14"
   • Context in content: "Source: [Article](url)"

3. Break up long notes:

   • Split into multiple notes by subtopic
   • Link between notes using markdown links
   • Use tags to group related notes

Maintenance

1. Regular review:

   • Weekly: Process new notes, add tags, link to projects
   • Monthly: Archive or delete obsolete notes
   • Quarterly: Reorganize tag system

2. Search before creating:

   • Check if similar note exists
   • Consolidate duplicates

3. Bookmark frequently accessed:

   • Copy note URL: /notes/:uid
   • Save in browser bookmarks for quick access

---

Limitations and Constraints

Current Limitations

1. No note history/versions:

   • Edits overwrite previous content
   • No undo beyond current session
   • Workaround: Use external version control for critical notes

2. Single project per note:

   • Cannot link note to multiple projects
   • Workaround: Duplicate note or use tags for cross-referencing

3. No hierarchical notes:

   • Flat structure only (no sub-notes)
   • Workaround: Use Markdown headings and lists

4. No collaborative editing:

   • Only one user can edit at a time
   • No conflict resolution
   • Last save wins (potential data loss)

5. No attachments:

   • Cannot upload files/images to notes
   • Workaround: Host elsewhere, link via Markdown

6. Limited rich text:

   • Markdown only (no WYSIWYG editor)
   • No inline images (must use external URLs)
   • No tables with complex formatting

Technical Constraints

1. Search limitations:

   • No fuzzy matching
   • No search within tags/projects
   • No advanced operators (AND, OR, NOT)

2. Performance:

   • All notes loaded at once (no pagination)
   • Slow with 1000+ notes
   • No virtualized scrolling

3. Mobile experience:

   • Single-panel only (no split view)
   • Harder to reference multiple notes

---

Related Documentation

• Inbox Page - Quick capture and conversion to notes
• Today Page Sections - Task-focused workflow
• Architecture Overview - Technical architecture
• Development Workflow - Working with the codebase
• Common Tasks - How to modify notes functionality

Technical Implementation Files:

• Note model: /backend/models/note.js
• Note service: /backend/modules/notes/service.js
• Note controller: /backend/modules/notes/controller.js
• Note repository: /backend/modules/notes/repository.js
• Note API routes: /backend/modules/notes/routes.js
• Notes component: /frontend/components/Notes.tsx
• Note modal: /frontend/components/Note/NoteModal.tsx
• Note focus mode: /frontend/components/Note/NoteFocusMode.tsx
• Markdown renderer: /frontend/components/Shared/MarkdownRenderer.tsx
• Note service (frontend): /frontend/utils/notesService.ts

---

Document Version: 1.0.0 Last Updated: 2026-03-14 Audience: Developers, AI assistants, and end users