187 lines
No EOL
6.1 KiB
Markdown
187 lines
No EOL
6.1 KiB
Markdown
# 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 |