quicknotes/specs/frontend.md

Frontend Specification

Overview

The QuickNotes frontend is built with Svelte and SvelteKit, providing a responsive single-page application experience. It communicates with the backend via RESTful API calls and provides a user-friendly interface for managing notes, read later items, and feeds.

Technology Stack

• SvelteKit: Framework for building the frontend application
• Bulma CSS: CSS framework for styling
• FontAwesome: Icon library
• D3.js: Used for the notes graph visualization
• Marked: Markdown parsing and rendering

Architecture

The frontend follows the SvelteKit architecture:

1. Routes: Defined in the src/routes directory, with each route corresponding to a page in the application
2. Components: Reusable UI components in the src/lib/components directory
3. Stores: Svelte stores for state management in the src/lib directory
4. API Client: Functions for communicating with the backend API in the src/lib/api directory

Routes

Route	Component	Description
/	+page.svelte	Home page with list of notes
/notes/new	notes/new/+page.svelte	Create a new note
/notes/:id	notes/[id]/+page.svelte	View or edit a specific note
/notes/graph	notes/graph/+page.svelte	View the notes graph
/readlist	readlist/+page.svelte	List of read later items
/readlist/:id	readlist/[id]/+page.svelte	View a specific read later item
/feeds	feeds/+page.svelte	List of feeds
/feeds/:id	feeds/[id]/+page.svelte	View entries from a specific feed
/feeds/entries/:id	feeds/entries/[id]/+page.svelte	View a specific feed entry

Components

Layout Components

• Navigation: Main navigation bar with links to different sections
• Footer: Page footer with application information
• Layout: Main layout component that wraps all pages

UI Components

• CardList: Reusable component for displaying lists of items as cards
• SearchBar: Search input with filtering functionality
• Pagination: Pagination controls for lists
• Modal: Modal dialog for confirmations and forms
• Tabs: Tabbed interface for switching between views
• Dropdown: Dropdown menu for actions
• Toast: Notification component for displaying messages

Feature Components

• NoteEditor: Markdown editor for creating and editing notes
• NoteViewer: Component for rendering note content with Markdown support
• NoteGraph: D3.js-based graph visualization of note connections
• ReadLaterForm: Form for saving new read later items
• ArticleViewer: Component for displaying read later items with clean formatting
• FeedList: Component for displaying a list of feeds
• EntryList: Component for displaying a list of feed entries

State Management

The frontend uses Svelte stores for state management:

1. Notes Store: Manages the state of notes

   // Example notes store
   export const notes = writable([]);
   
   // Load notes from the API
   notes.load = async () => {
     const response = await fetch('/api/notes');
     const data = await response.json();
     notes.set(data);
   };
   
   // Add other methods for CRUD operations
   

2. Readlist Store: Manages the state of read later items

3. Feeds Store: Manages the state of feeds and entries

API Integration

The frontend communicates with the backend API using the Fetch API:

// Example API client function
export async function fetchNotes() {
  const response = await fetch('/api/notes');
  if (!response.ok) {
    const error = await response.json();
    throw new Error(error.message || 'Failed to fetch notes');
  }
  return await response.json();
}

User Interface

Home Page

• List of notes with search functionality
• Buttons for creating new notes and importing from Obsidian
• Link to the notes graph visualization

Note Editor

• Markdown editor with preview functionality
• Title input field
• Save and cancel buttons
• Auto-save functionality

Note Viewer

• Rendered Markdown content
• Links to related notes
• Edit and delete buttons

Notes Graph

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

Readlist Page

• List of read later items with filters for read/unread and archived/unarchived
• Form for saving new items
• Buttons for marking as read, archiving, and deleting

Article Viewer

• Clean, reader-friendly display of article content
• Buttons for marking as read, archiving, and returning to the list

Feeds Page

• List of subscribed feeds with unread counts
• Form for subscribing to new feeds
• Buttons for refreshing, editing, and unsubscribing

Feed Entries Page

• List of entries from a specific feed or all feeds
• Filters for read/unread status
• Buttons for marking as read/unread

Responsive Design

The frontend is designed to be responsive and work well on different screen sizes:

1. Desktop: Full layout with sidebar navigation
2. Tablet: Adapted layout with collapsible navigation
3. Mobile: Simplified layout with mobile-friendly controls

Accessibility

The frontend follows accessibility best practices:

1. Semantic HTML: Using appropriate HTML elements for their intended purpose
2. ARIA Attributes: Adding ARIA attributes where necessary
3. Keyboard Navigation: Ensuring all functionality is accessible via keyboard
4. Color Contrast: Ensuring sufficient contrast for text and UI elements

Performance Optimization

The frontend is optimized for performance:

1. Code Splitting: Loading only the necessary code for each route
2. Lazy Loading: Loading components and data only when needed
3. Caching: Caching API responses where appropriate
4. Optimized Assets: Minimizing CSS and JavaScript files

Testing

The frontend includes tests using Playwright for end-to-end testing:

1. Page Tests: Testing each page's functionality
2. Component Tests: Testing individual components
3. Integration Tests: Testing the interaction between components
4. API Mock Tests: Testing with mocked API responses