# binary-shadowmonarch/bookapp architecture

> Architecture diagram of the GitHub repository binary-shadowmonarch/bookapp, 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/binary-shadowmonarch/bookapp
- Repository: https://github.com/binary-shadowmonarch/bookapp

## Overview

Books is a web-based personal EPUB library. A reader uploads an EPUB; the frontend extracts metadata, sends the file to the protected Go API, and later loads the library and opens books in a browser reader. The backend also supports email-code registration, password and Google login, and token refresh. Reading progress and EPUB parsing are client-side; the README says progress is not persisted. The tree and excerpts establish the main wiring, but some handlers and frontend components were not sampled, so only documented links are shown.

Main entry points: [`backend/internal/handlers`](https://github.com/binary-shadowmonarch/bookapp/tree/master/backend/internal/handlers) (API handlers), [`backend/internal/auth/service.go`](https://github.com/binary-shadowmonarch/bookapp/blob/master/backend/internal/auth/service.go) (Auth and library service), [`frontend/src/routes/library/+page.svelte`](https://github.com/binary-shadowmonarch/bookapp/blob/master/frontend/src/routes/library/%2Bpage.svelte) (Library page), [`backend/cmd/server/main.go`](https://github.com/binary-shadowmonarch/bookapp/blob/master/backend/cmd/server/main.go) (HTTP server)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Library UI"]
  node_home["Home and routes<br/>[+page.svelte]"]
  node_library_page["Library page<br/>[+page.svelte]"]
  node_upload_ui["EPUB upload<br/>[EpubUpload.svelte]"]
  node_parser_pool["Parser pool"]
  node_parser_worker["EPUB worker"]
  node_book_card["Book cards<br/>[BookCard.svelte]"]
  node_book_reader["Book reader<br/>[BookReader.svelte]"]
  node_search["Library search<br/>[SearchBar.svelte]"]
end

subgraph group_identity["Accounts"]
  node_signup_page["Signup request<br/>[+page.server.ts]"]
  node_verify_page["Code verification<br/>[+page.server.ts]"]
  node_success_page["Signup success<br/>[+page.server.ts]"]
  node_login_ui["Login and OAuth UI<br/>[Login.svelte]"]
end

subgraph group_api["Backend API"]
  node_server["HTTP server<br/>[main.go]"]
  node_router["API router<br/>[router.go]"]
  node_handlers["API handlers"]
  node_auth_service["Auth and library service<br/>[service.go]"]
end

subgraph group_infra["Persistence and services"]
  node_postgres[("PostgreSQL store<br/>[postgres.go]")]
  node_seaweed["SeaweedFS filer<br/>[seaweedfs_filer.go]"]
  node_email_sender["Verification email<br/>[resend.go]"]
end

node_reader(("Library user"))
node_database[("PostgreSQL")]
node_filer_service["SeaweedFS"]
node_resend_service["Resend"]
node_google_service["Google OAuth"]

node_reader -->|"visits"| node_home
node_reader -->|"registers"| node_signup_page
node_reader -->|"signs in"| node_login_ui
node_home -->|"opens library"| node_library_page
node_library_page -->|"starts upload"| node_upload_ui
node_upload_ui -->|"extracts metadata"| node_parser_pool
node_parser_pool -->|"dispatches files"| node_parser_worker
node_upload_ui -->|"uploads EPUB"| node_handlers
node_library_page -->|"fetches library"| node_handlers
node_library_page -->|"shows books"| node_book_card
node_library_page -->|"filters books"| node_search
node_book_card -->|"opens book"| node_book_reader
node_book_reader -->|"renders EPUB"| node_reader
node_signup_page -->|"requests code"| node_handlers
node_signup_page -->|"redirects with email"| node_verify_page
node_verify_page -->|"submits code"| node_handlers
node_verify_page -->|"redirects on success"| node_success_page
node_login_ui -->|"submits credentials"| node_handlers
node_login_ui -.->|"starts OAuth"| node_google_service
node_server -->|"creates store"| node_postgres
node_server -->|"constructs service"| node_auth_service
node_server -->|"starts with router"| node_router
node_router -->|"dispatches requests"| node_handlers
node_handlers -->|"calls operations"| node_auth_service
node_auth_service -->|"reads and writes"| node_postgres
node_postgres -->|"queries"| node_database
node_auth_service -->|"stores and retrieves files"| node_seaweed
node_seaweed -->|"proxies file operations"| node_filer_service
node_auth_service -->|"sends code"| node_email_sender
node_email_sender -->|"delivers email"| node_resend_service
node_auth_service -->|"exchanges OAuth code"| node_google_service

click node_home "https://github.com/binary-shadowmonarch/bookapp/blob/master/frontend/src/routes/%2Bpage.svelte"
click node_library_page "https://github.com/binary-shadowmonarch/bookapp/blob/master/frontend/src/routes/library/%2Bpage.svelte"
click node_upload_ui "https://github.com/binary-shadowmonarch/bookapp/blob/master/frontend/src/lib/EpubUpload.svelte"
click node_parser_pool "https://github.com/binary-shadowmonarch/bookapp/blob/master/frontend/src/lib/epub-parser-pool.ts"
click node_parser_worker "https://github.com/binary-shadowmonarch/bookapp/blob/master/frontend/src/lib/epub-parser.worker.ts"
click node_book_card "https://github.com/binary-shadowmonarch/bookapp/blob/master/frontend/src/lib/BookCard.svelte"
click node_book_reader "https://github.com/binary-shadowmonarch/bookapp/blob/master/frontend/src/lib/BookReader.svelte"
click node_search "https://github.com/binary-shadowmonarch/bookapp/blob/master/frontend/src/lib/SearchBar.svelte"
click node_signup_page "https://github.com/binary-shadowmonarch/bookapp/blob/master/frontend/src/routes/signup/%2Bpage.server.ts"
click node_verify_page "https://github.com/binary-shadowmonarch/bookapp/blob/master/frontend/src/routes/signup/verify/%2Bpage.server.ts"
click node_success_page "https://github.com/binary-shadowmonarch/bookapp/blob/master/frontend/src/routes/signup/success/%2Bpage.server.ts"
click node_login_ui "https://github.com/binary-shadowmonarch/bookapp/blob/master/frontend/src/lib/Login.svelte"
click node_server "https://github.com/binary-shadowmonarch/bookapp/blob/master/backend/cmd/server/main.go"
click node_router "https://github.com/binary-shadowmonarch/bookapp/blob/master/backend/internal/handlers/router.go"
click node_handlers "https://github.com/binary-shadowmonarch/bookapp/tree/master/backend/internal/handlers"
click node_auth_service "https://github.com/binary-shadowmonarch/bookapp/blob/master/backend/internal/auth/service.go"
click node_postgres "https://github.com/binary-shadowmonarch/bookapp/blob/master/backend/internal/store/postgres.go"
click node_seaweed "https://github.com/binary-shadowmonarch/bookapp/blob/master/backend/internal/storage/seaweedfs_filer.go"
click node_email_sender "https://github.com/binary-shadowmonarch/bookapp/blob/master/backend/internal/email/resend.go"

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_home,node_library_page,node_upload_ui,node_parser_pool,node_parser_worker,node_book_card,node_book_reader,node_search,node_reader toneBlue
class node_signup_page,node_verify_page,node_success_page,node_login_ui,node_database toneAmber
class node_server,node_router,node_handlers,node_auth_service toneMint
class node_postgres,node_seaweed,node_email_sender toneRose
class node_filer_service,node_resend_service,node_google_service toneIndigo
```

## Components

### Library UI

- [Home and routes](https://github.com/binary-shadowmonarch/bookapp/blob/master/frontend/src/routes/%2Bpage.svelte): `frontend/src/routes/+page.svelte`
- [Library page](https://github.com/binary-shadowmonarch/bookapp/blob/master/frontend/src/routes/library/%2Bpage.svelte): `frontend/src/routes/library/+page.svelte`
- [EPUB upload](https://github.com/binary-shadowmonarch/bookapp/blob/master/frontend/src/lib/EpubUpload.svelte): `frontend/src/lib/EpubUpload.svelte`
- [Parser pool](https://github.com/binary-shadowmonarch/bookapp/blob/master/frontend/src/lib/epub-parser-pool.ts): `frontend/src/lib/epub-parser-pool.ts`
- [EPUB worker](https://github.com/binary-shadowmonarch/bookapp/blob/master/frontend/src/lib/epub-parser.worker.ts): `frontend/src/lib/epub-parser.worker.ts`
- [Book cards](https://github.com/binary-shadowmonarch/bookapp/blob/master/frontend/src/lib/BookCard.svelte): `frontend/src/lib/BookCard.svelte`
- [Book reader](https://github.com/binary-shadowmonarch/bookapp/blob/master/frontend/src/lib/BookReader.svelte): `frontend/src/lib/BookReader.svelte`
- [Library search](https://github.com/binary-shadowmonarch/bookapp/blob/master/frontend/src/lib/SearchBar.svelte): `frontend/src/lib/SearchBar.svelte`

### Accounts

- [Signup request](https://github.com/binary-shadowmonarch/bookapp/blob/master/frontend/src/routes/signup/%2Bpage.server.ts): `frontend/src/routes/signup/+page.server.ts`
- [Code verification](https://github.com/binary-shadowmonarch/bookapp/blob/master/frontend/src/routes/signup/verify/%2Bpage.server.ts): `frontend/src/routes/signup/verify/+page.server.ts`
- [Signup success](https://github.com/binary-shadowmonarch/bookapp/blob/master/frontend/src/routes/signup/success/%2Bpage.server.ts): `frontend/src/routes/signup/success/+page.server.ts`
- [Login and OAuth UI](https://github.com/binary-shadowmonarch/bookapp/blob/master/frontend/src/lib/Login.svelte): `frontend/src/lib/Login.svelte`

### Backend API

- [HTTP server](https://github.com/binary-shadowmonarch/bookapp/blob/master/backend/cmd/server/main.go): `backend/cmd/server/main.go`
- [API router](https://github.com/binary-shadowmonarch/bookapp/blob/master/backend/internal/handlers/router.go): `backend/internal/handlers/router.go`
- [API handlers](https://github.com/binary-shadowmonarch/bookapp/tree/master/backend/internal/handlers): `backend/internal/handlers`
- [Auth and library service](https://github.com/binary-shadowmonarch/bookapp/blob/master/backend/internal/auth/service.go): `backend/internal/auth/service.go`

### Persistence and services

- [PostgreSQL store](https://github.com/binary-shadowmonarch/bookapp/blob/master/backend/internal/store/postgres.go): `backend/internal/store/postgres.go`
- [SeaweedFS filer](https://github.com/binary-shadowmonarch/bookapp/blob/master/backend/internal/storage/seaweedfs_filer.go): `backend/internal/storage/seaweedfs_filer.go`
- [Verification email](https://github.com/binary-shadowmonarch/bookapp/blob/master/backend/internal/email/resend.go): `backend/internal/email/resend.go`

### Other components

- **Library user**
- **PostgreSQL**
- **SeaweedFS**
- **Resend**
- **Google OAuth**

## Connections

- Library user → Home and routes: visits
- Library user → Signup request: registers
- Library user → Login and OAuth UI: signs in
- Home and routes → Library page: opens library
- Library page → EPUB upload: starts upload
- EPUB upload → Parser pool: extracts metadata
- Parser pool → EPUB worker: dispatches files
- EPUB upload → API handlers: uploads EPUB
- Library page → API handlers: fetches library
- Library page → Book cards: shows books
- Library page → Library search: filters books
- Book cards → Book reader: opens book
- Book reader → Library user: renders EPUB
- Signup request → API handlers: requests code
- Signup request → Code verification: redirects with email
- Code verification → API handlers: submits code
- Code verification → Signup success: redirects on success
- Login and OAuth UI → API handlers: submits credentials
- Login and OAuth UI → Google OAuth: starts OAuth
- HTTP server → PostgreSQL store: creates store
- HTTP server → Auth and library service: constructs service
- HTTP server → API router: starts with router
- API router → API handlers: dispatches requests
- API handlers → Auth and library service: calls operations
- Auth and library service → PostgreSQL store: reads and writes
- PostgreSQL store → PostgreSQL: queries
- Auth and library service → SeaweedFS filer: stores and retrieves files
- SeaweedFS filer → SeaweedFS: proxies file operations
- Auth and library service → Verification email: sends code
- Verification email → Resend: delivers email
- Auth and library service → Google OAuth: exchanges OAuth code