pdf-umbenenner/docs/architecture/adapter-overview.md

Architektur-Übersicht: Adapter-Out, CLI & Bootstrap

Diese Datei beschreibt die drei Module pdf-umbenenner-adapter-out, pdf-umbenenner-adapter-in-cli und pdf-umbenenner-bootstrap: ihren Zweck, ihre Paketstruktur, die wichtigsten Klassen und die Verdrahtungslogik beim Programmstart. Sie richtet sich an Entwickler, die in einem dieser Module arbeiten wollen und noch keinen Überblick über das Projekt haben. Domain- und Application-Schicht (Port-Verträge, fachliche Domänenobjekte, Use-Case-Interfaces) sind nicht Gegenstand dieses Dokuments – sie sind in docs/architecture/domain-overview.md beschrieben. GUI-interne Ports und die Struktur des GUI-Adapters finden sich in docs/architecture/gui-overview.md. Die hexagonale Abhängigkeitsrichtung ist strikt: Adapter kennen Domain und Application, nicht umgekehrt. Adapter dürfen außerdem nicht direkt voneinander abhängen.

---

1. Modulzweck

pdf-umbenenner-adapter-out

Enthält alle Outbound-Adapter-Implementierungen, also die konkreten technischen Lösungen für sämtliche Outbound-Ports der Application. Dazu gehören: Dateisystemzugriff, PDF-Textextraktion via PDFBox, SQLite-Persistenz (Schema, Repositories, Unit of Work), HTTP-Clients für zwei KI-Provider-Familien (OpenAI-kompatibel und Anthropic nativ), Properties-Konfiguration inklusive Legacy-Migration, dateibasierter Run-Lock sowie Systemuhr und SHA-256-Fingerprint.

pdf-umbenenner-adapter-in-cli

Schlanker Inbound-Adapter für den kopflosen Batch-Betrieb. Enthält genau eine Klasse (SchedulerBatchCommand), die den CLI-Einstiegspunkt bildet und ausschließlich über das Inbound-Port-Interface an die Application delegiert. Keine eigene Fachlogik.

pdf-umbenenner-bootstrap

Composition Root der Anwendung. Verantwortlich für: CLI-Argument-Parsing, Konfigurationsauflösung und -validierung, Aufbau des vollständigen Objektgraphen (manuell, ohne DI-Framework), Auswahl der aktiven KI-Adapter-Implementierung, Dispatch auf GUI- oder Headless-Pfad sowie Exit-Code-Ableitung. Bootstrap ist die einzige Stelle, an der alle Module zusammengeführt werden.

---

2. Paketstruktur

pdf-umbenenner-adapter-out

Wurzelpaket: de.gecheckt.pdf.umbenenner.adapter.out

Unterpaket	Inhalt
.ai	HTTP-Adapter für OpenAI-kompatible Schnittstelle und Anthropic Messages API
.clock	Systemuhr-Adapter (Instant.now())
.configuration	Properties-Laden, Multi-Provider-Parsing/-Validierung, Legacy-Migration
.fingerprint	SHA-256-Inhalts-Fingerprint
.lock	Dateibasierter Run-Lock
.modelcatalog	HTTP-Modellabruf für den GUI-Konfigurationseditor
.pathcheck	Pfadprüfung für den GUI-Editor
.pdfextraction	PDFBox-3.x-Adapter: Textextraktion und Seitenanzahl
.prompt	Prompt-Template-Lader
.resourcecreation	Anlegen von Ordnern und Dateien (korrigierende technische Tests)
.sourcedocument	Quellordner-Scanner (nicht rekursiv)
.sqlite	Schema-Initialisierung, Repositories, Unit of Work
.targetcopy	Zielkopie via Temp-Datei und atomarem Move
.targetfolder	Kollisionsfreier Zieldateiname, Umbenennung bestehender Zieldateien
.validation	API-Key-Auflösung aus Umgebungsvariablen (GUI-Editor)
.bootstrap.validation	StartConfiguration-Validierung vor Prozessstart

pdf-umbenenner-adapter-in-cli

Wurzelpaket: de.gecheckt.pdf.umbenenner.adapter.in.cli

Enthält ausschließlich SchedulerBatchCommand sowie die zugehörige package-info.java.

pdf-umbenenner-bootstrap

Wurzelpaket: de.gecheckt.pdf.umbenenner.bootstrap

Unterpaket	Inhalt
(Wurzel)	PdfUmbenennerApplication (main), BootstrapRunner, AiProviderSelector
.adapter	Bootstrap-interne Adapter: Log4jProcessingLogger, GuiConfigurationPropertiesWriter, AiModelCatalogDispatcher
.singleinstance	SingleInstanceGuard – Einzelinstanz-Schutz via Loopback-ServerSocket
.startup	StartupMode, StartupArguments, CliArgumentParser

---

3. Schlüsselklassen

Die folgenden Klassen sind für das Verständnis der drei Module zentral. FQN-Kürzel: ... steht jeweils für das Wurzelpaket des Moduls.

Adapter-Out

KI-Adapter

• ...ai.OpenAiHttpAdapter – implementiert AiInvocationPort für OpenAI-kompatible Endpunkte. POST {baseUrl}/v1/chat/completions, Bearer-Authentifizierung, extrahiert choices[0].message.content, klassifiziert HTTP-Fehler und Timeouts als AiInvocationTechnicalFailure.

• ...ai.AnthropicClaudeHttpAdapter – implementiert AiInvocationPort für die native Anthropic Messages API. POST /v1/messages, Header x-api-key und anthropic-version, konkateniert text-Content-Blöcke aus dem Antwort-Array.

Beide Adapter liefern denselben Domain-Typ (NamingProposal) und enthalten keinerlei provider-spezifische Typen in öffentlichen Signaturen. Welche Implementierung aktiv ist, entscheidet ausschließlich der Bootstrap (→ AiProviderSelector).

Modell-Katalog (GUI)

• ...modelcatalog.ClaudeModelCatalogAdapter – AiModelCatalogPort für Claude, GET /v1/models mit x-api-key.

• ...modelcatalog.OpenAiCompatibleModelCatalogAdapter – AiModelCatalogPort für OpenAI-kompatibel, GET /v1/models mit Bearer.

PDF-Extraktion

• ...pdfextraction.PdfTextExtractionPortAdapter – PDFBox-3.x-Adapter. Alle technischen Fehler werden als PdfExtractionTechnicalError zurückgegeben; es werden keine Exceptions propagiert.

SQLite

• ...sqlite.SqliteSchemaInitializationAdapter – legt Tabellen document_record und processing_attempt an. Schema-Evolution erfolgt per ALTER TABLE ADD COLUMN; bestehende Datenbestände bleiben rückwärtskompatibel.

• ...sqlite.SqliteUnitOfWorkAdapter – implementiert UnitOfWorkPort. Setzt autoCommit=false, führt atomare Commits durch, rollt bei Fehlern zurück.

• ...sqlite.SqliteDocumentRecordRepositoryAdapter – Stammsatz pro SHA-256-Fingerprint (Gesamtstatus, Fehlerzähler, Zieldateiname usw.).

• ...sqlite.SqliteProcessingAttemptRepositoryAdapter – Versuchshistorie, referenziert über Fingerprint. Enthält u. a. Provider-Identifikator, Modellname, Prompt-Identifikator, KI-Rohantwort und finalen Zieldateinamen.

Konfiguration

• ...configuration.PropertiesConfigurationPortAdapter – implementiert ConfigurationPort. Lädt config/application.properties (oder einen --config-Override), parst via MultiProviderConfigurationParser, löst API-Keys aus Umgebungsvariablen (OPENAI_COMPATIBLE_API_KEY, ANTHROPIC_API_KEY).

• ...configuration.LegacyConfigurationMigrator – erkennt alte Flat-Key-Konfigurationen (Schlüssel wie api.baseUrl, api.model), legt eine .bak-Sicherung an und überführt den Inhalt in das aktuelle Multi-Provider-Schema.

Laufzeitinfrastruktur

• ...lock.FilesystemRunLockPortAdapter – Lock-Datei mit PID-Inhalt. Wirft RunLockUnavailableException, wenn die Datei bereits vorhanden ist. Release löscht die Datei (best-effort).

• ...clock.SystemClockAdapter – delegiert an Instant.now().

• ...fingerprint.Sha256FingerprintAdapter – SHA-256 über den Rohdatei-Inhalt. Fehler als FingerprintTechnicalError.

Zieldatei

• ...targetcopy.FilesystemTargetFileCopyAdapter – kopiert die Quelldatei zunächst in eine .tmp-Datei, dann atomarer Move (Fallback: Standard-Move). Die Quelldatei wird in keinem Fall verändert.

• ...targetfolder.FilesystemTargetFolderAdapter – ermittelt einen kollisionsfreien Zieldateinamen mit (1), (2)-Suffix. Erkennt inhaltsidentische Duplikate via SHA-256.

Validierung vor Prozessstart

• ...bootstrap.validation.StartConfigurationValidator – validiert die geladene StartConfiguration auf Pflichtfelder, Wertebereiche, URI-Syntax und Pfadbedingungen. Wird im Bootstrap-Headless-Pfad unmittelbar nach dem Laden der Konfiguration aufgerufen.

---

Adapter-In-CLI

• ...adapter.in.cli.SchedulerBatchCommand – einziger Inbound-Adapter für den Headless-Betrieb. Nimmt einen BatchRunContext entgegen, delegiert an BatchRunProcessingUseCase.execute() und gibt BatchRunOutcome zurück. Enthält keine eigene Fachlogik; die Verdrahtung mit dem Use-Case-Interface erfolgt ausschließlich im Bootstrap.

---

Bootstrap

• ...bootstrap.PdfUmbenennerApplication – main-Methode. Parst CLI-Argumente via CliArgumentParser, bricht bei ungültiger Verwendung mit Exit-Code 1 ab, delegiert an BootstrapRunner.run() und ruft abschließend System.exit() mit dem zurückgegebenen Code auf.

• ...bootstrap.BootstrapRunner – Herzstück der Verdrahtung. Baut den Objektgraph für Headless- und GUI-Pfad, dispatcht über StartupMode, enthält buildProductionBatchUseCase() und runHeadlessBatch() als zentrale Kompositionsmethoden, liefert den Exit-Code zurück.

• ...bootstrap.AiProviderSelector – einzige Stelle, an der AiProviderFamily auf eine konkrete AiInvocationPort-Implementierung abgebildet wird: OPENAI_COMPATIBLE → OpenAiHttpAdapter, CLAUDE → AnthropicClaudeHttpAdapter.

• ...bootstrap.startup.CliArgumentParser – parst --headless und --config <Pfad> zu einem typsicheren StartupArgumentsParseResult (sealed: Valid / Invalid).

• ...bootstrap.singleinstance.SingleInstanceGuard – bindet einen Loopback-ServerSocket auf Port 47832. Wirft AnotherInstanceRunningException, wenn der Port bereits belegt ist. Ein Shutdown-Hook gibt den Socket frei.

• ...bootstrap.adapter.AiModelCatalogDispatcher – Bootstrap-interner Dispatcher für die GUI. Routet AiModelCatalogPort-Aufrufe anhand des providerIdentifier an den Claude- oder OpenAI-kompatiblen Modell-Katalog-Adapter. Thread-safe.

• ...bootstrap.adapter.Log4jProcessingLogger – implementiert ProcessingLogger auf Basis von Log4j2. Unterdrückt sensitive KI-Inhalte, wenn AiContentSensitivity.PROTECT_SENSITIVE_CONTENT gesetzt ist.

• ...bootstrap.adapter.GuiConfigurationPropertiesWriter – schreibt die im GUI-Editor bearbeitete Konfiguration als normalisierte application.properties zurück auf das Dateisystem.

---

4. Verdrahtungslogik in Bootstrap

Die folgende Sequenz beschreibt den Ablauf von main() bis zum Start des eigentlichen Adapters. Der Objektgraph wird ausschließlich durch manuelle new-Aufrufe aufgebaut; es wird kein DI-Framework verwendet.

Argument-Parsing

• PdfUmbenennerApplication.main() → CliArgumentParser.parse(args)
• Ergebnis Invalid → Exit-Code 1, keine weiteren Schritte

Einzelinstanz-Schutz

• BootstrapRunner.run() → SingleInstanceGuard.acquire()
• AnotherInstanceRunningException → Exit-Code 1; im GUI-Modus zusätzlich ein Swing-Warndialog

Modus-Dispatch

• BootstrapRunner.run() wertet startupArguments.mode() aus:
  • HEADLESS → runHeadlessBatch()
  • GUI → startGuiMode()

Konfigurationsauflösung (Headless-Pfad)

• Prüfung, ob --config-Datei existiert (Fehler → Exit-Code 1)
• LegacyConfigurationMigrator.migrateIfLegacy() bei erkannter Legacy-Form
• PropertiesConfigurationPortAdapter lädt und parst die Properties
• StartConfigurationValidator validiert die geladene StartConfiguration
• Validierungsfehler → Exit-Code 1

KI-Provider-Auswahl

• Innerhalb von buildProductionBatchUseCase(): multiProviderConfiguration().activeProviderFamily() → AiProviderSelector.select(family, providerConfig)
• Ergebnis: genau eine AiInvocationPort-Instanz

Objektgraph-Aufbau (Headless)

• Erzeugte Instanzen (Reihenfolge nach Abhängigkeit): Sha256FingerprintAdapter, SqliteDocumentRecordRepositoryAdapter, SqliteProcessingAttemptRepositoryAdapter, SqliteUnitOfWorkAdapter, FilesystemTargetFolderAdapter, FilesystemTargetFileCopyAdapter, FilesystemPromptPortAdapter, SystemClockAdapter, SourceDocumentCandidatesPortAdapter, PdfTextExtractionPortAdapter, Log4jProcessingLogger
• Application-Services (DocumentProcessingCoordinator, AiResponseValidator, AiNamingService) werden verdrahtet und in DefaultBatchRunProcessingUseCase eingebettet

CLI-Adapter

• BootstrapRunner erzeugt SchedulerBatchCommand mit dem fertigen BatchRunProcessingUseCase

Exit-Code-Ableitung

• BatchRunOutcome → 0 (Lauf technisch erfolgreich) oder 1 (harter Bootstrap-/Konfigurationsfehler)
• PdfUmbenennerApplication ruft System.exit(exitCode) auf

GUI-Pfad

• startGuiMode() baut via buildGuiStartupContext() einen GuiStartupContext: enthält AiModelCatalogDispatcher, EnvironmentApiKeyResolutionAdapter, TechnicalTestOrchestrator, GuiConfigurationPropertiesWriter
• GuiAdapter.start(context) übernimmt; ab diesem Punkt liegt die Kontrolle beim GUI-Adapter
• Im GUI-Pfad: keine SQLite-Schema-Initialisierung, kein Run-Lock-Erwerb, kein Batch-Use-Case
• GUI-interne Ports und deren Verbindung mit Outbound-Adaptern sind in docs/architecture/gui-overview.md beschrieben

---

5. Einstiegspunkte je Modul

pdf-umbenenner-adapter-out

1. ...ai.OpenAiHttpAdapter – zeigt das typische Adapter-Muster: Port-Interface implementieren, alle provider-spezifischen Details kapseln, ProviderConfiguration als einzige Konfigurationsquelle konsumieren. Danach AnthropicClaudeHttpAdapter zum Vergleich lesen.

2. ...sqlite.SqliteSchemaInitializationAdapter – erklärt das Datenbankschema, das alle SQLite-Adapter voraussetzen. Hier sieht man, welche Felder in document_record und processing_attempt existieren und wie Schema-Evolution additiv umgesetzt ist.

3. ...configuration.PropertiesConfigurationPortAdapter – Einstieg in die Konfigurationskette. Von hier aus MultiProviderConfigurationParser und LegacyConfigurationMigrator nachverfolgen.

pdf-umbenenner-adapter-in-cli

1. ...adapter.in.cli.SchedulerBatchCommand – komprimiertes Inbound-Adapter-Muster in einer einzigen Klasse. Zeigt, wie ein Inbound-Adapter ausschließlich über Port-Interfaces mit der Application kommuniziert.

2. package-info.java – beschreibt Abhängigkeitsrichtung und Verdrahtungsvertrag dieses Adapters.

3. SchedulerBatchCommandTest – zeigt, wie der Adapter ohne Bootstrap testbar ist.

pdf-umbenenner-bootstrap

1. PdfUmbenennerApplication – Startpunkt; die kurze Kette von main() bis System.exit() gibt einen ersten Überblick über die gesamte Startsequenz.

2. BootstrapRunner – Herzstück; buildProductionBatchUseCase() zeigt, wie der vollständige Objektgraph manuell aufgebaut wird. runHeadlessBatch() zeigt den Headless-Kontrollfluss.

3. AiProviderSelector – kleinste Klasse mit größter Hebelwirkung: hier liegt die einzige Stelle, an der die Provider-Auswahl aus der Konfiguration auf eine konkrete AiInvocationPort-Implementierung trifft.

---

Port-Verträge und Domain-Typen: docs/architecture/domain-overview.md GUI-interne Ports und GUI-Adapter-Struktur: docs/architecture/gui-overview.md