Famulus Repro besteht aus 55 Swift-Quelldateien in drei Xcode-Targets, einer Python-OCR-Pipeline im Orchestrator und einer Quarto-Dokumentationssite — nichts ist versteckt, jede Produktionsdatei steht in der folgenden Tabelle.
Dieses Kapitel ist die einzige Stelle, an der alle Produktionsdateien namentlich aufgeführt sind. Wer eine Komponente ändern, einen Fehler lokalisieren oder die Pipeline von Grund auf wiederherstellen will, findet hier den vollständigen Ausgangspunkt.
Xcode-Projekt und Build-Konfiguration
Das Projekt wird mit XcodeGen aus project.yml generiert. Das erzeugte .xcodeproj wird nicht in Git eingecheckt; es entsteht durch xcodegen generate aus einer einzigen Konfigurationsdatei.
project.yml |
XcodeGen-Spezifikation: 3 Targets, Bundle-ID com.opensciencetechnology.famulus.repro, Team YGJ8TE6EAT |
ExportOptions.plist |
App-Store-Export-Konfiguration für scripts/archive.sh |
fastlane/metadata/ |
App-Store-Metadaten (de-DE, en-US) |
.cursor/rules/repro-link.mdc |
Cursor-Arbeitsregel: funktionierende Mac↔︎iPhone-Konfiguration |
.cursor/rules/bauhaus-design.mdc |
Cursor-Arbeitsregel: UI-Designprinzipien (keine Dev-Telemetrie, keine gelben Warnungen für Routine) |
Drei Targets / Schemes
FamulusRepro-iOS |
iOS 27+ |
Shared/ + iOS/ |
Kamera-App für iPhone/iPadOS |
FamulusRepro-macOS |
macOS 26+ |
Shared/ + macOS/ |
Backstage-App |
famulus-pipeline |
macOS 26+ |
Teilmenge Shared + PipelineTool |
Diagnose-CLI |
Shared — Geräteübergreifende Quellcode-Schicht
Alle Dateien unter FamulusRepro/Shared/ werden von beiden App-Targets kompiliert. Eine Änderung hier erfordert immer den Neubau beider Schemes.
Modelle
Shared/Models/ReproNetworkMessage.swift |
Codable-Enum aller Protokoll-Nachrichten: liveFrame, detection, pageCaptured, settings, linkHello, resolutionUpdate |
Shared/Models/ReproDocumentMode.swift |
bookDoublePage vs. receipt (Einzelblatt); von Mac→iPhone synchronisiert |
Shared/Models/BookType.swift |
Benannter Buchtyp mit OCR-Overlay, Seitenformat, Lifecycle-Status |
Shared/Models/PagePartitur.swift |
Pro-Seite-Partitur-Ergebnis-Schema: pagenum, Kolumnentitel, Seitentyp |
Shared/Models/ReceiptMetadata.swift |
Belegklasse (Taxi/offen), fileStem für [klasse]-Firma-Datum-Betrag-Währung-Benennung |
Services
Shared/Services/ReproLink.swift |
Gerahmtes TCP auf Port 8765; beide Seiten hören und wählen; Tailscale zuerst, Bonjour-Fallback; tcpParameters(peerToPeer: false) |
Shared/Services/PageGeometry.swift |
Zentrales Geometrie-Modul: Quad-Erkennung, Perspektivkorrektur, Buchspreite-Aufteilung, Einzelblatt-Hülle, Deskew, Tight-Crop, Quality-Gates, GeometryReport |
Shared/Services/GutterFinder.swift |
Falz-Lokalisierung: LiDAR-Tiefe + Schatten + Textlücke; gutterMethod nennt beitragende Signale |
Shared/Services/ArchivalToneEngine.swift |
Fünfstufige Tonwertkette auf linearem CIContext: Flat-Field, Spreizung, S-Kurve, Enhancer, Luminanz-Schärfung |
Shared/Services/OCRService.swift |
RecognizeDocumentsRequest primär, VNRecognizeTextRequest Fallback; Modell-Warmup beim Programmstart |
Shared/Services/IPhonePhotoEngine.swift |
CIRAWFilter ProRAW-Entwicklungsstack für On-Device-RAW-Verarbeitung |
Shared/Services/Sharpness.swift |
Laplace-Varianz-Fokus-Gate auf zentralem 60-%-Crop, kontrast-normiert |
Theme
Shared/Theme/LettreTheme.swift |
Oxford/Gold/Papier-Palette, FamulusBanner, StatusChip, Button-Stile |
iOS — Kamera-App
FamulusRepro/iOS/ enthält den gesamten Erfassungspfad: Kamera, Rahmen-Erkennung, ReproLink-Server, UI.
Services
iOS/Services/CameraService.swift |
AVCapture-Session: LiDAR/Wide-Kamera, 48-MP-HEIC-Erfassung, Tiefensnapshot beim Auslösen |
iOS/Services/DocumentDetector.swift |
Zweistufige Rahmen-Sperre: stage1Acquiring → stage1Settled → stage2Refining → stage2Locked; Hysterese und deadbandPos/Size/Angle |
iOS/Services/HardwareTriggerManager.swift |
Bluetooth-/Lautstärketasten-Fernauslöser |
iOS/Services/ReproLevelManager.swift |
CoreMotion-Pitch/Roll-Wasserwaage für Kopierständer-Ausrichtung |
iOS/Services/ReproStreamServer.swift |
iPhone-ObservableObject: empfängt Mac-Kommandos, streamt Vorschau, leitet Auslösen weiter |
iOS/Services/ImageProcessor.swift |
On-iPhone-Archiv-Verbesserungsprofile (lokaler Pfad, Legacy) |
iOS/Services/PDAPackageExporter.swift |
Standalone-PDA-Export-Bundle aus SwiftData für Weitergabe |
iOS/Services/PDFExporter.swift |
Durchsuchbares PDF aus lokalen Scan-Seitenbildern |
Views
iOS/Views/CameraView.swift |
Haupt-Sucher-UI: Auslöser, Zoom, Erfassungsgate, Versand via ReproLink |
iOS/Views/CameraPreviewView.swift |
UIView mit AVCaptureVideoPreviewLayer + Quad/Falz-Overlay-Zeichnung |
iOS/Views/ReproOverlayView.swift |
Ausrichtungshilfen: Wasserwaage, A4/Buchspreite-Führungslinien, Kopierständer-Rand |
iOS/Views/HomeView.swift |
Startseite: Link-Status, Dokumentliste, Sucher-Einstieg, iPad-Split-View |
iOS/Views/DocumentDetailView.swift |
Lokale SwiftData-Dokumentansicht, On-Device-OCR, PDF/PDA-Export |
Modelle
iOS/Models/ScannedDocument.swift |
SwiftData @Model für lokalen iPhone-Dokumentspeicher (parallel zu Mac PDAI) |
iOS/FamulusReproApp.swift |
iOS @main; startet ReproStreamServer; SwiftData-Container |
macOS — Backstage-App
FamulusRepro/macOS/ enthält die gesamte Verarbeitungs- und UI-Schicht.
Services
macOS/Services/BackstageController.swift |
Zentraler Zustand: Link, Sucher-Spiegel, Capture→Pipeline, Partitur, Dokument-Sessions, ActiveDocumentStore |
macOS/Services/PDAIBackendPipeline.swift |
Mac-Orchestrierung: Master → Geometrie → Tonwert → OCR → page_NNN/-PDAI-Ordner; Reprocessing und Umbenennung |
macOS/Services/PartiturClient.swift |
HTTP-Client gegen ai-agent-orchestrator Port 5401; synchrone und asynchrone Extended-OCR-Scores |
macOS/Services/ReceiptClassifier.swift |
Schnelle On-Device-Belegfeld-Extraktion aus OCRResult (vor Partitur, für sofortige Umbenennung) |
macOS/Services/BookTypeRegistry.swift |
Lade/Speichere BookType-Profile aus Application-Support |
macOS/Services/CaptureSettingsStore.swift |
UserDefaults-Persistenz von Aufnahme-/Tonwert-Einstellungen; Push an iPhone bei Verbindung |
macOS/Services/PageOrderAnalyzer.swift |
Lesereihenfolge-Sortierung, Spreiten-Geschwister-Seitennum-Inferenz, Dubletten-Erkennung |
macOS/Services/ThumbnailCache.swift |
ImageIO-downgesampelte Sidebar-Vorschaubilder + Master-Platzhalter während Pipeline |
macOS/Services/ScanFolderBookmark.swift |
Security-Scope-Bookmark für Scan-Wurzel; Standard ~/Documents/Scans |
macOS/FamulusReproBackstageApp.swift |
macOS @main; OCR-Warmup; BackstageController-Lifecycle |
Views
macOS/Views/BackstageView.swift |
Root-Fenster: Sidebar · Stage · Inspektor · Statusleiste |
macOS/Views/SidebarView.swift |
Zweistufiger Dokument-Browser + seitenbreites Vorschaubild-Raster; Seitennum-Edit; Dubletten-Icon |
macOS/Views/ContactSheetView.swift |
Spreiten-Karten, Qualitäts-Chip „Nachbessern”, Reshoot/Reprocess-Kontextmenü |
macOS/Views/SpreadDetailView.swift |
Doppelseite: zwei Seiten + Transkript-/Geometrie-/Partitur-Tabs in SplitPane |
macOS/Views/PageDetailView.swift |
Einzelseite-Detail mit Tabs: Transkript / Daten / XML / XML-Quelle |
macOS/Views/ViewfinderView.swift |
Mac-Live-Spiegel: Quad-Overlay, Falzlinie, Metering-Overlay |
macOS/Views/MeteringOverlay.swift |
Schwach-goldenes Papier-Messquadrat, am erkannten Quad ausgerichtet |
macOS/Views/InspectorView.swift |
Bauhaus-Inspektor: Aufnahme · Partitur · Ablage; DisclosureGroup("Erweitert") |
macOS/Views/DuplicateSelectionView.swift |
Vergleich gleicher Seitennum-Duplikate; Behalten vs. Archivieren |
macOS/Views/SplitPane.swift |
Ziehbarer Split-Teiler mit UserDefaults-Persistenz |
macOS/Views/TranscriptWebView.swift |
WebKit-HTML/XML-Renderer; TranscriptHTML-Builder; renderReceiptXML für Beleganzeige |
macOS/Models/BackstageModels.swift |
LocalScanPage, LocalSpread, LocalDocumentSession, PageSelectionRecord, PartiturRunRecord |
macOS/Resources/transcript.css |
Buchblatt-CSS für formatierte Transkript-/XML-Tabs |
Diagnose-CLI: famulus-pipeline
Tools/PipelineTool/main.swift |
CLI-Einstieg: Stage-Dumps, --mode book\|receipt, --measure-tilt, --probe-receipt, --score |
Tools/PipelineTool/ProbeMath.swift |
Quad-IoU/Winkel-Hilfsfunktionen für Belegrahmen-Diagnosen |
Skripte
scripts/make-snapshot.sh |
Workspace-Snapshot erzeugen (App + OCR-Pipeline, ohne Scans/Secrets/build) |
scripts/archive.sh |
App-Store-Archiv/Export für iOS + macOS Release (scripts/archive.sh [ios\|mac\|all]) |
scripts/geometry_audit.sh |
Batch-Pipeline auf Scan-Bibliothek; Neigungsresiduum- und Bogen-Gates |
scripts/page_tilt.py |
Unabhängiger Neigungsresiduum-Scorer (Kreuzkorrelation, nicht Vision) |
scripts/page_bow.py |
Seitenweise Bogenmessung pro Band; Kontrolle gegen Pipeline-Curl-Selbstbericht |
scripts/reprocess_and_batch_ocr.py |
Wartet auf Reprocessing-Abschluss, stellt Gemini-Batch-OCR über Orchestrator ein |
scripts/store_screenshots.sh |
Simulator + Mac-Screenshots für fastlane App-Store-Metadaten |
scripts/make_app_icon.py |
Rendert AppIcon.appiconset (Oxford/Gold-Buchmotiv) |
Dokumentationssite
Alle .qmd-Kapitel unter docs/ — Quarto-Site mit Oxford/Sandstone-Theme.
docs/index.qmd |
Architektur und Systemüberblick |
docs/reproplatz.qmd |
Physischer Aufbau, Auslöselogik, Schärfe-Gate |
docs/verbindung.qmd |
Mac↔︎iPhone ReproLink-Konfiguration und Protokoll |
docs/geometrie.qmd |
Geometrische Rektifizierung: Falz, Deskew, Quality-Gates |
docs/tonwert.qmd |
Archivischer Tonwert: Flat-Field, Spreizung, S-Kurve |
docs/ocr.qmd |
Vision-OCR: Struktur-Modus, Warmup, erweiterte OCR/Batch |
docs/partitur.qmd |
Partitur-Scores, Orchestrator-Endpunkte, JSON-Artefakte |
docs/pdai-ablage.qmd |
PDAI-Dateiformat, Ordnerstruktur, alle Sidecar-Dateien |
docs/backstage-ui.qmd |
Backstage-Bedienung, Bauhaus-Prinzip, Tastatursteuerung |
docs/cli.qmd |
famulus-pipeline-Diagnose-CLI |
docs/konstruktion.qmd |
Dieses Kapitel: vollständiger Dateikatalog |
docs/betrieb.qmd |
Betriebsabläufe Buch und Einzelblatt |
docs/entwicklung.qmd |
Entwickler- und Wiederherstellungsschleife |
OCR-Pipeline (ai-agent-orchestrator)
Die Orchestrator-Repro-Module liegen außerhalb des App-Repos, sind aber für den vollständigen Betrieb unerlässlich. Alle Pfade relativ zu ~/ai-mac-studio/development/ai-agent-orchestrator/.
Partitur-Scores
agent-store/repro_extended_ocr_agent/partitur.yaml |
Buch-Extended-OCR; pdai:repro_ocr_document; Standard-Modell gemini-3.8-flash, Batch-Standard |
agent-store/repro_receipt_ocr_agent/partitur.yaml |
Beleg-Extended-OCR; gleiche Op mit profile=receipt |
agent-store/repro_book_agent/partitur.yaml |
Buch-Bibliographie + Seitenstruktur-JSON (fastapple / glm-5.3:cloud) |
agent-store/repro_booktype_agent/partitur.yaml |
Buchtyp-Klassifizierung → Overlay → Pilot-OCR → Audit → Promotion |
agent-store/repro_receipt_agent/partitur.yaml |
Schnelles Beleg-JSON aus Transkript (fastapple) |
agent-store/repro_archival_agent/partitur.yaml |
Archivalisches Regest-JSON (Briefe, Urkunden) |
DTD und CSS
agent-store/repro_extended_ocr_agent/schema/repro_page.dtd |
Buchseiten-XML-Schema (<page>, <figure>, <table>, …) |
agent-store/repro_extended_ocr_agent/schema/repro_page.css |
Buchblatt-Anzeigestil (Oxford/Gold/Papier) |
agent-store/repro_receipt_ocr_agent/schema/repro_receipt.dtd |
Beleg-XML-Schema (Händler, Positionen, TSE, Reise, …) |
agent-store/repro_receipt_ocr_agent/schema/repro_receipt.css |
Thermobondartige Beleganzeige |
Python-Module
src/orchestrator/agents/pdai/repro/schema.py |
Kanonische DTD/CSS-Pfade; install_schema(profile=book\|receipt) |
src/orchestrator/agents/pdai/repro/prompt.py |
Prompt-Builder für Buch und Beleg; clean_raw_xml() |
src/orchestrator/agents/pdai/repro/validate.py |
DTD-Validierung/-Reparatur; Klartextextraktion aus XML |
src/orchestrator/agents/pdai/repro/figures.py |
Figurenzuschnitt aus Inline-Bbox + Erkennungs-Fallback; Reparatur-Sweep |
src/orchestrator/agents/pdai/repro/status.py |
ocr_extended.status.json-Schreiber; umbenannte Ordner-Seitenentdeckung |
src/orchestrator/agents/pdai/repro/receipt_json.py |
Beleg-XML → <stem>.receipt.json Flat-Contract (alle DTD-Attribute) |
src/orchestrator/agents/pdai/repro/driver.py |
op_repro_ocr_document: Reparatur-Sweep, Sync-Ollama-Pfad, Batch-Einreihung |
src/orchestrator/agents/pdai/repro/batch/machine.py |
DuckDB-Queue, Gemini-Batch-Submit/Poll/Route, Billing-Hook |
src/orchestrator/agents/pdai/repro/batch/launcher.py |
launchd-Einstiegspunkt: maybe_flush() alle 5 Minuten |
src/orchestrator/agents/pdai/repro/batch/schema.sql |
DDL für ocr_queue, batch_jobs, routing_log |
src/orchestrator/agents/pdai/repro/batch/config.json |
Modell, Flush-Schwellenwerte (10 Seiten / 30 Min.) |
src/orchestrator/agents/pdai/ocr.py |
Dünner Wrapper → repro.driver |
src/orchestrator/agents/pdai/llm.py |
Ollama-Multimodal-Aufrufe für Sync-OCR-Pfad (glm-5.3-flash:cloud) |
src/orchestrator/agents/fastapple.py |
On-Device-fasttext-Runtime für Book/Receipt/Booktype-Scores |
webapp/app.py |
FastAPI-App auf Port 5401 (Conductor) |
Billing
~/ai-mac-studio/agents/document-processing/ocr-billing/ocr_billing/recorder.py |
record_submission() — zentraler Billing-Einstiegspunkt; schreibt nach ocr_billing.duckdb |
~/ai-mac-studio/agents/document-processing/ocr-billing/ocr_billing/pricing.py |
Gemini-Modellpreise (inkl. 50-%-Batch-Rabatt) |
~/ai-mac-studio/agents/document-processing/ocr-billing/ocr_billing/report.py |
Tabellarische/CSV/Markdown-Berichte |
LaunchAgents
~/Library/LaunchAgents/com.ai-platform.conductor.plist |
com.ai-platform.conductor |
KeepAlive → Port 5401 |
~/Library/LaunchAgents/com.ai-platform.batch-ocr.plist |
com.ai-platform.batch-ocr |
300 s → launcher.py |
Externe Abhängigkeiten (Betrieb)
| Tailscale |
Primärverbindungsweg Mac↔︎iPhone |
Mac + iPhone |
Ollama glm-5.3-flash:cloud |
Buch-OCR-Sync-Pfad und Partitur |
Lokal auf Mac |
Gemini Batch API (gemini-3.8-flash) |
Extended-OCR via Batch-Queue |
Cloud (API-Key erforderlich) |
fasttext (~/bin/fasttext) |
Apple-Foundation-Models-Runtime für Partitur-Scores |
Lokal, macOS 27+ |
xcodegen |
Xcode-Projekt aus project.yml |
Homebrew: brew install xcodegen |
quarto |
Dokumentations-Site rendern |
Homebrew / quarto.org |