Technisches Systemprotokoll & Entwicklungsdokumentation

1. Ursprüngliche Vision & Zielbild

Archivarius ist als lokal betriebenes, KI-gestütztes Collection Management System (CMS) konzipiert, das die Erfassung, Katalogisierung, Suche und Organisation einer privaten Sammlung automatisiert.

1.1 Kernphilosophie

• Zentrale Multimedien-Sammlung: Gemeinsame Verwaltung von Büchern, Mangas, Comics, Filmen, Spielen und weiteren Sammlerobjekten.
• Trennung von Werk und Exemplar: Das abstrakte Work beschreibt den Inhalt, während Item das physische Exemplar im Besitz repräsentiert.
• Lokale Datenhoheit: Datenhaltung und Rechenleistungen erfolgen primär lokal auf dem Raspberry Pi 5.
• KI als Assistenz: Optische Erkennung und Recherche-Hilfen ergänzen das System, sind jedoch keine Betriebsvoraussetzung. Das Grundsystem bleibt offline voll funktionsfähig.

1.2 Geplanter Funktionsumfang

Bereich	Geplante Funktion	Ziel
Erfassung	Barcode-/ISBN-Scan, Kameraaufnahme, Manuelle Eingabe	Schnelle Objekterfassung ohne Tippaufwand
Metadaten	Automatischer Abruf externer Daten & Covers	Stammdaten automatisch vervollständigen
Standorte	Hierarchische Schachtelung (Raum → Regal → Fach)	Lückenlose physische Auffindbarkeit
KI & OCR	Cover-Erkennung, Ähnlichkeitssuche via pgvector	Erfassung und Visualisierung automatisieren
Schnittstellen	Plugin-System für Metadatenprovider	Zukunftssichere Erweiterbarkeit

2. Systemarchitektur & Laufzeitumgebung

Das System wird über Docker Compose orchestriert und ist ressourcenschonend für den Raspberry Pi 5 konfiguriert.

2.1 Container-Setup & Bindings

Container-Name	Basis-Image	Port-Binding	Spezifikationen & Speicherlimits
archivarius-postgres	postgres:16-alpine	127.0.0.1:5432:5432	Optimiert: shared_buffers=64MB, effective_cache_size=256MB, max_connections=10.
archivarius-api	python:3.12-slim	0.0.0.0:8000:8000	FastAPI-Backend mit Uvicorn, SQLAlchemy 2.0 (AsyncIO) und Alembic.

2.2 Verzeichnisstruktur

.
├── alembic/                  # Alembic Migrationsskripte
├── backend/                  # Applikationscode & Test-Suite
│   ├── app/
│   │   ├── api/              # REST Endpunkte (Router)
│   │   ├── core/             # DB Engine, Session Handler & Config
│   │   ├── models/           # SQLAlchemy ORM Domänenmodelle
│   │   ├── repositories/     # Data Access Layer
│   │   └── schemas/          # Pydantic Schemas (DTOs)
│   └── tests/                # Async Pytest Test-Suite
├── database/                 # PostgreSQL Persistent Mount (/database/data)
└── uploads/                  # Medien-Speicher (Covers, Objektfotos)

3. Modell-Konsolidierung & Datenbankstand (Meilenstein v0.2)

Das ORM-Schema wurde konsolidiert, um Mapping-Fehler, zirkuläre Imports und Primary-Key-Konflikte zu beheben.

3.1 Modell-Anpassungen im Detail

• Location (location.py): Primärschlüssel eindeutig auf location_id festgelegt. Hierarchische Selbstreferenz (parent_location_id) und Feld description integriert.
• Item (item.py): Namensfelder title und title_override ergänzt. Verpflichtende Fremdschlüssel-Beziehung media_type_id auf media_types verankert. Time-Stamps via server_default=func.now() abgesichert.
• MediaType (media_type.py): Felder code, name und parent_id (für hierarchische Formate) hergestellt.

3.2 Bestätigter Datenbank- & Migrationsstand

Der Abgleich zwischen der PostgreSQL-Datenbank und Alembic wurde erfolgreich verifiziert:

Prüfpunkt	Ergebnis / Version	Status
Datenbank-Schema	9 Relationen (inkl. media_types, items, works)	OK
Alembic Head	8216f3a30af2 (Revision: Add Media Types)	OK
alembic_version in DB	8216f3a30af2	OK
API Healthcheck	{"status":"ok","database":"ok"}	OK

4. Test-Infrastruktur & Qualitätssicherung

Für automatisierte Tests ohne Beeinträchtigung der PostgreSQL-Produktivdatenbank wurde eine asynchrone SQLite-Testumgebung aufgebaut.

4.1 Test-Konzept & Ergebnisse

• Isolation: Ausführung über sqlite+aiosqlite:////tmp/test_archivarius.db.
• Lifecycle: Automatischer Schema-Aufbau (create_all) und Abbau (drop_all) pro Testdurchlauf in tests/conftest.py.
• Ergebnis: 100 % Erfolgsquote (6/6 Tests grün in ~4,5 Sekunden).

tests/api/v1/test_conditions.py::test_create_condition PASSED
tests/api/v1/test_conditions.py::test_create_duplicate_condition_fails PASSED
tests/api/v1/test_conditions.py::test_list_conditions PASSED
tests/api/v1/test_conditions.py::test_get_condition_by_id PASSED
tests/api/v1/test_conditions.py::test_delete_condition PASSED
tests/api/v1/test_items.py::test_create_and_filter_item PASSED

====================== 6 passed in 4.58s ======================

5. Roadmap & Nächste Schritte (Meilenstein v0.3)

Nach Abschluss von v0.2 richtet sich der Fokus auf den Ausbau der Geschäftslogik und der Schnittstellen.

5.1 Arbeitspakete für v0.3 (REST API)

• Repository-Layer (app/repositories/): Implementierung von BaseRepository[ModelType] für generische CRUD-Muster sowie spezialisierte Abfragen für ItemRepository.
• REST-API-Router (app/api/v1/): Fertigstellung aller Endpunkte für locations/, media-types/, works/, publishers/ und items/ (mit Pagination und Barcode-Filterung).
• Integrationstests: Ausbau der Pytest-Coverage auf Standort-Hierarchien und Work-Item-Kopplungen.

6. Betriebsbefehle & Operations-Cheatsheet

# System im Hintergrund starten
docker compose up -d

# Container- & Health-Status prüfen
docker compose ps
curl http://localhost:8000/health

# Test-Suite im API-Container ausführen
docker exec -it archivarius-api pytest -o asyncio_mode=auto tests -v

# Alembic Migrationsstand abfragen
docker compose exec api alembic current
docker compose exec postgres psql -U archivarius -d archivarius -c "SELECT * FROM alembic_version;"