# illyadd/pdf-share architecture

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

- Interactive diagram: https://gitdiagram.com/illyadd/pdf-share
- Repository: https://github.com/illyadd/pdf-share

## Overview

PDF+ is a Django monolith for managing, reading, and sharing PDF books in a learning setting. A user enters through account access, then browses a personal/shared/catalog library; upload forms validate PDFs before saving, and access rules determine which books are visible. The reader renders PDFs in-browser and stores per-user highlights and notes. Separate sharing workflows grant class or token-link access, while the JWT REST API supports catalog/file access and offline delta sync. Edges reflect README statements and source references; unsampled routes and templates limit detail on their exact dispatch and rendering connections.

Main entry points: [`PDF+/api/sync.py`](https://github.com/illyadd/pdf-share/blob/master/PDF%2B/api/sync.py) (Delta sync), [`PDF+/book_library/models.py`](https://github.com/illyadd/pdf-share/blob/master/PDF%2B/book_library/models.py) (Books and folders), [`PDF+/book_library/views.py`](https://github.com/illyadd/pdf-share/blob/master/PDF%2B/book_library/views.py) (Library browsing), [`PDF+/users/views.py`](https://github.com/illyadd/pdf-share/blob/master/PDF%2B/users/views.py) (Account access)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_accounts["Accounts"]
  node_account_flow["Account access<br/>[views.py]"]
  node_user_model[("User accounts<br/>[models.py]")]
end

subgraph group_library["PDF library"]
  node_library_flow["Library browsing<br/>[views.py]"]
  node_book_model[("Books and folders<br/>[models.py]")]
  node_upload_form["Upload forms<br/>[forms.py]"]
  node_pdf_inspection["PDF inspection<br/>[pdf.py]"]
  node_access_rules["Visibility rules<br/>[access.py]"]
  node_file_storage["PDF storage<br/>[signals.py]"]
end

subgraph group_collaboration["Sharing"]
  node_sharing_flow["Sharing management<br/>[views.py]"]
  node_sharing_forms["Sharing forms<br/>[forms.py]"]
  node_sharing_records[("Groups and links<br/>[models.py]")]
end

subgraph group_reading["Reader and annotations"]
  node_reader_ui["Browser reader<br/>[reader.js]"]
  node_annotation_routes["Annotation JSON API<br/>[api.py]"]
  node_annotation_validation["Payload validation<br/>[validators.py]"]
  node_annotation_records[("User annotation layers<br/>[models.py]")]
end

subgraph group_offline["Offline API"]
  node_rest_routes["JWT REST endpoints<br/>[views.py]"]
  node_sync_engine["Delta sync<br/>[sync.py]"]
  node_sync_tombstones[("Deleted annotation markers<br/>[models.py]")]
end

node_visitor(("User"))
node_mobile_client(("Mobile/offline client"))
node_google["Google OAuth"]

node_visitor -->|"uses"| node_account_flow
node_account_flow -->|"authenticates"| node_user_model
node_account_flow -->|"signs in via"| node_google
node_visitor -->|"browses"| node_library_flow
node_library_flow -->|"filters by visibility"| node_access_rules
node_library_flow -->|"reads and manages"| node_book_model
node_library_flow -->|"validates upload"| node_upload_form
node_upload_form -->|"inspects PDF"| node_pdf_inspection
node_upload_form -->|"saves book"| node_book_model
node_book_model -->|"stores and deletes files"| node_file_storage
node_visitor -->|"manages access"| node_sharing_flow
node_sharing_flow -->|"uses forms"| node_sharing_forms
node_sharing_flow -->|"updates sharing records"| node_sharing_records
node_sharing_records -->|"targets books and folders"| node_book_model
node_access_rules -->|"checks grants and links"| node_sharing_records
node_visitor -->|"reads books"| node_reader_ui
node_reader_ui -->|"sends annotation requests"| node_annotation_routes
node_annotation_routes -->|"validates payload"| node_annotation_validation
node_annotation_routes -->|"reads and writes"| node_annotation_records
node_mobile_client -->|"calls REST API"| node_rest_routes
node_rest_routes -->|"dispatches sync"| node_sync_engine
node_sync_engine -->|"filters visible content"| node_access_rules
node_sync_engine -->|"pulls book state"| node_book_model
node_sync_engine -->|"validates changes"| node_annotation_validation
node_sync_engine -->|"syncs annotations"| node_annotation_records
node_sync_engine -->|"tracks deletions"| node_sync_tombstones

click node_account_flow "https://github.com/illyadd/pdf-share/blob/master/PDF%2B/users/views.py"
click node_user_model "https://github.com/illyadd/pdf-share/blob/master/PDF%2B/users/models.py"
click node_library_flow "https://github.com/illyadd/pdf-share/blob/master/PDF%2B/book_library/views.py"
click node_book_model "https://github.com/illyadd/pdf-share/blob/master/PDF%2B/book_library/models.py"
click node_upload_form "https://github.com/illyadd/pdf-share/blob/master/PDF%2B/book_library/forms.py"
click node_pdf_inspection "https://github.com/illyadd/pdf-share/blob/master/PDF%2B/book_library/pdf.py"
click node_access_rules "https://github.com/illyadd/pdf-share/blob/master/PDF%2B/book_library/access.py"
click node_file_storage "https://github.com/illyadd/pdf-share/blob/master/PDF%2B/book_library/signals.py"
click node_sharing_flow "https://github.com/illyadd/pdf-share/blob/master/PDF%2B/sharing/views.py"
click node_sharing_forms "https://github.com/illyadd/pdf-share/blob/master/PDF%2B/sharing/forms.py"
click node_sharing_records "https://github.com/illyadd/pdf-share/blob/master/PDF%2B/sharing/models.py"
click node_reader_ui "https://github.com/illyadd/pdf-share/blob/master/PDF%2B/static/js/reader.js"
click node_annotation_routes "https://github.com/illyadd/pdf-share/blob/master/PDF%2B/annotations/api.py"
click node_annotation_validation "https://github.com/illyadd/pdf-share/blob/master/PDF%2B/annotations/validators.py"
click node_annotation_records "https://github.com/illyadd/pdf-share/blob/master/PDF%2B/annotations/models.py"
click node_rest_routes "https://github.com/illyadd/pdf-share/blob/master/PDF%2B/api/views.py"
click node_sync_engine "https://github.com/illyadd/pdf-share/blob/master/PDF%2B/api/sync.py"
click node_sync_tombstones "https://github.com/illyadd/pdf-share/blob/master/PDF%2B/api/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_account_flow,node_user_model,node_visitor,node_mobile_client toneBlue
class node_library_flow,node_book_model,node_upload_form,node_pdf_inspection,node_access_rules,node_file_storage toneAmber
class node_sharing_flow,node_sharing_forms,node_sharing_records toneMint
class node_reader_ui,node_annotation_routes,node_annotation_validation,node_annotation_records toneRose
class node_rest_routes,node_sync_engine,node_sync_tombstones,node_google toneIndigo
```

## Components

### Accounts

- [Account access](https://github.com/illyadd/pdf-share/blob/master/PDF%2B/users/views.py): `PDF+/users/views.py`
- [User accounts](https://github.com/illyadd/pdf-share/blob/master/PDF%2B/users/models.py): `PDF+/users/models.py`

### PDF library

- [Library browsing](https://github.com/illyadd/pdf-share/blob/master/PDF%2B/book_library/views.py): `PDF+/book_library/views.py`
- [Books and folders](https://github.com/illyadd/pdf-share/blob/master/PDF%2B/book_library/models.py): `PDF+/book_library/models.py`
- [Upload forms](https://github.com/illyadd/pdf-share/blob/master/PDF%2B/book_library/forms.py): `PDF+/book_library/forms.py`
- [PDF inspection](https://github.com/illyadd/pdf-share/blob/master/PDF%2B/book_library/pdf.py): `PDF+/book_library/pdf.py`
- [Visibility rules](https://github.com/illyadd/pdf-share/blob/master/PDF%2B/book_library/access.py): `PDF+/book_library/access.py`
- [PDF storage](https://github.com/illyadd/pdf-share/blob/master/PDF%2B/book_library/signals.py): `PDF+/book_library/signals.py`

### Sharing

- [Sharing management](https://github.com/illyadd/pdf-share/blob/master/PDF%2B/sharing/views.py): `PDF+/sharing/views.py`
- [Sharing forms](https://github.com/illyadd/pdf-share/blob/master/PDF%2B/sharing/forms.py): `PDF+/sharing/forms.py`
- [Groups and links](https://github.com/illyadd/pdf-share/blob/master/PDF%2B/sharing/models.py): `PDF+/sharing/models.py`

### Reader and annotations

- [Browser reader](https://github.com/illyadd/pdf-share/blob/master/PDF%2B/static/js/reader.js): `PDF+/static/js/reader.js`
- [Annotation JSON API](https://github.com/illyadd/pdf-share/blob/master/PDF%2B/annotations/api.py): `PDF+/annotations/api.py`
- [Payload validation](https://github.com/illyadd/pdf-share/blob/master/PDF%2B/annotations/validators.py): `PDF+/annotations/validators.py`
- [User annotation layers](https://github.com/illyadd/pdf-share/blob/master/PDF%2B/annotations/models.py): `PDF+/annotations/models.py`

### Offline API

- [JWT REST endpoints](https://github.com/illyadd/pdf-share/blob/master/PDF%2B/api/views.py): `PDF+/api/views.py`
- [Delta sync](https://github.com/illyadd/pdf-share/blob/master/PDF%2B/api/sync.py): `PDF+/api/sync.py`
- [Deleted annotation markers](https://github.com/illyadd/pdf-share/blob/master/PDF%2B/api/models.py): `PDF+/api/models.py`

### Other components

- **User**
- **Mobile/offline client**
- **Google OAuth**

## Connections

- User → Account access: uses (evidence: `PDF+/users/views.py`)
- Account access → User accounts: authenticates (evidence: `PDF+/users/views.py`)
- Account access → Google OAuth: signs in via (evidence: `PDF+/users/views.py`)
- User → Library browsing: browses
- Library browsing → Visibility rules: filters by visibility (evidence: `PDF+/book_library/views.py`)
- Library browsing → Books and folders: reads and manages (evidence: `PDF+/book_library/views.py`)
- Library browsing → Upload forms: validates upload (evidence: `PDF+/book_library/views.py`)
- Upload forms → PDF inspection: inspects PDF (evidence: `PDF+/book_library/forms.py`)
- Upload forms → Books and folders: saves book (evidence: `PDF+/book_library/views.py`)
- Books and folders → PDF storage: stores and deletes files (evidence: `PDF+/book_library/signals.py`)
- User → Sharing management: manages access
- Sharing management → Sharing forms: uses forms (evidence: `PDF+/sharing/views.py`)
- Sharing management → Groups and links: updates sharing records (evidence: `PDF+/sharing/views.py`)
- Groups and links → Books and folders: targets books and folders (evidence: `PDF+/sharing/models.py`)
- Visibility rules → Groups and links: checks grants and links (evidence: `PDF+/book_library/access.py`)
- User → Browser reader: reads books
- Browser reader → Annotation JSON API: sends annotation requests
- Annotation JSON API → Payload validation: validates payload (evidence: `PDF+/annotations/validators.py`)
- Annotation JSON API → User annotation layers: reads and writes (evidence: `PDF+/annotations/models.py`)
- Mobile/offline client → JWT REST endpoints: calls REST API
- JWT REST endpoints → Delta sync: dispatches sync (evidence: `PDF+/api/views.py`)
- Delta sync → Visibility rules: filters visible content (evidence: `PDF+/api/sync.py`)
- Delta sync → Books and folders: pulls book state (evidence: `PDF+/api/sync.py`)
- Delta sync → Payload validation: validates changes (evidence: `PDF+/api/sync.py`)
- Delta sync → User annotation layers: syncs annotations (evidence: `PDF+/api/sync.py`)
- Delta sync → Deleted annotation markers: tracks deletions (evidence: `PDF+/api/sync.py`)
