# duwqijlk/margin-words architecture

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

- Interactive diagram: https://gitdiagram.com/duwqijlk/margin-words
- Repository: https://github.com/duwqijlk/margin-words

## Overview

Margin Words is an offline-capable English-novel reader for Chinese junior-high learners. Readers discover a title, sign in to add it, then read a stored or downloaded book with book-specific meanings and paragraph, sentence, and phrase notes; they can save words to a notebook and review them later. Copyrighted titles require the reader’s own EPUB. Optional accounts sync reading and study state. The README documents these capabilities; source excerpts and the index support selected internal links, but many UI and catalog modules were not sampled.

Main entry points: [`src/components/reader.tsx`](https://github.com/duwqijlk/margin-words/blob/main/src/components/reader.tsx) (Novel reader), [`src/components/review.tsx`](https://github.com/duwqijlk/margin-words/blob/main/src/components/review.tsx) (Word review), [`functions/lib/handlers.ts`](https://github.com/duwqijlk/margin-words/blob/main/functions/lib/handlers.ts) (Account handlers), [`src/components/shelf.tsx`](https://github.com/duwqijlk/margin-words/blob/main/src/components/shelf.tsx) (Book shelf)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Reader experience"]
  node_reader["Reader app<br/>[margin-app.tsx]"]
  node_shelf["Book shelf<br/>[shelf.tsx]"]
  node_discover["Discover catalog<br/>[discover.tsx]"]
  node_dashboard["Library dashboard<br/>[dashboard-page.tsx]"]
  node_guide["Guide and help<br/>[guide-page.tsx]"]
end

subgraph group_content["Books and reading"]
  node_reader_view["Novel reader<br/>[reader.tsx]"]
  node_book_store[("Local book store<br/>[book-db.ts]")]
  node_epub["EPUB handling<br/>[epub.ts]"]
  node_glossary["Book glossary<br/>[glossary-format.ts]"]
  node_paragraph_notes["Paragraph notes<br/>[paragraph-note.ts]"]
  node_floating_card["Meaning card<br/>[floating-card.tsx]"]
  node_position["Reading position<br/>[position.ts]"]
end

subgraph group_study["Study tools"]
  node_notebook["Word notebook<br/>[notebook.tsx]"]
  node_vocab_store[("Vocabulary state<br/>[vocab-store.ts]")]
  node_review["Word review<br/>[review.tsx]"]
  node_spaced_review["Review scheduling<br/>[srs.ts]"]
end

subgraph group_accounts["Accounts and sync"]
  node_account_ui["Account controls<br/>[account-dialog.tsx]"]
  node_sync_engine["Sync engine<br/>[sync-engine.ts]"]
  node_sync_api["Sync API<br/>[sync.ts]"]
  node_handlers["Account handlers<br/>[handlers.ts]"]
  node_session["Session management<br/>[session.ts]"]
  node_db[("D1 database<br/>[db.ts]")]
end

node_reader_user(("Reader"))
node_book_host["Books host"]

node_reader_user -->|"opens shelf"| node_shelf
node_shelf -->|"browses titles"| node_discover
node_discover -->|"adds book"| node_shelf
node_reader_user -->|"reads book"| node_reader_view
node_reader_view -->|"loads stored book"| node_book_store
node_reader_view -->|"opens EPUB"| node_epub
node_reader_view -->|"reads meanings"| node_glossary
node_reader_view -->|"loads notes"| node_paragraph_notes
node_reader_view -.->|"shows meaning"| node_floating_card
node_reader_view -->|"tracks position"| node_position
node_reader_user -->|"saves words"| node_notebook
node_notebook -.->|"stores vocabulary"| node_vocab_store
node_reader_view -->|"saves words"| node_vocab_store
node_reader_user -->|"reviews words"| node_review
node_review -->|"schedules review"| node_spaced_review
node_review -->|"reads study state"| node_vocab_store
node_reader_user -->|"signs in"| node_account_ui
node_account_ui -.->|"enables sync"| node_sync_engine
node_sync_engine -->|"syncs state"| node_sync_api
node_sync_api -->|"routes requests"| node_handlers
node_handlers -->|"reads and writes"| node_db
node_handlers -->|"checks sessions"| node_session
node_book_host -.->|"serves books"| node_reader_view
node_dashboard -.->|"summarizes library"| node_reader_user
node_guide -.->|"explains features"| node_reader_user

click node_reader "https://github.com/duwqijlk/margin-words/blob/main/src/components/margin-app.tsx"
click node_shelf "https://github.com/duwqijlk/margin-words/blob/main/src/components/shelf.tsx"
click node_discover "https://github.com/duwqijlk/margin-words/blob/main/src/components/discover.tsx"
click node_dashboard "https://github.com/duwqijlk/margin-words/blob/main/src/components/dashboard-page.tsx"
click node_guide "https://github.com/duwqijlk/margin-words/blob/main/src/components/guide-page.tsx"
click node_reader_view "https://github.com/duwqijlk/margin-words/blob/main/src/components/reader.tsx"
click node_book_store "https://github.com/duwqijlk/margin-words/blob/main/src/lib/book-db.ts"
click node_epub "https://github.com/duwqijlk/margin-words/blob/main/src/lib/epub.ts"
click node_glossary "https://github.com/duwqijlk/margin-words/blob/main/src/lib/glossary-format.ts"
click node_paragraph_notes "https://github.com/duwqijlk/margin-words/blob/main/src/lib/paragraph-note.ts"
click node_floating_card "https://github.com/duwqijlk/margin-words/blob/main/src/components/floating-card.tsx"
click node_position "https://github.com/duwqijlk/margin-words/blob/main/src/lib/position.ts"
click node_notebook "https://github.com/duwqijlk/margin-words/blob/main/src/components/notebook.tsx"
click node_vocab_store "https://github.com/duwqijlk/margin-words/blob/main/src/lib/vocab-store.ts"
click node_review "https://github.com/duwqijlk/margin-words/blob/main/src/components/review.tsx"
click node_spaced_review "https://github.com/duwqijlk/margin-words/blob/main/src/lib/srs.ts"
click node_account_ui "https://github.com/duwqijlk/margin-words/blob/main/src/components/account-dialog.tsx"
click node_sync_engine "https://github.com/duwqijlk/margin-words/blob/main/src/lib/sync-engine.ts"
click node_sync_api "https://github.com/duwqijlk/margin-words/blob/main/functions/api/sync.ts"
click node_handlers "https://github.com/duwqijlk/margin-words/blob/main/functions/lib/handlers.ts"
click node_session "https://github.com/duwqijlk/margin-words/blob/main/functions/lib/session.ts"
click node_db "https://github.com/duwqijlk/margin-words/blob/main/functions/lib/db.ts"

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_reader,node_shelf,node_discover,node_dashboard,node_guide toneBlue
class node_reader_view,node_book_store,node_epub,node_glossary,node_paragraph_notes,node_floating_card,node_position toneAmber
class node_notebook,node_vocab_store,node_review,node_spaced_review toneMint
class node_account_ui,node_sync_engine,node_sync_api,node_handlers,node_session,node_db toneRose
class node_reader_user,node_book_host toneIndigo
```

## Components

### Reader experience

- [Reader app](https://github.com/duwqijlk/margin-words/blob/main/src/components/margin-app.tsx): `src/components/margin-app.tsx`
- [Book shelf](https://github.com/duwqijlk/margin-words/blob/main/src/components/shelf.tsx): `src/components/shelf.tsx`
- [Discover catalog](https://github.com/duwqijlk/margin-words/blob/main/src/components/discover.tsx): `src/components/discover.tsx`
- [Library dashboard](https://github.com/duwqijlk/margin-words/blob/main/src/components/dashboard-page.tsx): `src/components/dashboard-page.tsx`
- [Guide and help](https://github.com/duwqijlk/margin-words/blob/main/src/components/guide-page.tsx): `src/components/guide-page.tsx`

### Books and reading

- [Novel reader](https://github.com/duwqijlk/margin-words/blob/main/src/components/reader.tsx): `src/components/reader.tsx`
- [Local book store](https://github.com/duwqijlk/margin-words/blob/main/src/lib/book-db.ts): `src/lib/book-db.ts`
- [EPUB handling](https://github.com/duwqijlk/margin-words/blob/main/src/lib/epub.ts): `src/lib/epub.ts`
- [Book glossary](https://github.com/duwqijlk/margin-words/blob/main/src/lib/glossary-format.ts): `src/lib/glossary-format.ts`
- [Paragraph notes](https://github.com/duwqijlk/margin-words/blob/main/src/lib/paragraph-note.ts): `src/lib/paragraph-note.ts`
- [Meaning card](https://github.com/duwqijlk/margin-words/blob/main/src/components/floating-card.tsx): `src/components/floating-card.tsx`
- [Reading position](https://github.com/duwqijlk/margin-words/blob/main/src/lib/position.ts): `src/lib/position.ts`

### Study tools

- [Word notebook](https://github.com/duwqijlk/margin-words/blob/main/src/components/notebook.tsx): `src/components/notebook.tsx`
- [Vocabulary state](https://github.com/duwqijlk/margin-words/blob/main/src/lib/vocab-store.ts): `src/lib/vocab-store.ts`
- [Word review](https://github.com/duwqijlk/margin-words/blob/main/src/components/review.tsx): `src/components/review.tsx`
- [Review scheduling](https://github.com/duwqijlk/margin-words/blob/main/src/lib/srs.ts): `src/lib/srs.ts`

### Accounts and sync

- [Account controls](https://github.com/duwqijlk/margin-words/blob/main/src/components/account-dialog.tsx): `src/components/account-dialog.tsx`
- [Sync engine](https://github.com/duwqijlk/margin-words/blob/main/src/lib/sync-engine.ts): `src/lib/sync-engine.ts`
- [Sync API](https://github.com/duwqijlk/margin-words/blob/main/functions/api/sync.ts): `functions/api/sync.ts`
- [Account handlers](https://github.com/duwqijlk/margin-words/blob/main/functions/lib/handlers.ts): `functions/lib/handlers.ts`
- [Session management](https://github.com/duwqijlk/margin-words/blob/main/functions/lib/session.ts): `functions/lib/session.ts`
- [D1 database](https://github.com/duwqijlk/margin-words/blob/main/functions/lib/db.ts): `functions/lib/db.ts`

### Other components

- **Reader**
- **Books host**

## Connections

- Reader → Book shelf: opens shelf (evidence: `README.md`)
- Book shelf → Discover catalog: browses titles (evidence: `README.md`)
- Discover catalog → Book shelf: adds book (evidence: `README.md`)
- Reader → Novel reader: reads book (evidence: `README.md`)
- Novel reader → Local book store: loads stored book (evidence: `src/components/reader.tsx`)
- Novel reader → EPUB handling: opens EPUB (evidence: `src/components/reader.tsx`)
- Novel reader → Book glossary: reads meanings (evidence: `src/components/reader.tsx`)
- Novel reader → Paragraph notes: loads notes (evidence: `src/components/reader.tsx`)
- Novel reader → Meaning card: shows meaning (evidence: `README.md`)
- Novel reader → Reading position: tracks position (evidence: `src/components/reader.tsx`)
- Reader → Word notebook: saves words (evidence: `README.md`)
- Word notebook → Vocabulary state: stores vocabulary (evidence: `README.md`)
- Novel reader → Vocabulary state: saves words (evidence: `src/components/reader.tsx`)
- Reader → Word review: reviews words (evidence: `README.md`)
- Word review → Review scheduling: schedules review (evidence: `src/components/review.tsx`)
- Word review → Vocabulary state: reads study state (evidence: `src/components/review.tsx`)
- Reader → Account controls: signs in (evidence: `README.md`)
- Account controls → Sync engine: enables sync (evidence: `README.md`)
- Sync engine → Sync API: syncs state (evidence: `src/lib/sync-engine.ts`)
- Sync API → Account handlers: routes requests (evidence: `functions/api/sync.ts`)
- Account handlers → D1 database: reads and writes (evidence: `functions/lib/handlers.ts`)
- Account handlers → Session management: checks sessions (evidence: `functions/lib/handlers.ts`)
- Books host → Novel reader: serves books (evidence: `README.md`)
- Library dashboard → Reader: summarizes library (evidence: `README.md`)
- Guide and help → Reader: explains features (evidence: `README.md`)
