# coreyarnold/libraryn architecture

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

- Interactive diagram: https://gitdiagram.com/coreyarnold/libraryn
- Repository: https://github.com/coreyarnold/libraryn

## Overview

Family Library is a self-hosted household collection app: a family member scans a book barcode in the browser, the server looks up metadata, and the member can add the result to their collection. It also supports DVDs, family accounts, collection browsing, condition and location tracking, loans, scan auditing, and Goodreads synchronization. The graph follows the documented book-scan flow and sampled server calls; some DVD and background-worker details are only partially excerpted, so unsampled relationships are omitted.

Main entry points: [`app/models.py`](https://github.com/coreyarnold/libraryn/blob/master/app/models.py) (Catalog and user records), [`app/retry_worker.py`](https://github.com/coreyarnold/libraryn/blob/master/app/retry_worker.py) (Scan retry worker), [`app/routes/api.py`](https://github.com/coreyarnold/libraryn/blob/master/app/routes/api.py) (Book API), [`app/routes/dvd_api.py`](https://github.com/coreyarnold/libraryn/blob/master/app/routes/dvd_api.py) (DVD API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web application"]
  node_book_scanner["Book scanner UI<br/>[scanner.js]"]
  node_dvd_scanner["DVD scanner UI<br/>[dvd-scanner.js]"]
end

subgraph group_books["Book collection"]
  node_book_pages["Book pages<br/>[books.py]"]
  node_book_api["Book API<br/>[api.py]"]
  node_book_sources{{"Book metadata sources"}}
  node_goodreads["Goodreads sync<br/>[api.py]"]
end

subgraph group_dvds["DVD collection"]
  node_dvd_pages["DVD pages<br/>[dvds.py]"]
  node_dvd_api["DVD API<br/>[dvd_api.py]"]
  node_dvd_sources{{"DVD metadata sources"}}
end

subgraph group_accounts["Accounts and lending"]
  node_login["Login and sessions<br/>[auth.py]"]
  node_user_admin["User management<br/>[users.py]"]
  node_book_lending["Book loans<br/>[api.py]"]
  node_dvd_lending["DVD loans<br/>[dvd_api.py]"]
end

subgraph group_shared["Shared services"]
  node_app_factory["Application setup<br/>[__init__.py]"]
  node_configuration["Configuration<br/>[config.py]"]
  node_extensions["Flask extensions<br/>[extensions.py]"]
  node_catalog_models[("Catalog and user records<br/>[models.py]")]
  node_cover_storage["Cover image storage<br/>[covers.py]"]
  node_retry_worker["Scan retry worker<br/>[retry_worker.py]"]
  node_database[("Configured database")]
end

node_member(("Family member"))

node_member -->|"scans ISBN"| node_book_scanner
node_book_scanner -->|"requests lookup and add"| node_book_api
node_book_api -->|"looks up metadata"| node_book_sources
node_book_api -->|"reads and saves"| node_catalog_models
node_book_pages -->|"queries collections"| node_catalog_models
node_member -.->|"scans UPC"| node_dvd_scanner
node_dvd_scanner -.->|"submits scans"| node_dvd_api
node_dvd_api -->|"looks up metadata"| node_dvd_sources
node_dvd_api -->|"reads and saves"| node_catalog_models
node_dvd_pages -->|"queries collections"| node_catalog_models
node_member -->|"authenticates"| node_login
node_login -->|"loads user"| node_catalog_models
node_user_admin -->|"manages users"| node_catalog_models
node_book_lending -->|"updates loans"| node_catalog_models
node_dvd_lending -->|"updates loans"| node_catalog_models
node_member -.->|"connects account"| node_goodreads
node_login -->|"starts sync"| node_goodreads
node_goodreads -->|"updates reading status"| node_catalog_models
node_app_factory -->|"loads settings"| node_configuration
node_app_factory -->|"initializes extensions"| node_extensions
node_app_factory -->|"creates tables"| node_database
node_extensions -->|"provides ORM"| node_database
node_catalog_models -->|"defines ORM models"| node_extensions
node_book_api -->|"stores covers"| node_cover_storage
node_dvd_api -->|"stores covers"| node_cover_storage
node_app_factory -->|"starts worker"| node_retry_worker
node_retry_worker -->|"retries book lookups"| node_book_api
node_retry_worker -->|"retries DVD lookups"| node_dvd_api
node_retry_worker -->|"updates retry records"| node_catalog_models
node_retry_worker -->|"stores covers"| node_cover_storage

click node_book_scanner "https://github.com/coreyarnold/libraryn/blob/master/app/static/js/scanner.js"
click node_dvd_scanner "https://github.com/coreyarnold/libraryn/blob/master/app/static/js/dvd-scanner.js"
click node_book_pages "https://github.com/coreyarnold/libraryn/blob/master/app/routes/books.py"
click node_book_api "https://github.com/coreyarnold/libraryn/blob/master/app/routes/api.py"
click node_dvd_pages "https://github.com/coreyarnold/libraryn/blob/master/app/routes/dvds.py"
click node_dvd_api "https://github.com/coreyarnold/libraryn/blob/master/app/routes/dvd_api.py"
click node_login "https://github.com/coreyarnold/libraryn/blob/master/app/routes/auth.py"
click node_user_admin "https://github.com/coreyarnold/libraryn/blob/master/app/routes/users.py"
click node_book_lending "https://github.com/coreyarnold/libraryn/blob/master/app/routes/api.py"
click node_dvd_lending "https://github.com/coreyarnold/libraryn/blob/master/app/routes/dvd_api.py"
click node_goodreads "https://github.com/coreyarnold/libraryn/blob/master/app/routes/api.py"
click node_app_factory "https://github.com/coreyarnold/libraryn/blob/master/app/__init__.py"
click node_configuration "https://github.com/coreyarnold/libraryn/blob/master/app/config.py"
click node_extensions "https://github.com/coreyarnold/libraryn/blob/master/app/extensions.py"
click node_catalog_models "https://github.com/coreyarnold/libraryn/blob/master/app/models.py"
click node_cover_storage "https://github.com/coreyarnold/libraryn/blob/master/app/covers.py"
click node_retry_worker "https://github.com/coreyarnold/libraryn/blob/master/app/retry_worker.py"

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_book_scanner,node_dvd_scanner toneBlue
class node_book_pages,node_book_api,node_book_sources,node_goodreads toneAmber
class node_dvd_pages,node_dvd_api,node_dvd_sources toneMint
class node_login,node_user_admin,node_book_lending,node_dvd_lending toneRose
class node_app_factory,node_configuration,node_extensions,node_catalog_models,node_cover_storage,node_retry_worker,node_database,node_member toneIndigo
```

## Components

### Web application

- [Book scanner UI](https://github.com/coreyarnold/libraryn/blob/master/app/static/js/scanner.js): `app/static/js/scanner.js`
- [DVD scanner UI](https://github.com/coreyarnold/libraryn/blob/master/app/static/js/dvd-scanner.js): `app/static/js/dvd-scanner.js`

### Book collection

- [Book pages](https://github.com/coreyarnold/libraryn/blob/master/app/routes/books.py): `app/routes/books.py`
- [Book API](https://github.com/coreyarnold/libraryn/blob/master/app/routes/api.py): `app/routes/api.py`
- **Book metadata sources**
- [Goodreads sync](https://github.com/coreyarnold/libraryn/blob/master/app/routes/api.py): `app/routes/api.py`

### DVD collection

- [DVD pages](https://github.com/coreyarnold/libraryn/blob/master/app/routes/dvds.py): `app/routes/dvds.py`
- [DVD API](https://github.com/coreyarnold/libraryn/blob/master/app/routes/dvd_api.py): `app/routes/dvd_api.py`
- **DVD metadata sources**

### Accounts and lending

- [Login and sessions](https://github.com/coreyarnold/libraryn/blob/master/app/routes/auth.py): `app/routes/auth.py`
- [User management](https://github.com/coreyarnold/libraryn/blob/master/app/routes/users.py): `app/routes/users.py`
- [Book loans](https://github.com/coreyarnold/libraryn/blob/master/app/routes/api.py): `app/routes/api.py`
- [DVD loans](https://github.com/coreyarnold/libraryn/blob/master/app/routes/dvd_api.py): `app/routes/dvd_api.py`

### Shared services

- [Application setup](https://github.com/coreyarnold/libraryn/blob/master/app/__init__.py): `app/__init__.py`
- [Configuration](https://github.com/coreyarnold/libraryn/blob/master/app/config.py): `app/config.py`
- [Flask extensions](https://github.com/coreyarnold/libraryn/blob/master/app/extensions.py): `app/extensions.py`
- [Catalog and user records](https://github.com/coreyarnold/libraryn/blob/master/app/models.py): `app/models.py`
- [Cover image storage](https://github.com/coreyarnold/libraryn/blob/master/app/covers.py): `app/covers.py`
- [Scan retry worker](https://github.com/coreyarnold/libraryn/blob/master/app/retry_worker.py): `app/retry_worker.py`
- **Configured database**

### Other components

- **Family member**

## Connections

- Family member → Book scanner UI: scans ISBN (evidence: `README.md`)
- Book scanner UI → Book API: requests lookup and add (evidence: `README.md`)
- Book API → Book metadata sources: looks up metadata (evidence: `app/routes/api.py`)
- Book API → Catalog and user records: reads and saves (evidence: `app/routes/api.py`)
- Book pages → Catalog and user records: queries collections (evidence: `app/routes/books.py`)
- Family member → DVD scanner UI: scans UPC
- DVD scanner UI → DVD API: submits scans
- DVD API → DVD metadata sources: looks up metadata (evidence: `app/routes/dvd_api.py`)
- DVD API → Catalog and user records: reads and saves (evidence: `app/routes/dvd_api.py`)
- DVD pages → Catalog and user records: queries collections (evidence: `app/routes/dvds.py`)
- Family member → Login and sessions: authenticates (evidence: `README.md`)
- Login and sessions → Catalog and user records: loads user (evidence: `app/routes/auth.py`)
- User management → Catalog and user records: manages users (evidence: `app/routes/users.py`)
- Book loans → Catalog and user records: updates loans (evidence: `app/routes/api.py`)
- DVD loans → Catalog and user records: updates loans (evidence: `app/routes/dvd_api.py`)
- Family member → Goodreads sync: connects account
- Login and sessions → Goodreads sync: starts sync (evidence: `app/routes/auth.py`)
- Goodreads sync → Catalog and user records: updates reading status (evidence: `app/routes/api.py`)
- Application setup → Configuration: loads settings (evidence: `app/__init__.py`)
- Application setup → Flask extensions: initializes extensions (evidence: `app/__init__.py`)
- Application setup → Configured database: creates tables (evidence: `app/__init__.py`)
- Flask extensions → Configured database: provides ORM (evidence: `app/extensions.py`)
- Catalog and user records → Flask extensions: defines ORM models (evidence: `app/models.py`)
- Book API → Cover image storage: stores covers (evidence: `app/routes/api.py`)
- DVD API → Cover image storage: stores covers (evidence: `app/routes/dvd_api.py`)
- Application setup → Scan retry worker: starts worker (evidence: `app/__init__.py`)
- Scan retry worker → Book API: retries book lookups (evidence: `app/retry_worker.py`)
- Scan retry worker → DVD API: retries DVD lookups (evidence: `app/retry_worker.py`)
- Scan retry worker → Catalog and user records: updates retry records (evidence: `app/retry_worker.py`)
- Scan retry worker → Cover image storage: stores covers (evidence: `app/retry_worker.py`)