Famulus Repro — Architektur & Gesamtsystem

Famulus Repro in einem Satz

Famulus Repro teilt die Reproduktionsaufgabe strikt zwischen Erfassungssensor (iPhone/iPad) und Verarbeitungs- und Ablageinstanz (Mac Backstage) auf: das eine Gerät beherrscht die Optik, das andere die Rechenarbeit.

Famulus Repro verbindet iPhone oder iPad mit dem Mac zu einem integrierten Reproplatz. Das iPhone übernimmt ausschließlich die optische Erfassung: es liefert einen Live-Sucher mit Wasserwaage und Dokumenterkennung, löst mit voller Sensorauflösung aus und überträgt das Master-HEIC an den Mac. Dort läuft die gesamte rechnerische Verarbeitungskette: Trapez-Erkennung, Perspektivkorrektur, Falzerkennung, Tonwertoptimierung, Texterkennung und Ablage als PDAI-Dokumentbündel. Auf Wunsch steuert ein nachgelagerter Orchestrator eine semantische Partitur-Nachbearbeitung (Bibliographie, Belegextraktion, Regestierung) im lokalen Netz.

1 Systemarchitektur

flowchart TD
    PhoneCamera["iPhone Sensor\n48 MP ProRAW/HEIC"] -->|"TCP 8765 Tailscale plus Bonjour"| NetStream["ReproLink"]
    NetStream --> BackstageCtrl["Mac BackstageController"]
    BackstageCtrl --> PipelineEntry["PDAIBackendPipeline"]
    PipelineEntry --> Geometry["PageGeometry\nTrapez-Erkennung + Rektifizierung"]
    Geometry --> Tone["ArchivalToneEngine\nPapier-Tinte-S-Kurve"]
    Tone --> OCR["OCRService\nRecognizeDocumentsRequest"]
    OCR --> Storage["PDAI-Dokumentordner\nmaster NNN plus page NNN"]
    Storage --> PartiturClient["PartiturClient\nai-agent-orchestrator 5401"]

Die Trennlinie zwischen Sensor und Backstage ist eine bewusste Entwurfsentscheidung: Sie hält das iOS-Gerät schlank und erlaubt es, die rechenintensive GPU-Pipeline vollständig unter macOS auszuführen, wo die Metal-GPU und CoreImage-Hardwarebeschleunigung zur Verfügung stehen.

2 Zuständigkeiten der Komponenten

Komponente	Zuständigkeit	Plattform
`FamulusRepro-iOS`	Live-Sucher, Auslöselogik, Kameradienst, Netzwerktransfer	iOS/iPadOS
`ReproLink`	Gerahmtes TCP auf Port 8765; Tailscale zuerst, Bonjour `_famulusrepro._tcp` als LAN-Fallback	Shared
`BackstageController`	Hauptzustand der Mac-Anwendung, Koordination Sucher/Pipeline/UI	macOS
`PDAIBackendPipeline`	Vollständige Rektifizierungs- und Tonwertkette	macOS (Core Image GPU)
`PageGeometry`	Trapez-Erkennung, Perspektivkorrektur, Falzfindung, Deskew, Tight-Crop	Shared
`ArchivalToneEngine`	Archivischer Tonwert, S-Kurve, Flat-Field, Schärfung	Shared
`OCRService`	Strukturierte Texterkennung, Blocklayout	Shared
`PartiturClient`	HTTP-Client gegen den ai-agent-orchestrator	macOS

3 Netzwerkprotokoll

Die Kamera und die Backstage wählen sich gegenseitig auf TCP-Port 8765 an: zuerst über Tailscale (mac-studio ‹mac-im-tailnet›, iPhonegg ‹iphone-im-tailnet›), ersatzweise über Bonjour _famulusrepro._tcp. Beide Geräte müssen Famulus Repro sein; eine daneben liegende MacRepro-App belegt denselben Port und zerstört die Zuordnung. Die gemessene, funktionierende Konfiguration — inklusive Listener ohne Peer-to-Peer, Neuaufbau nach Shared-Änderungen und Prüfbefehlen — steht in Mac und iPhone verbinden. Bilddaten verlassen das lokale Netz nicht.

4 Produktverortung

Famulus Repro ist Teil der Famulus-Produktfamilie von lettreai. In dieser Familie stehen:

Famulus Repro — Bucherfassung, Belegdigitalisierung, Archivalreproduktion (dieses Produkt)
Famulus Erasmus — KI-gestützte Lektüre und Annotation
Famulus Scholar — Wissenschaftliche Dokumentenverarbeitung

Beide Apps — iOS und macOS — teilen denselben Bundle-Identifier (com.opensciencetechnology.famulus.repro) und sind als Universal-Purchase im App Store geplant.

5 Navigationshinweise

Diese Dokumentation umfasst drei neue Kapitel, die das System vollständig beschreiben:

Konstruktion und Dateikatalog: Jede Produktionsdatei mit Einzeiler-Zweck — kein Pfad ist versteckt.
Betrieb: Tagesablauf Buch- und Einzelblatt-Scan von Auslösen bis benanntem Beleg.
Entwicklung: Build-Loop, iOS-Install, Mac-Deploy, Wiederherstellung aus Snapshot.

6 Latenzen und Systemgrenzen

Gemessen auf Apple M1 Ultra und iPhone 16 Pro Max (Testgerät “iPhonegg”, UDID 00008140-...):

Schritt	Kaltstart	Warmstart
`RecognizeDocumentsRequest` Modelllade	ca. 94 s	< 0,6 s
Flat-Field + Tonwertkette (4k-HEIC)	ca. 1,5 s	ca. 1,5 s
Perspektivkorrektur + Deskew	ca. 0,3 s	ca. 0,3 s
Partitur-Anfrage an Orchestrator	2–8 s	2–8 s

Das Warmup des OCR-Modells wird beim Programmstart ausgelöst, sodass der erste Auslösevorgang nicht in den 94-Sekunden-Kaltstart läuft.