# mozzo1000/booklogr architecture

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

- Interactive diagram: https://gitdiagram.com/mozzo1000/booklogr
- Repository: https://github.com/mozzo1000/booklogr

## Overview

BookLogr is a self-hosted personal-library web app. Users authenticate, search or manually add books, organize them by reading status, track progress and ratings, and optionally publish a profile; notes, custom fields, and data export extend that workflow. The React app calls a Flask API whose route handlers operate on SQLAlchemy models. The README documents Mastodon sharing and multiple export formats; task execution is visible in the sampled API excerpt. Frontend links for several documented features are not shown, so those connections rely on README evidence.

Main entry points: [`api/app.py`](https://github.com/mozzo1000/booklogr/blob/main/api/app.py) (Flask app and routing), [`api/models.py`](https://github.com/mozzo1000/booklogr/blob/main/api/models.py) (Library data models), [`api/routes/books.py`](https://github.com/mozzo1000/booklogr/blob/main/api/routes/books.py) (Book endpoints), [`api/routes/tasks.py`](https://github.com/mozzo1000/booklogr/blob/main/api/routes/tasks.py) (Background tasks)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web application"]
  node_app["App routing<br/>[App.jsx]"]
end

subgraph group_catalog["Library workflows"]
  node_library_ui["Library and book views<br/>[Library.jsx]"]
  node_book_service["Book API client<br/>[books.service.jsx]"]
  node_search_hook["Book search hook<br/>[useSearch.js]"]
  node_notes["Notes and quotes<br/>[notes.py]"]
  node_fields["Custom book fields<br/>[fields.py]"]
end

subgraph group_identity["Accounts and profiles"]
  node_auth_ui["Authentication client<br/>[auth.service.jsx]"]
  node_profile_page["Profile page<br/>[Profile.jsx]"]
end

subgraph group_api["API services"]
  node_book_routes["Book endpoints<br/>[books.py]"]
  node_provider["OpenLibrary lookup<br/>[book_provider.py]"]
  node_auth_routes["Auth endpoints<br/>[auth_route.py]"]
  node_user_routes["User endpoints<br/>[user_route.py]"]
  node_profile_routes["Public profiles<br/>[profiles.py]"]
  node_settings["User settings<br/>[settings.py]"]
  node_files["Import and export files<br/>[files.py]"]
  node_tasks["Background tasks<br/>[tasks.py]"]
  node_flask_app["Flask app and routing<br/>[app.py]"]
end

subgraph group_data["Persistence and tasks"]
  node_models["Library data models<br/>[models.py]"]
  node_auth_models["Account data models<br/>[models.py]"]
  node_database[("SQL database")]
end

node_reader(("Library user"))
node_mastodon(("Mastodon"))

node_reader -->|"uses"| node_app
node_app -->|"routes to"| node_library_ui
node_library_ui -.->|"requests books"| node_book_service
node_search_hook -->|"queries"| node_book_service
node_book_service -->|"calls API"| node_book_routes
node_book_routes -->|"looks up books"| node_provider
node_book_routes -->|"reads and writes"| node_models
node_notes -.->|"reads and writes"| node_models
node_fields -.->|"reads and writes"| node_models
node_auth_ui -->|"calls API"| node_auth_routes
node_auth_routes -->|"uses"| node_auth_models
node_user_routes -->|"uses"| node_auth_models
node_profile_page -.->|"loads profile"| node_profile_routes
node_profile_routes -.->|"reads profile data"| node_models
node_settings -.->|"reads and writes"| node_models
node_files -.->|"imports and exports"| node_models
node_tasks -->|"records task"| node_models
node_tasks -.->|"shares progress"| node_mastodon
node_flask_app -->|"registers"| node_book_routes
node_flask_app -->|"registers"| node_profile_routes
node_flask_app -->|"registers"| node_auth_routes
node_flask_app -->|"registers"| node_user_routes
node_flask_app -->|"registers"| node_notes
node_flask_app -->|"registers"| node_tasks
node_flask_app -->|"registers"| node_files
node_flask_app -->|"registers"| node_settings
node_flask_app -->|"registers"| node_fields
node_models -->|"persists data"| node_database
node_auth_models -->|"persists accounts"| node_database

click node_app "https://github.com/mozzo1000/booklogr/blob/main/web/src/App.jsx"
click node_library_ui "https://github.com/mozzo1000/booklogr/blob/main/web/src/pages/Library.jsx"
click node_book_service "https://github.com/mozzo1000/booklogr/blob/main/web/src/services/books.service.jsx"
click node_search_hook "https://github.com/mozzo1000/booklogr/blob/main/web/src/hooks/useSearch.js"
click node_book_routes "https://github.com/mozzo1000/booklogr/blob/main/api/routes/books.py"
click node_provider "https://github.com/mozzo1000/booklogr/blob/main/api/book_provider.py"
click node_notes "https://github.com/mozzo1000/booklogr/blob/main/api/routes/notes.py"
click node_fields "https://github.com/mozzo1000/booklogr/blob/main/api/routes/fields.py"
click node_auth_ui "https://github.com/mozzo1000/booklogr/blob/main/web/src/services/auth.service.jsx"
click node_auth_routes "https://github.com/mozzo1000/booklogr/blob/main/api/auth/auth_route.py"
click node_user_routes "https://github.com/mozzo1000/booklogr/blob/main/api/auth/user_route.py"
click node_profile_page "https://github.com/mozzo1000/booklogr/blob/main/web/src/pages/Profile.jsx"
click node_profile_routes "https://github.com/mozzo1000/booklogr/blob/main/api/routes/profiles.py"
click node_settings "https://github.com/mozzo1000/booklogr/blob/main/api/routes/settings.py"
click node_files "https://github.com/mozzo1000/booklogr/blob/main/api/routes/files.py"
click node_tasks "https://github.com/mozzo1000/booklogr/blob/main/api/routes/tasks.py"
click node_models "https://github.com/mozzo1000/booklogr/blob/main/api/models.py"
click node_auth_models "https://github.com/mozzo1000/booklogr/blob/main/api/auth/models.py"
click node_flask_app "https://github.com/mozzo1000/booklogr/blob/main/api/app.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_app,node_reader toneBlue
class node_library_ui,node_book_service,node_search_hook,node_notes,node_fields toneAmber
class node_auth_ui,node_profile_page toneMint
class node_book_routes,node_provider,node_auth_routes,node_user_routes,node_profile_routes,node_settings,node_files,node_tasks,node_flask_app toneRose
class node_models,node_auth_models,node_database,node_mastodon toneIndigo
```

## Components

### Web application

- [App routing](https://github.com/mozzo1000/booklogr/blob/main/web/src/App.jsx): `web/src/App.jsx`

### Library workflows

- [Library and book views](https://github.com/mozzo1000/booklogr/blob/main/web/src/pages/Library.jsx): `web/src/pages/Library.jsx`
- [Book API client](https://github.com/mozzo1000/booklogr/blob/main/web/src/services/books.service.jsx): `web/src/services/books.service.jsx`
- [Book search hook](https://github.com/mozzo1000/booklogr/blob/main/web/src/hooks/useSearch.js): `web/src/hooks/useSearch.js`
- [Notes and quotes](https://github.com/mozzo1000/booklogr/blob/main/api/routes/notes.py): `api/routes/notes.py`
- [Custom book fields](https://github.com/mozzo1000/booklogr/blob/main/api/routes/fields.py): `api/routes/fields.py`

### Accounts and profiles

- [Authentication client](https://github.com/mozzo1000/booklogr/blob/main/web/src/services/auth.service.jsx): `web/src/services/auth.service.jsx`
- [Profile page](https://github.com/mozzo1000/booklogr/blob/main/web/src/pages/Profile.jsx): `web/src/pages/Profile.jsx`

### API services

- [Book endpoints](https://github.com/mozzo1000/booklogr/blob/main/api/routes/books.py): `api/routes/books.py`
- [OpenLibrary lookup](https://github.com/mozzo1000/booklogr/blob/main/api/book_provider.py): `api/book_provider.py`
- [Auth endpoints](https://github.com/mozzo1000/booklogr/blob/main/api/auth/auth_route.py): `api/auth/auth_route.py`
- [User endpoints](https://github.com/mozzo1000/booklogr/blob/main/api/auth/user_route.py): `api/auth/user_route.py`
- [Public profiles](https://github.com/mozzo1000/booklogr/blob/main/api/routes/profiles.py): `api/routes/profiles.py`
- [User settings](https://github.com/mozzo1000/booklogr/blob/main/api/routes/settings.py): `api/routes/settings.py`
- [Import and export files](https://github.com/mozzo1000/booklogr/blob/main/api/routes/files.py): `api/routes/files.py`
- [Background tasks](https://github.com/mozzo1000/booklogr/blob/main/api/routes/tasks.py): `api/routes/tasks.py`
- [Flask app and routing](https://github.com/mozzo1000/booklogr/blob/main/api/app.py): `api/app.py`

### Persistence and tasks

- [Library data models](https://github.com/mozzo1000/booklogr/blob/main/api/models.py): `api/models.py`
- [Account data models](https://github.com/mozzo1000/booklogr/blob/main/api/auth/models.py): `api/auth/models.py`
- **SQL database**

### Other components

- **Library user**
- **Mastodon**

## Connections

- Library user → App routing: uses (evidence: `web/src/App.jsx`)
- App routing → Library and book views: routes to (evidence: `web/src/App.jsx`)
- Library and book views → Book API client: requests books
- Book search hook → Book API client: queries (evidence: `web/src/hooks/useSearch.js`)
- Book API client → Book endpoints: calls API (evidence: `web/src/services/books.service.jsx`)
- Book endpoints → OpenLibrary lookup: looks up books (evidence: `api/routes/books.py`)
- Book endpoints → Library data models: reads and writes (evidence: `api/routes/books.py`)
- Notes and quotes → Library data models: reads and writes (evidence: `api/routes/notes.py`)
- Custom book fields → Library data models: reads and writes (evidence: `api/routes/fields.py`)
- Authentication client → Auth endpoints: calls API (evidence: `web/src/services/auth.service.jsx`)
- Auth endpoints → Account data models: uses (evidence: `api/auth/auth_route.py`)
- User endpoints → Account data models: uses (evidence: `api/auth/user_route.py`)
- Profile page → Public profiles: loads profile
- Public profiles → Library data models: reads profile data (evidence: `api/routes/profiles.py`)
- User settings → Library data models: reads and writes (evidence: `api/routes/settings.py`)
- Import and export files → Library data models: imports and exports (evidence: `api/routes/files.py`)
- Background tasks → Library data models: records task (evidence: `api/routes/tasks.py`)
- Background tasks → Mastodon: shares progress
- Flask app and routing → Book endpoints: registers (evidence: `api/app.py`)
- Flask app and routing → Public profiles: registers (evidence: `api/app.py`)
- Flask app and routing → Auth endpoints: registers (evidence: `api/app.py`)
- Flask app and routing → User endpoints: registers (evidence: `api/app.py`)
- Flask app and routing → Notes and quotes: registers (evidence: `api/app.py`)
- Flask app and routing → Background tasks: registers (evidence: `api/app.py`)
- Flask app and routing → Import and export files: registers (evidence: `api/app.py`)
- Flask app and routing → User settings: registers (evidence: `api/app.py`)
- Flask app and routing → Custom book fields: registers (evidence: `api/app.py`)
- Library data models → SQL database: persists data (evidence: `api/models.py`)
- Account data models → SQL database: persists accounts (evidence: `api/auth/models.py`)
