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
   ```javascript
   // 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:

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