# raghavtandonn/margin architecture

> Architecture diagram of the GitHub repository raghavtandonn/margin, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/raghavtandonn/margin
- Repository: https://github.com/raghavtandonn/margin
- Video tour (about a minute): https://gitdiagram.com/raghavtandonn/margin/video

## Overview

MARGIN is a private-first reading log: readers build and curate a library, record reading and reviews, and explore it through visual shelves, seasons, and recommendations. The main request path enters Express, passes through authentication/security middleware, and reaches feature routes backed by SQLite. Browser imports preview and confirm books before adding them; the README also documents supplementary notes, dates, and quotes. The tree and excerpts establish the major subsystems, but do not expose all route-to-library calls, so uncertain internal links are omitted.

Main entry points: [`routes/pages.js`](https://github.com/raghavtandonn/margin/blob/main/routes/pages.js) (Page routes), [`db/index.js`](https://github.com/raghavtandonn/margin/blob/main/db/index.js) (SQLite database), [`server.js`](https://github.com/raghavtandonn/margin/blob/main/server.js) (Express server), [`routes/auth.js`](https://github.com/raghavtandonn/margin/blob/main/routes/auth.js) (Authentication routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web entry"]
  node_server["Express server<br/>[server.js]"]
  node_page_routes["Page routes<br/>[pages.js]"]
  node_api_routes["API routes<br/>[api.js]"]
end

subgraph group_identity["Identity and privacy"]
  node_auth_routes["Authentication routes<br/>[auth.js]"]
  node_settings_routes["Settings routes<br/>[settings.js]"]
  node_auth_sessions["Sessions and passkeys<br/>[sessions.js]"]
  node_auth_webauthn["WebAuthn<br/>[webauthn.js]"]
end

subgraph group_library["Reading library"]
  node_library["Library and shelves<br/>[library.js]"]
  node_import["Library import<br/>[import.js]"]
  node_supplements["Import supplements<br/>[supplement.js]"]
  node_works["Works and editions<br/>[works.js]"]
  node_reading["Reading records<br/>[reviews.js]"]
  node_notes["Private notes<br/>[notes.js]"]
end

subgraph group_community["Community"]
  node_community_routes["Community routes<br/>[community.js]"]
  node_clubs_routes["Clubs routes<br/>[clubs.js]"]
end

subgraph group_discovery["Visuals and discovery"]
  node_seasons_routes["Season catalogues<br/>[seasons.js]"]
  node_lookbook_routes["Lookbook<br/>[lookbook.js]"]
  node_colour["Colour system<br/>[colour.js]"]
  node_recommendations["Recommendations<br/>[reco.js]"]
  node_embeddings["Embedding store<br/>[embeddings.js]"]
end

node_reader(("Reader"))
node_db[("SQLite database<br/>[index.js]")]
node_openlibrary["Open Library"]

node_reader -->|"sends requests"| node_server
node_server -->|"dispatches pages"| node_page_routes
node_server -->|"dispatches API"| node_api_routes
node_server -->|"dispatches auth"| node_auth_routes
node_server -->|"dispatches settings"| node_settings_routes
node_page_routes -->|"reads shelves"| node_library
node_page_routes -->|"loads works"| node_works
node_page_routes -->|"loads reviews"| node_reading
node_page_routes -->|"reads notes"| node_notes
node_auth_routes -->|"creates sessions"| node_auth_sessions
node_auth_webauthn -->|"stores credentials"| node_db
node_auth_routes -.->|"verifies passkeys"| node_auth_webauthn
node_settings_routes -->|"handles imports"| node_import
node_import -->|"matches works"| node_works
node_settings_routes -->|"previews supplements"| node_supplements
node_community_routes -->|"serves reviews"| node_reading
node_clubs_routes -->|"reads and writes"| node_db
node_seasons_routes -->|"reads catalogues"| node_db
node_lookbook_routes -->|"uses colour"| node_colour
node_page_routes -.->|"shows suggestions"| node_recommendations
node_recommendations -->|"reads vectors"| node_embeddings
node_embeddings -->|"stores vectors"| node_db
node_works -->|"reads and writes"| node_db
node_library -->|"reads and writes"| node_db
node_reading -->|"reads and writes"| node_db
node_notes -->|"reads and writes"| node_db
node_page_routes -.->|"looks up editions"| node_openlibrary

click node_server "https://github.com/raghavtandonn/margin/blob/main/server.js"
click node_page_routes "https://github.com/raghavtandonn/margin/blob/main/routes/pages.js"
click node_api_routes "https://github.com/raghavtandonn/margin/blob/main/routes/api.js"
click node_auth_routes "https://github.com/raghavtandonn/margin/blob/main/routes/auth.js"
click node_settings_routes "https://github.com/raghavtandonn/margin/blob/main/routes/settings.js"
click node_auth_sessions "https://github.com/raghavtandonn/margin/blob/main/lib/auth/sessions.js"
click node_auth_webauthn "https://github.com/raghavtandonn/margin/blob/main/lib/auth/webauthn.js"
click node_library "https://github.com/raghavtandonn/margin/blob/main/lib/library.js"
click node_import "https://github.com/raghavtandonn/margin/blob/main/lib/import.js"
click node_supplements "https://github.com/raghavtandonn/margin/blob/main/lib/supplement.js"
click node_works "https://github.com/raghavtandonn/margin/blob/main/lib/works.js"
click node_reading "https://github.com/raghavtandonn/margin/blob/main/lib/reviews.js"
click node_notes "https://github.com/raghavtandonn/margin/blob/main/lib/notes.js"
click node_community_routes "https://github.com/raghavtandonn/margin/blob/main/routes/community.js"
click node_clubs_routes "https://github.com/raghavtandonn/margin/blob/main/routes/clubs.js"
click node_seasons_routes "https://github.com/raghavtandonn/margin/blob/main/routes/seasons.js"
click node_lookbook_routes "https://github.com/raghavtandonn/margin/blob/main/routes/lookbook.js"
click node_colour "https://github.com/raghavtandonn/margin/blob/main/lib/colour.js"
click node_recommendations "https://github.com/raghavtandonn/margin/blob/main/lib/reco.js"
click node_embeddings "https://github.com/raghavtandonn/margin/blob/main/lib/embeddings.js"
click node_db "https://github.com/raghavtandonn/margin/blob/main/db/index.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_server,node_page_routes,node_api_routes toneBlue
class node_auth_routes,node_settings_routes,node_auth_sessions,node_auth_webauthn,node_db toneAmber
class node_library,node_import,node_supplements,node_works,node_reading,node_notes toneMint
class node_community_routes,node_clubs_routes toneRose
class node_seasons_routes,node_lookbook_routes,node_colour,node_recommendations,node_embeddings,node_reader,node_openlibrary toneIndigo
```

## Components

### Web entry

- [Express server](https://github.com/raghavtandonn/margin/blob/main/server.js): `server.js`
- [Page routes](https://github.com/raghavtandonn/margin/blob/main/routes/pages.js): `routes/pages.js`
- [API routes](https://github.com/raghavtandonn/margin/blob/main/routes/api.js): `routes/api.js`

### Identity and privacy

- [Authentication routes](https://github.com/raghavtandonn/margin/blob/main/routes/auth.js): `routes/auth.js`
- [Settings routes](https://github.com/raghavtandonn/margin/blob/main/routes/settings.js): `routes/settings.js`
- [Sessions and passkeys](https://github.com/raghavtandonn/margin/blob/main/lib/auth/sessions.js): `lib/auth/sessions.js`
- [WebAuthn](https://github.com/raghavtandonn/margin/blob/main/lib/auth/webauthn.js): `lib/auth/webauthn.js`

### Reading library

- [Library and shelves](https://github.com/raghavtandonn/margin/blob/main/lib/library.js): `lib/library.js`
- [Library import](https://github.com/raghavtandonn/margin/blob/main/lib/import.js): `lib/import.js`
- [Import supplements](https://github.com/raghavtandonn/margin/blob/main/lib/supplement.js): `lib/supplement.js`
- [Works and editions](https://github.com/raghavtandonn/margin/blob/main/lib/works.js): `lib/works.js`
- [Reading records](https://github.com/raghavtandonn/margin/blob/main/lib/reviews.js): `lib/reviews.js`
- [Private notes](https://github.com/raghavtandonn/margin/blob/main/lib/notes.js): `lib/notes.js`

### Community

- [Community routes](https://github.com/raghavtandonn/margin/blob/main/routes/community.js): `routes/community.js`
- [Clubs routes](https://github.com/raghavtandonn/margin/blob/main/routes/clubs.js): `routes/clubs.js`

### Visuals and discovery

- [Season catalogues](https://github.com/raghavtandonn/margin/blob/main/routes/seasons.js): `routes/seasons.js`
- [Lookbook](https://github.com/raghavtandonn/margin/blob/main/routes/lookbook.js): `routes/lookbook.js`
- [Colour system](https://github.com/raghavtandonn/margin/blob/main/lib/colour.js): `lib/colour.js`
- [Recommendations](https://github.com/raghavtandonn/margin/blob/main/lib/reco.js): `lib/reco.js`
- [Embedding store](https://github.com/raghavtandonn/margin/blob/main/lib/embeddings.js): `lib/embeddings.js`

### Other components

- **Reader**
- [SQLite database](https://github.com/raghavtandonn/margin/blob/main/db/index.js): `db/index.js`
- **Open Library**

## Connections

- Reader → Express server: sends requests
- Express server → Page routes: dispatches pages
- Express server → API routes: dispatches API
- Express server → Authentication routes: dispatches auth
- Express server → Settings routes: dispatches settings
- Page routes → Library and shelves: reads shelves
- Page routes → Works and editions: loads works
- Page routes → Reading records: loads reviews
- Page routes → Private notes: reads notes
- Authentication routes → Sessions and passkeys: creates sessions
- WebAuthn → SQLite database: stores credentials
- Authentication routes → WebAuthn: verifies passkeys
- Settings routes → Library import: handles imports
- Library import → Works and editions: matches works
- Settings routes → Import supplements: previews supplements
- Community routes → Reading records: serves reviews
- Clubs routes → SQLite database: reads and writes
- Season catalogues → SQLite database: reads catalogues
- Lookbook → Colour system: uses colour
- Page routes → Recommendations: shows suggestions
- Recommendations → Embedding store: reads vectors
- Embedding store → SQLite database: stores vectors
- Works and editions → SQLite database: reads and writes
- Library and shelves → SQLite database: reads and writes
- Reading records → SQLite database: reads and writes
- Private notes → SQLite database: reads and writes
- Page routes → Open Library: looks up editions