# patrick-1810/booklens-backend architecture

> Architecture diagram of the GitHub repository patrick-1810/booklens-backend, 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/patrick-1810/booklens-backend
- Repository: https://github.com/patrick-1810/booklens-backend

## Overview

BookLens is a document-digitization backend. A client submits an image to the OCR routes, which invoke image/OCR processing and the documented dictionary-validation stage, then return structured text and persist document history. The API also supports account authentication, document management and comments, plus searchable-PDF and visual-overlay exports. The README documents the product stages; the sampled OCR excerpt is partial, so some processing and export links rely on the SOURCE INDEX rather than visible call sites.

Main entry points: [`app/routes/ocr.py`](https://github.com/patrick-1810/booklens-backend/blob/main/app/routes/ocr.py) (OCR and document routes), [`app/routes/auth.py`](https://github.com/patrick-1810/booklens-backend/blob/main/app/routes/auth.py) (Authentication routes), [`app/core/security.py`](https://github.com/patrick-1810/booklens-backend/blob/main/app/core/security.py) (JWT security), [`app/database/models.py`](https://github.com/patrick-1810/booklens-backend/blob/main/app/database/models.py) (User and document entities)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and Accounts"]
  node_app["FastAPI application<br/>[main.py]"]
  node_ocr["OCR and document routes<br/>[ocr.py]"]
  node_auth["Authentication routes<br/>[auth.py]"]
  node_dictionary["Dictionary autocomplete<br/>[dictionary.py]"]
  node_security["JWT security<br/>[security.py]"]
  node_schemas["Request and response schemas<br/>[schemas.py]"]
end

subgraph group_processing["Document Processing"]
  node_processor["Image and OCR processor<br/>[processor.py]"]
  node_docling["Docling conversion"]
end

subgraph group_persistence["Persistence"]
  node_dbconfig["Database configuration<br/>[config.py]"]
  node_models["User and document entities<br/>[models.py]"]
  node_database[("Relational database")]
end

subgraph group_outputs["Document Outputs"]
  node_pdf["Searchable PDF and overlay<br/>[pdf_writer.py]"]
end

node_client(("Frontend client"))

node_client -->|"sends API requests"| node_app
node_app -->|"registers routes"| node_ocr
node_app -->|"registers routes"| node_auth
node_app -->|"registers routes"| node_dictionary
node_ocr -->|"invokes processing"| node_processor
node_ocr -->|"invokes conversion"| node_docling
node_ocr -->|"uses export tools"| node_pdf
node_ocr -->|"reads and writes documents"| node_models
node_ocr -->|"requires authenticated user"| node_security
node_ocr -.->|"validates extracted words"| node_dictionary
node_auth -->|"creates and verifies tokens"| node_security
node_auth -->|"queries users"| node_models
node_auth -->|"gets database session"| node_dbconfig
node_auth -->|"accepts typed inputs"| node_schemas
node_security -->|"loads current user"| node_models
node_security -->|"gets database session"| node_dbconfig
node_security -->|"returns token data"| node_schemas
node_dbconfig -.->|"creates engine sessions"| node_database
node_models -->|"uses ORM base"| node_dbconfig
node_models -.->|"defines persisted entities"| node_database

click node_app "https://github.com/patrick-1810/booklens-backend/blob/main/app/main.py"
click node_ocr "https://github.com/patrick-1810/booklens-backend/blob/main/app/routes/ocr.py"
click node_auth "https://github.com/patrick-1810/booklens-backend/blob/main/app/routes/auth.py"
click node_dictionary "https://github.com/patrick-1810/booklens-backend/blob/main/app/routes/dictionary.py"
click node_security "https://github.com/patrick-1810/booklens-backend/blob/main/app/core/security.py"
click node_schemas "https://github.com/patrick-1810/booklens-backend/blob/main/app/core/schemas.py"
click node_processor "https://github.com/patrick-1810/booklens-backend/blob/main/app/core/processor.py"
click node_docling "https://github.com/patrick-1810/booklens-backend/blob/main/app/core/docling_processor.py"
click node_pdf "https://github.com/patrick-1810/booklens-backend/blob/main/app/core/pdf_writer.py"
click node_dbconfig "https://github.com/patrick-1810/booklens-backend/blob/main/app/database/config.py"
click node_models "https://github.com/patrick-1810/booklens-backend/blob/main/app/database/models.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_ocr,node_auth,node_dictionary,node_security,node_schemas,node_client toneBlue
class node_processor,node_docling toneAmber
class node_dbconfig,node_models,node_database toneMint
class node_pdf toneRose
```

## Components

### API and Accounts

- [FastAPI application](https://github.com/patrick-1810/booklens-backend/blob/main/app/main.py): `app/main.py`
- [OCR and document routes](https://github.com/patrick-1810/booklens-backend/blob/main/app/routes/ocr.py): `app/routes/ocr.py`
- [Authentication routes](https://github.com/patrick-1810/booklens-backend/blob/main/app/routes/auth.py): `app/routes/auth.py`
- [Dictionary autocomplete](https://github.com/patrick-1810/booklens-backend/blob/main/app/routes/dictionary.py): `app/routes/dictionary.py`
- [JWT security](https://github.com/patrick-1810/booklens-backend/blob/main/app/core/security.py): `app/core/security.py`
- [Request and response schemas](https://github.com/patrick-1810/booklens-backend/blob/main/app/core/schemas.py): `app/core/schemas.py`

### Document Processing

- [Image and OCR processor](https://github.com/patrick-1810/booklens-backend/blob/main/app/core/processor.py): `app/core/processor.py`
- [Docling conversion](https://github.com/patrick-1810/booklens-backend/blob/main/app/core/docling_processor.py): `app/core/docling_processor.py`

### Persistence

- [Database configuration](https://github.com/patrick-1810/booklens-backend/blob/main/app/database/config.py): `app/database/config.py`
- [User and document entities](https://github.com/patrick-1810/booklens-backend/blob/main/app/database/models.py): `app/database/models.py`
- **Relational database**

### Document Outputs

- [Searchable PDF and overlay](https://github.com/patrick-1810/booklens-backend/blob/main/app/core/pdf_writer.py): `app/core/pdf_writer.py`

### Other components

- **Frontend client**

## Connections

- Frontend client → FastAPI application: sends API requests (evidence: `README.md`)
- FastAPI application → OCR and document routes: registers routes (evidence: `app/main.py`)
- FastAPI application → Authentication routes: registers routes (evidence: `app/main.py`)
- FastAPI application → Dictionary autocomplete: registers routes (evidence: `app/main.py`)
- OCR and document routes → Image and OCR processor: invokes processing (evidence: `app/routes/ocr.py`)
- OCR and document routes → Docling conversion: invokes conversion (evidence: `app/routes/ocr.py`)
- OCR and document routes → Searchable PDF and overlay: uses export tools (evidence: `app/routes/ocr.py`)
- OCR and document routes → User and document entities: reads and writes documents (evidence: `app/routes/ocr.py`)
- OCR and document routes → JWT security: requires authenticated user (evidence: `app/routes/ocr.py`)
- OCR and document routes → Dictionary autocomplete: validates extracted words (evidence: `README.md`)
- Authentication routes → JWT security: creates and verifies tokens (evidence: `app/routes/auth.py`)
- Authentication routes → User and document entities: queries users (evidence: `app/routes/auth.py`)
- Authentication routes → Database configuration: gets database session (evidence: `app/routes/auth.py`)
- Authentication routes → Request and response schemas: accepts typed inputs (evidence: `app/routes/auth.py`)
- JWT security → User and document entities: loads current user (evidence: `app/core/security.py`)
- JWT security → Database configuration: gets database session (evidence: `app/core/security.py`)
- JWT security → Request and response schemas: returns token data (evidence: `app/core/security.py`)
- Database configuration → Relational database: creates engine sessions
- User and document entities → Database configuration: uses ORM base (evidence: `app/database/models.py`)
- User and document entities → Relational database: defines persisted entities
