# tostman1/notenarchiv architecture

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

- Interactive diagram: https://gitdiagram.com/tostman1/notenarchiv
- Repository: https://github.com/tostman1/notenarchiv

## Overview

Notenarchiv is a local Django application for a music association. The verified source documents durable job recovery and cancellation, German-language management of works and members, and bounded PDF inspection primitives; the published preview is more limited. Archive indexing, review, and publication code is present, but the README says those product capabilities remain unavailable, so they are shown as an implementation subsystem rather than an available user workflow. The excerpts support several internal calls; other connections are omitted where wiring was not shown.

Main entry points: [`core/files.py`](https://github.com/tostman1/notenarchiv/blob/main/core/files.py) (Safe file access), [`apps/archive/indexing.py`](https://github.com/tostman1/notenarchiv/blob/main/apps/archive/indexing.py) (Archive indexing), [`apps/archive/publication.py`](https://github.com/tostman1/notenarchiv/blob/main/apps/archive/publication.py) (Copy and publication), [`apps/jobs/services/queue.py`](https://github.com/tostman1/notenarchiv/blob/main/apps/jobs/services/queue.py) (Queue and claims)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_catalog["Catalog management"]
  node_catalog_ui["Catalog CRUD and search<br/>[views.py]"]
  node_catalog_service["Catalog services<br/>[services.py]"]
  node_catalog_data[("Works and arrangements<br/>[models.py]")]
  node_members_data[("Members and assignments<br/>[models.py]")]
end

subgraph group_jobs["Durable jobs"]
  node_job_ui["Job management<br/>[views.py]"]
  node_job_data[("Jobs and leases<br/>[models.py]")]
  node_queue["Queue and claims<br/>[queue.py]"]
  node_lifecycle["Job lifecycle<br/>[lifecycle.py]"]
  node_worker["Worker runner<br/>[worker.py]"]
  node_storage_check["Storage validation<br/>[storage.py]"]
end

subgraph group_archive["Archive implementation"]
  node_indexing["Archive indexing<br/>[indexing.py]"]
  node_archive_data[("Archive records<br/>[models.py]")]
  node_archive_services["Archive transitions<br/>[services.py]"]
  node_review["Review orchestration<br/>[review_services.py]"]
  node_publication["Copy and publication<br/>[publication.py]"]
  node_preview["Authorized preview"]
end

subgraph group_core["Local processing"]
  node_filesystem["Safe file access<br/>[files.py]"]
  node_snapshot["Verified snapshots<br/>[preview.py]"]
  node_pdf_api["PDF processing API<br/>[api.py]"]
  node_pdf_worker["Isolated PDF worker<br/>[_worker.py]"]
  node_processes["Process control<br/>[processes.py]"]
  node_paths["Path validation<br/>[paths.py]"]
end

node_user(("Archivist"))

node_user -.->|"manages catalog"| node_catalog_ui
node_catalog_ui -.->|"delegates to"| node_catalog_service
node_catalog_service -->|"updates"| node_catalog_data
node_user -.->|"manages jobs"| node_job_ui
node_worker -->|"claims and heartbeats"| node_queue
node_worker -->|"completes attempts"| node_lifecycle
node_queue -->|"updates queue state"| node_job_data
node_lifecycle -->|"uses queue"| node_queue
node_worker -->|"uses locks"| node_filesystem
node_storage_check -.->|"validates roots"| node_filesystem
node_indexing -->|"records index"| node_archive_data
node_indexing -->|"uses transitions"| node_archive_services
node_indexing -->|"queues copies"| node_publication
node_indexing -->|"queues jobs"| node_queue
node_indexing -->|"reads files"| node_filesystem
node_review -->|"validates and records"| node_archive_services
node_review -->|"verifies bytes"| node_preview
node_review -->|"queues approval"| node_publication
node_preview -->|"reads snapshot"| node_snapshot
node_preview -->|"renders thumbnail"| node_pdf_api
node_snapshot -->|"opens managed file"| node_filesystem
node_publication -.->|"publishes copies"| node_filesystem
node_publication -.->|"uses catalog records"| node_catalog_data
node_pdf_api -->|"runs isolated process"| node_processes
node_pdf_worker -->|"worker process"| node_processes
node_filesystem -->|"validates references"| node_paths

click node_catalog_ui "https://github.com/tostman1/notenarchiv/blob/main/apps/catalog/views.py"
click node_catalog_service "https://github.com/tostman1/notenarchiv/blob/main/apps/catalog/services.py"
click node_catalog_data "https://github.com/tostman1/notenarchiv/blob/main/apps/catalog/models.py"
click node_members_data "https://github.com/tostman1/notenarchiv/blob/main/apps/members/models.py"
click node_job_ui "https://github.com/tostman1/notenarchiv/blob/main/apps/jobs/views.py"
click node_job_data "https://github.com/tostman1/notenarchiv/blob/main/apps/jobs/models.py"
click node_queue "https://github.com/tostman1/notenarchiv/blob/main/apps/jobs/services/queue.py"
click node_lifecycle "https://github.com/tostman1/notenarchiv/blob/main/apps/jobs/services/lifecycle.py"
click node_worker "https://github.com/tostman1/notenarchiv/blob/main/apps/jobs/services/worker.py"
click node_storage_check "https://github.com/tostman1/notenarchiv/blob/main/apps/jobs/services/storage.py"
click node_indexing "https://github.com/tostman1/notenarchiv/blob/main/apps/archive/indexing.py"
click node_archive_data "https://github.com/tostman1/notenarchiv/blob/main/apps/archive/models.py"
click node_archive_services "https://github.com/tostman1/notenarchiv/blob/main/apps/archive/services.py"
click node_review "https://github.com/tostman1/notenarchiv/blob/main/apps/archive/review_services.py"
click node_publication "https://github.com/tostman1/notenarchiv/blob/main/apps/archive/publication.py"
click node_preview "https://github.com/tostman1/notenarchiv/blob/main/apps/archive/preview_services.py"
click node_filesystem "https://github.com/tostman1/notenarchiv/blob/main/core/files.py"
click node_snapshot "https://github.com/tostman1/notenarchiv/blob/main/core/preview.py"
click node_pdf_api "https://github.com/tostman1/notenarchiv/blob/main/core/pdf/api.py"
click node_pdf_worker "https://github.com/tostman1/notenarchiv/blob/main/core/pdf/_worker.py"
click node_processes "https://github.com/tostman1/notenarchiv/blob/main/core/processes.py"
click node_paths "https://github.com/tostman1/notenarchiv/blob/main/core/paths.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_catalog_ui,node_catalog_service,node_catalog_data,node_members_data toneBlue
class node_job_ui,node_job_data,node_queue,node_lifecycle,node_worker,node_storage_check toneAmber
class node_indexing,node_archive_data,node_archive_services,node_review,node_publication,node_preview toneMint
class node_filesystem,node_snapshot,node_pdf_api,node_pdf_worker,node_processes,node_paths toneRose
class node_user toneIndigo
```

## Components

### Catalog management

- [Catalog CRUD and search](https://github.com/tostman1/notenarchiv/blob/main/apps/catalog/views.py): `apps/catalog/views.py`
- [Catalog services](https://github.com/tostman1/notenarchiv/blob/main/apps/catalog/services.py): `apps/catalog/services.py`
- [Works and arrangements](https://github.com/tostman1/notenarchiv/blob/main/apps/catalog/models.py): `apps/catalog/models.py`
- [Members and assignments](https://github.com/tostman1/notenarchiv/blob/main/apps/members/models.py): `apps/members/models.py`

### Durable jobs

- [Job management](https://github.com/tostman1/notenarchiv/blob/main/apps/jobs/views.py): `apps/jobs/views.py`
- [Jobs and leases](https://github.com/tostman1/notenarchiv/blob/main/apps/jobs/models.py): `apps/jobs/models.py`
- [Queue and claims](https://github.com/tostman1/notenarchiv/blob/main/apps/jobs/services/queue.py): `apps/jobs/services/queue.py`
- [Job lifecycle](https://github.com/tostman1/notenarchiv/blob/main/apps/jobs/services/lifecycle.py): `apps/jobs/services/lifecycle.py`
- [Worker runner](https://github.com/tostman1/notenarchiv/blob/main/apps/jobs/services/worker.py): `apps/jobs/services/worker.py`
- [Storage validation](https://github.com/tostman1/notenarchiv/blob/main/apps/jobs/services/storage.py): `apps/jobs/services/storage.py`

### Archive implementation

- [Archive indexing](https://github.com/tostman1/notenarchiv/blob/main/apps/archive/indexing.py): `apps/archive/indexing.py`
- [Archive records](https://github.com/tostman1/notenarchiv/blob/main/apps/archive/models.py): `apps/archive/models.py`
- [Archive transitions](https://github.com/tostman1/notenarchiv/blob/main/apps/archive/services.py): `apps/archive/services.py`
- [Review orchestration](https://github.com/tostman1/notenarchiv/blob/main/apps/archive/review_services.py): `apps/archive/review_services.py`
- [Copy and publication](https://github.com/tostman1/notenarchiv/blob/main/apps/archive/publication.py): `apps/archive/publication.py`
- [Authorized preview](https://github.com/tostman1/notenarchiv/blob/main/apps/archive/preview_services.py): `apps/archive/preview_services.py`

### Local processing

- [Safe file access](https://github.com/tostman1/notenarchiv/blob/main/core/files.py): `core/files.py`
- [Verified snapshots](https://github.com/tostman1/notenarchiv/blob/main/core/preview.py): `core/preview.py`
- [PDF processing API](https://github.com/tostman1/notenarchiv/blob/main/core/pdf/api.py): `core/pdf/api.py`
- [Isolated PDF worker](https://github.com/tostman1/notenarchiv/blob/main/core/pdf/_worker.py): `core/pdf/_worker.py`
- [Process control](https://github.com/tostman1/notenarchiv/blob/main/core/processes.py): `core/processes.py`
- [Path validation](https://github.com/tostman1/notenarchiv/blob/main/core/paths.py): `core/paths.py`

### Other components

- **Archivist**

## Connections

- Archivist → Catalog CRUD and search: manages catalog (evidence: `README.md`)
- Catalog CRUD and search → Catalog services: delegates to
- Catalog services → Works and arrangements: updates (evidence: `apps/catalog/services.py`)
- Archivist → Job management: manages jobs (evidence: `README.md`)
- Worker runner → Queue and claims: claims and heartbeats (evidence: `apps/jobs/services/worker.py`)
- Worker runner → Job lifecycle: completes attempts (evidence: `apps/jobs/services/worker.py`)
- Queue and claims → Jobs and leases: updates queue state (evidence: `apps/jobs/services/queue.py`)
- Job lifecycle → Queue and claims: uses queue (evidence: `apps/jobs/services/lifecycle.py`)
- Worker runner → Safe file access: uses locks (evidence: `apps/jobs/services/worker.py`)
- Storage validation → Safe file access: validates roots
- Archive indexing → Archive records: records index (evidence: `apps/archive/indexing.py`)
- Archive indexing → Archive transitions: uses transitions (evidence: `apps/archive/indexing.py`)
- Archive indexing → Copy and publication: queues copies (evidence: `apps/archive/indexing.py`)
- Archive indexing → Queue and claims: queues jobs (evidence: `apps/archive/indexing.py`)
- Archive indexing → Safe file access: reads files (evidence: `apps/archive/indexing.py`)
- Review orchestration → Archive transitions: validates and records (evidence: `apps/archive/review_services.py`)
- Review orchestration → Authorized preview: verifies bytes (evidence: `apps/archive/review_services.py`)
- Review orchestration → Copy and publication: queues approval (evidence: `apps/archive/review_services.py`)
- Authorized preview → Verified snapshots: reads snapshot (evidence: `apps/archive/preview_services.py`)
- Authorized preview → PDF processing API: renders thumbnail (evidence: `apps/archive/preview_services.py`)
- Verified snapshots → Safe file access: opens managed file (evidence: `core/preview.py`)
- Copy and publication → Safe file access: publishes copies (evidence: `apps/archive/publication.py`)
- Copy and publication → Works and arrangements: uses catalog records (evidence: `apps/archive/publication.py`)
- PDF processing API → Process control: runs isolated process (evidence: `core/pdf/api.py`)
- Isolated PDF worker → Process control: worker process (evidence: `core/pdf/_worker.py`)
- Safe file access → Path validation: validates references (evidence: `core/files.py`)
