# aprxty3/project-baca architecture

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

- Interactive diagram: https://gitdiagram.com/aprxty3/project-baca
- Repository: https://github.com/aprxty3/project-baca

## Overview

Project Baca is an offline-first digital reader for public-domain classics. Readers browse a catalog, open and paginate through books, and can save progress; the web client also supports authentication and offline storage. Separate API capabilities include semantic quote discovery, chapter recaps and insight cards, reading streaks and badges, and administration. Admin EPUB jobs are consumed by a Python worker for parsing, chunking, embedding, and publishing. The graph follows documented routes and sampled calls; unsampled feature wiring is intentionally left general.

Main entry points: [`crates/server/src/lib.rs`](https://github.com/aprxty3/project-baca/blob/main/crates/server/src/lib.rs) (REST API), [`crates/web/src/lib.rs`](https://github.com/aprxty3/project-baca/blob/main/crates/web/src/lib.rs) (Web application), [`crates/web/src/api/mod.rs`](https://github.com/aprxty3/project-baca/blob/main/crates/web/src/api/mod.rs) (Web API client), [`python_worker/worker.py`](https://github.com/aprxty3/project-baca/blob/main/python_worker/worker.py) (EPUB worker)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_reader["Reader experience"]
  node_webapp["Web application<br/>[lib.rs]"]
  node_catalog["Catalog pages<br/>[home.rs]"]
  node_book["Book details<br/>[book.rs]"]
  node_read["Pagination reader<br/>[reader.rs]"]
  node_profile["Profile and insights<br/>[profile.rs]"]
  node_offline[("Browser storage<br/>[mod.rs]")]
  node_webapi["Web API client<br/>[mod.rs]"]
end

subgraph group_api["API and domain"]
  node_server["REST API<br/>[lib.rs]"]
  node_authroutes["Authentication<br/>[auth.rs]"]
  node_bookroutes["Catalog and reading<br/>[books.rs]"]
  node_insightroutes["Insights and quotes<br/>[insights.rs]"]
  node_progressroutes["Progress and badges<br/>[progress.rs]"]
  node_adminroutes["Admin jobs<br/>[admin.rs]"]
end

subgraph group_infra["Persistence and services"]
  node_repos["Data repositories<br/>[mod.rs]"]
  node_bookrepo["Catalog queries<br/>[book_repository.rs]"]
  node_quoterepo["Quotes and recaps"]
  node_progressrepo["Reading activity"]
  node_userrepo["Account records<br/>[user_repository.rs]"]
  node_postgres[("PostgreSQL")]
  node_embedding["Embedding provider<br/>[embedding.rs]"]
end

subgraph group_ingestion["EPUB ingestion"]
  node_redis["Redis streams"]
  node_worker["EPUB worker<br/>[worker.py]"]
  node_objectstore[("EPUB object storage<br/>[s3.rs]")]
end

node_reader(("Reader"))
node_gemini{{"Gemini API"}}

node_reader -->|"opens"| node_webapp
node_webapp -->|"routes to"| node_catalog
node_webapp -->|"routes to"| node_book
node_webapp -->|"routes to"| node_read
node_webapp -->|"routes to"| node_profile
node_catalog -->|"requests catalog"| node_webapi
node_book -->|"requests details"| node_webapi
node_read -->|"syncs progress"| node_webapi
node_read -->|"reads and writes"| node_offline
node_profile -->|"requests account data"| node_webapi
node_webapi -->|"calls"| node_server
node_server -->|"dispatches"| node_authroutes
node_server -->|"dispatches"| node_bookroutes
node_server -->|"dispatches"| node_insightroutes
node_server -->|"dispatches"| node_progressroutes
node_server -->|"dispatches"| node_adminroutes
node_authroutes -->|"reads and writes"| node_userrepo
node_bookroutes -->|"queries"| node_bookrepo
node_insightroutes -->|"queries"| node_quoterepo
node_progressroutes -->|"updates"| node_progressrepo
node_bookrepo -->|"queries"| node_postgres
node_quoterepo -->|"queries"| node_postgres
node_progressrepo -->|"reads and writes"| node_postgres
node_userrepo -->|"reads and writes"| node_postgres
node_adminroutes -->|"stores uploads"| node_objectstore
node_adminroutes -->|"queues jobs"| node_redis
node_worker -->|"consumes jobs"| node_redis
node_worker -->|"downloads EPUB"| node_objectstore
node_worker -->|"publishes book data"| node_postgres
node_worker -.->|"requests embeddings"| node_gemini
node_embedding -.->|"sends embedding requests"| node_gemini

click node_webapp "https://github.com/aprxty3/project-baca/blob/main/crates/web/src/lib.rs"
click node_catalog "https://github.com/aprxty3/project-baca/blob/main/crates/web/src/pages/home.rs"
click node_book "https://github.com/aprxty3/project-baca/blob/main/crates/web/src/pages/book.rs"
click node_read "https://github.com/aprxty3/project-baca/blob/main/crates/web/src/pages/reader.rs"
click node_profile "https://github.com/aprxty3/project-baca/blob/main/crates/web/src/pages/profile.rs"
click node_offline "https://github.com/aprxty3/project-baca/blob/main/crates/web/src/storage/mod.rs"
click node_webapi "https://github.com/aprxty3/project-baca/blob/main/crates/web/src/api/mod.rs"
click node_server "https://github.com/aprxty3/project-baca/blob/main/crates/server/src/lib.rs"
click node_authroutes "https://github.com/aprxty3/project-baca/blob/main/crates/server/src/routes/auth.rs"
click node_bookroutes "https://github.com/aprxty3/project-baca/blob/main/crates/server/src/routes/books.rs"
click node_insightroutes "https://github.com/aprxty3/project-baca/blob/main/crates/server/src/routes/insights.rs"
click node_progressroutes "https://github.com/aprxty3/project-baca/blob/main/crates/server/src/routes/progress.rs"
click node_adminroutes "https://github.com/aprxty3/project-baca/blob/main/crates/server/src/routes/admin.rs"
click node_repos "https://github.com/aprxty3/project-baca/blob/main/crates/infra/src/repositories/mod.rs"
click node_bookrepo "https://github.com/aprxty3/project-baca/blob/main/crates/infra/src/repositories/book_repository.rs"
click node_quoterepo "https://github.com/aprxty3/project-baca/blob/main/crates/infra/src/repositories/quote_repository.rs"
click node_progressrepo "https://github.com/aprxty3/project-baca/blob/main/crates/infra/src/repositories/progress_repository.rs"
click node_userrepo "https://github.com/aprxty3/project-baca/blob/main/crates/infra/src/repositories/user_repository.rs"
click node_worker "https://github.com/aprxty3/project-baca/blob/main/python_worker/worker.py"
click node_objectstore "https://github.com/aprxty3/project-baca/blob/main/crates/infra/src/storage/s3.rs"
click node_embedding "https://github.com/aprxty3/project-baca/blob/main/crates/infra/src/ai/embedding.rs"

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_webapp,node_catalog,node_book,node_read,node_profile,node_offline,node_webapi toneBlue
class node_server,node_authroutes,node_bookroutes,node_insightroutes,node_progressroutes,node_adminroutes toneAmber
class node_repos,node_bookrepo,node_quoterepo,node_progressrepo,node_userrepo,node_postgres,node_embedding,node_gemini toneMint
class node_redis,node_worker,node_objectstore toneRose
class node_reader toneIndigo
```

## Components

### Reader experience

- [Web application](https://github.com/aprxty3/project-baca/blob/main/crates/web/src/lib.rs): `crates/web/src/lib.rs`
- [Catalog pages](https://github.com/aprxty3/project-baca/blob/main/crates/web/src/pages/home.rs): `crates/web/src/pages/home.rs`
- [Book details](https://github.com/aprxty3/project-baca/blob/main/crates/web/src/pages/book.rs): `crates/web/src/pages/book.rs`
- [Pagination reader](https://github.com/aprxty3/project-baca/blob/main/crates/web/src/pages/reader.rs): `crates/web/src/pages/reader.rs`
- [Profile and insights](https://github.com/aprxty3/project-baca/blob/main/crates/web/src/pages/profile.rs): `crates/web/src/pages/profile.rs`
- [Browser storage](https://github.com/aprxty3/project-baca/blob/main/crates/web/src/storage/mod.rs): `crates/web/src/storage/mod.rs`
- [Web API client](https://github.com/aprxty3/project-baca/blob/main/crates/web/src/api/mod.rs): `crates/web/src/api/mod.rs`

### API and domain

- [REST API](https://github.com/aprxty3/project-baca/blob/main/crates/server/src/lib.rs): `crates/server/src/lib.rs`
- [Authentication](https://github.com/aprxty3/project-baca/blob/main/crates/server/src/routes/auth.rs): `crates/server/src/routes/auth.rs`
- [Catalog and reading](https://github.com/aprxty3/project-baca/blob/main/crates/server/src/routes/books.rs): `crates/server/src/routes/books.rs`
- [Insights and quotes](https://github.com/aprxty3/project-baca/blob/main/crates/server/src/routes/insights.rs): `crates/server/src/routes/insights.rs`
- [Progress and badges](https://github.com/aprxty3/project-baca/blob/main/crates/server/src/routes/progress.rs): `crates/server/src/routes/progress.rs`
- [Admin jobs](https://github.com/aprxty3/project-baca/blob/main/crates/server/src/routes/admin.rs): `crates/server/src/routes/admin.rs`

### Persistence and services

- [Data repositories](https://github.com/aprxty3/project-baca/blob/main/crates/infra/src/repositories/mod.rs): `crates/infra/src/repositories/mod.rs`
- [Catalog queries](https://github.com/aprxty3/project-baca/blob/main/crates/infra/src/repositories/book_repository.rs): `crates/infra/src/repositories/book_repository.rs`
- [Quotes and recaps](https://github.com/aprxty3/project-baca/blob/main/crates/infra/src/repositories/quote_repository.rs): `crates/infra/src/repositories/quote_repository.rs`
- [Reading activity](https://github.com/aprxty3/project-baca/blob/main/crates/infra/src/repositories/progress_repository.rs): `crates/infra/src/repositories/progress_repository.rs`
- [Account records](https://github.com/aprxty3/project-baca/blob/main/crates/infra/src/repositories/user_repository.rs): `crates/infra/src/repositories/user_repository.rs`
- **PostgreSQL**
- [Embedding provider](https://github.com/aprxty3/project-baca/blob/main/crates/infra/src/ai/embedding.rs): `crates/infra/src/ai/embedding.rs`

### EPUB ingestion

- **Redis streams**
- [EPUB worker](https://github.com/aprxty3/project-baca/blob/main/python_worker/worker.py): `python_worker/worker.py`
- [EPUB object storage](https://github.com/aprxty3/project-baca/blob/main/crates/infra/src/storage/s3.rs): `crates/infra/src/storage/s3.rs`

### Other components

- **Reader**
- **Gemini API**

## Connections

- Reader → Web application: opens
- Web application → Catalog pages: routes to
- Web application → Book details: routes to
- Web application → Pagination reader: routes to
- Web application → Profile and insights: routes to
- Catalog pages → Web API client: requests catalog
- Book details → Web API client: requests details
- Pagination reader → Web API client: syncs progress
- Pagination reader → Browser storage: reads and writes
- Profile and insights → Web API client: requests account data
- Web API client → REST API: calls
- REST API → Authentication: dispatches
- REST API → Catalog and reading: dispatches
- REST API → Insights and quotes: dispatches
- REST API → Progress and badges: dispatches
- REST API → Admin jobs: dispatches
- Authentication → Account records: reads and writes
- Catalog and reading → Catalog queries: queries
- Insights and quotes → Quotes and recaps: queries
- Progress and badges → Reading activity: updates
- Catalog queries → PostgreSQL: queries
- Quotes and recaps → PostgreSQL: queries
- Reading activity → PostgreSQL: reads and writes
- Account records → PostgreSQL: reads and writes
- Admin jobs → EPUB object storage: stores uploads
- Admin jobs → Redis streams: queues jobs
- EPUB worker → Redis streams: consumes jobs
- EPUB worker → EPUB object storage: downloads EPUB
- EPUB worker → PostgreSQL: publishes book data
- EPUB worker → Gemini API: requests embeddings
- Embedding provider → Gemini API: sends embedding requests