Technisches Systemprotokoll & Entwicklungsdokumentation

1. Ursprüngliche Vision & Zielbild

Archivarius ist als lokal betriebenes, self-hosted Collection Management System (CMS) konzipiert, das die Erfassung, Katalogisierung, Suche und Organisation einer privaten Medien-Sammlung (Blu-rays, DVDs, VHS, Audio-CDs, Hörspiele, Bücher, Mangas, Comics u.a.) automatisiert und strukturiert.

1.1 Kernphilosophie

• Trennung von Werk und Exemplar: Das abstrakte Work beschreibt den Inhalt (Titel, Autoren/Künstler, Kategorie), während Item das physische Exemplar im Besitz repräsentiert (Zustand, Standort, Barcode, eigene Fotos). Ein Work kann mehrere Items haben – z.B. dieselbe Serie auf VHS, DVD und Blu-ray gleichzeitig.
• Lokale Datenhoheit: Datenhaltung und Rechenleistung erfolgen vollständig lokal, keine Abhängigkeit von Cloud-Diensten für den Kernbetrieb.
• Externe Anreicherung als Assistenz, nicht Voraussetzung: Automatischer Metadaten-Abruf ergänzt die Erfassung, das System bleibt aber auch offline voll funktionsfähig – nicht erreichbare externe Dienste blockieren nie das Anlegen eines Items.

1.2 Funktionsumfang (Stand aktuell)

2. Systemarchitektur & Laufzeitumgebung

Das System wird über Docker Compose orchestriert und läuft hinter einem Reverse Proxy für sicheren externen Zugriff.

2.1 Container-Setup

Externer Zugriff läuft über einen bestehenden Caddy-Reverse-Proxy (separates Gerät im Netzwerk), der per DuckDNS-DNS-01-Challenge ein echtes, browser-vertrauenswürdiges Let's-Encrypt-Zertifikat bezieht – ganz ohne offene Portweiterleitung am Router für die Anwendung selbst.

2.2 Tech-Stack

2.3 Verzeichnisstruktur (Ausschnitt)

backend/
├── app/
│   ├── api/v1/endpoints/  # REST-Endpunkte (items, works, locations, lookup, omdb, ...)
│   ├── models/            # SQLAlchemy ORM-Modelle
│   ├── repositories/      # Data-Access-Layer mit Eager-Loading-Strategien
│   ├── schemas/           # Pydantic-Schemas (DTOs)
│   ├── templates/         # Jinja2-Seiten der Web-Oberflaeche
│   ├── static/             # Eigenes CSS/JS der Web-Oberflaeche
│   └── web/                # Routen der Web-Oberflaeche (getrennt von der REST-API)
├── services/              # Externe Metadaten-Provider (Open Library, Discogs, OMDb)
└── scripts/               # Enrichment-Cronjob

3. Web-Oberfläche (Meilenstein 5, in Arbeit)

Bewusste Architekturentscheidung: serverseitig gerenderte Seiten direkt über FastAPI/Jinja2, statt eines separaten JavaScript-Frontend-Projekts mit eigenem Build-Prozess – geringere Komplexität, eine einzige Codebasis.

3.1 "Neues Item anlegen"

• Barcode per Handy-Kamera scannen (html5-qrcode, funktioniert für EAN/UPC) oder manuell eingeben
• Automatischer Metadaten-Lookup gegen den bestehenden Barcode-Endpunkt (lokaler Bestand → Open Library → Discogs)
• Zusätzliche, manuelle Titelsuche gegen OMDb für Filme/Serien (mit automatischer Suche während des Tippens) – nötig, da es aktuell keine verlässliche kostenlose Barcode-zu-Film-Datenbank gibt
• Publisher-Freitextfeld mit Autovervollständigung (legt neue Publisher automatisch an)
• Foto-Upload für das physische Exemplar
• Robuste Fehlerbehandlung: Work- und Item-Anlage sind so abgesichert, dass ein fehlgeschlagener Item-Schritt kein verwaistes Work in der Datenbank zurücklässt

3.2 Sammlungs-Dashboard

• Karten-Ansicht der gesamten Sammlung mit Foto/Titel/Autoren/Zustand/Standort
• Filter nach Medientyp, Zustand, Standort (inkl. der rekursiven Standort-Suche aus Meilenstein 4) und Barcode
• Aktuell in Überarbeitung: Detail-Ansicht pro Item, Mehrfach-Foto-Unterstützung, Dark Mode, kompaktere Kartenansicht bei langen Besetzungslisten

4. Barcode- & Metadaten-Erkennung

GET /api/v1/lookup/{barcode} prüft: eigener Bestand → Open Library (Bücher) → Discogs (Musik/Hörspiele). Antwort-Status: local · open_library · discogs · not_found · provider_unavailable.

Für Filme/Serien ergänzt GET /api/v1/omdb/search?title=... eine manuelle, titelbasierte Suche gegen die OMDb API – Barcode-basierte Filmdatenbanken existieren aktuell schlicht nicht zuverlässig als kostenloser Dienst (selbst TMDb pflegt keine Barcode-Daten).

Sind beim Scannen keine externen Dienste erreichbar, wird das Item trotzdem ohne Blockade angelegt; ein nächtlicher Cronjob trägt Metadaten automatisch nach, sobald die Dienste wieder erreichbar sind.

5. Qualitätssicherung

Automatisierte Test-Suite (isolierte SQLite-Testdatenbank) plus systematische manuelle End-to-End-Verifikation aller Entitäten gegen den laufenden Docker-Container – inklusive Fehlerfällen, Zeichenkodierung bei internationalen Metadaten und produktionsnahem Verhalten unter Docker Compose. Mehrere zuvor unentdeckte Inkonsistenzen zwischen Modellen, Schemas und Repositories (v.a. bei asynchronem Eager-Loading verschachtelter Beziehungen) wurden im Zuge dessen identifiziert und behoben.

6. Roadmap & Nächste Schritte