quicknotes/specs/architecture.md

Architecture Specification

Overview

QuickNotes is a personal knowledge management application with a client-server architecture. It consists of a Go backend and a Svelte frontend, with SQLite as the database.

System Components

Backend

The backend is built with Go and uses the following key components:

1. Gin Web Framework: Handles HTTP routing and middleware
2. GORM: Object-relational mapping for database operations
3. SQLite: Embedded database for data storage
4. Domain Modules:
   • Notes: Manages note creation, retrieval, and linking
   • Readlist: Handles read-later functionality
   • Feeds: Manages RSS/Atom feed subscriptions and entries

Frontend

The frontend is built with Svelte and SvelteKit, providing a responsive single-page application experience:

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

Database

SQLite is used as the database, with the following main tables:

1. Notes: Stores user notes
2. Note Links: Stores relationships between notes
3. Read Later Items: Stores saved articles
4. Feeds: Stores feed subscriptions
5. Entries: Stores feed entries

Communication Flow

1. The frontend communicates with the backend via RESTful API calls
2. The backend processes these requests, interacts with the database, and returns responses
3. The frontend renders the data and handles user interactions

┌─────────────┐      HTTP/JSON      ┌─────────────┐      SQL      ┌─────────────┐
│   Frontend  │ ─────────────────► │   Backend   │ ───────────► │  Database   │
│  (Svelte)   │ ◄───────────────── │    (Go)     │ ◄───────────  │  (SQLite)   │
└─────────────┘                     └─────────────┘               └─────────────┘

Deployment Architecture

The application is designed to be run locally as a single binary that embeds the frontend assets:

1. The Go backend serves the compiled Svelte frontend
2. The SQLite database is stored as a local file
3. The application is accessed via a web browser at http://localhost:3000

File Structure

quicknotes/
├── main.go                 # Application entry point
├── go.mod                  # Go module definition
├── go.sum                  # Go module checksums
├── notes/                  # Notes module
│   ├── model.go            # Note data models
│   ├── service.go          # Business logic
│   └── routes.go           # API endpoints
├── readlist/               # Readlist module
│   ├── model.go            # Readlist data models
│   ├── service.go          # Business logic
│   └── routes.go           # API endpoints
├── feeds/                  # Feeds module
│   ├── model.go            # Feed data models
│   ├── service.go          # Business logic
│   └── handler.go          # API endpoints
├── frontend/               # Frontend application
│   ├── src/                # Source code
│   │   ├── routes/         # SvelteKit routes
│   │   ├── lib/            # Shared components and utilities
│   │   └── app.html        # HTML template
│   ├── static/             # Static assets
│   └── build/              # Compiled frontend (embedded in binary)
└── notes.db                # SQLite database file

Design Patterns

1. Model-View-Controller (MVC): The backend follows an MVC-like pattern with models, services, and handlers
2. Repository Pattern: Database operations are abstracted in service layers
3. Dependency Injection: Services are injected into handlers
4. RESTful API: The backend exposes a RESTful API for the frontend to consume

Security Considerations

1. The application is designed for local use and does not implement authentication
2. Input validation is performed on both client and server sides
3. Content Security Policy headers are set for frontend assets
4. The application uses parameterized queries to prevent SQL injection