go-documenter/README.md

# Dokumentenmanagement-System

## 1. Einführung und Ziele

Ziel ist die Entwicklung eines schlanken, serverseitig betriebenen Dokumentenmanagement-Systems mit Fokus auf einer zuerst umzusetzenden Schnittstelle statt eines Frontends. Die Nutzung soll initial vollständig über eine programmatische API erfolgen; ein Frontend ist bewusst erst für einen späteren Ausbauschritt vorgesehen.

Das System soll PDF-Dokumente verarbeiten, deren Inhalte per OCR erfassen, eine Volltextsuche bereitstellen und eine LLM-gestützte inhaltliche Anreicherung ermöglichen. Zusätzlich soll ein automatisierter Dateiimport aus einem überwachten Ordner unterstützt werden.

Wichtige Qualitätsziele:
- Einfache und möglichst schlanke Lösung.
- So wenig Frameworks und externe Systeme wie möglich; externe Komponenten nur dort, wo sie klaren Mehrwert liefern.
- Testbare Architektur mit konsequenter Unit-Test-Unterstützung.
- Nachvollziehbarkeit und Konsistenz von Zustandsänderungen durch Event Sourcing.
- Klare, wartbare und erweiterbare Struktur.
- einfache Installation, Betrieb und Automatisierung.
- zuverlässiger Import und konsistente Verarbeitung
- zuverlaessige Suchbarkeit der Dokumente.

## 2. Randbedingungen

- Die Implementierungssprache ist Go.
- Die Architektur soll technologisch so offen beschrieben werden, dass keine unnötigen Festlegungen auf konkrete Werkzeuge oder Produkte vorgenommen werden.
- Das System soll zunächst ohne Frontend nutzbar sein; der Zugriff erfolgt vorerst über die API.
- Automatisierung für Build, Test und Deployment soll über die bestehende Umgebung mit Gitea und Actions berücksichtigt werden.
- Die Dokumentation soll sich an der arc42-Struktur orientieren.
- Zu allen wesentlichen Architekturbausteinen und Verhaltensweisen sollen Unit-Tests vorgesehen werden.

## 3. Kontextabgrenzung

### Fachlicher Kontext

Das System verwaltet eingehende Dokumente, insbesondere PDF-Dateien. Dokumente können aktiv über die API eingebracht oder automatisiert aus einem definierten Import-Ordner übernommen werden.
Später soll es auch moeglich sein Dokument per Email an das System zu schicken um sie dann zu importieren.

Nach dem Import werden Dokumente verarbeitet, analysiert, durchsuchbar gemacht und in eine finale Ablagestruktur überführt. Die Verarbeitung umfasst auch die Anreicherung mit zusätzlichen Informationen aus einer LLM-gestützten Analyse.

### Technischer Kontext

Externe oder angrenzende Systeme und Schnittstellen:
- Dateisystem für Import-Ordner, temporäre Verarbeitung und finale Ablagestruktur.
- API-Clients zur Nutzung der Systemschnittstelle.
- LLM-Anbindung für semantische Analyse, Tagging oder ähnliche inhaltliche Verarbeitung.
- OCR-Verarbeitung zur Texterkennung aus Dokumenten.
- Automatisierungsumgebung mit Gitea und Actions für Build-, Test- und Deployment-Prozesse.

## 4. Lösungsstrategie

Die Lösung soll schrittweise und mit minimaler Komplexität umgesetzt werden:

1. Zuerst wird das Backend mit klarer API umgesetzt.
2. Danach werden Import, Parsing, OCR, Suchindexierung und Ereignisverarbeitung integriert.
3. Ein Frontend wird bewusst zurückgestellt und erst nach Stabilisierung der Schnittstelle betrachtet.

Leitprinzipien der Lösung:
- API-first-Ansatz.
- Schlanke, modular geschnittene Komponenten.
- Klare Trennung von Domänenlogik, Infrastruktur und Anwendungslogik.
- Event Sourcing zur Nachvollziehbarkeit von Änderungen und zur Unterstützung der Datenkonsistenz.
- Testbarkeit als architektonische Leitentscheidung, nicht als nachgelagerter Aspekt.
- Automatisierter dateibasierter Import als integraler Bestandteil der Lösung.

## 5. Bausteinsicht

### 5.1 Überblick über die Hauptbausteine

Das System besteht aus folgenden zentralen Bausteinen:

- API-Schicht
- Anwendungslogik
- Dokumentenverwaltung
- Import- und Watcher-Komponente
- Verarbeitungs-Pipeline
- OCR-Komponente
- LLM-Integrationskomponente
- Volltextsuch-Komponente
- Ereignis- und Konsistenzkomponente
- Ablage- und Strukturierungslogik
- Testschicht

### 5.2 Bausteinbeschreibungen

#### API-Schicht
Stellt die Schnittstelle zur Verfügung, über die Dokumente importiert, gesucht, abgefragt und verwaltet werden können. Da das Frontend zunächst nicht umgesetzt wird, ist die API der primäre Zugangspunkt des Systems.

#### Anwendungslogik
Koordiniert Anwendungsfälle wie Import, Verarbeitung, Suche, Verschiebung und Abfrage. Diese Schicht kapselt die Ablauflogik und soll unabhängig von Infrastrukturkomponenten testbar sein.

#### Dokumentenverwaltung
Verwaltet Metadaten, Status, Identitäten und den fachlichen Lebenszyklus eines Dokuments. Dazu gehören Zustände wie neu importiert, in Verarbeitung, verarbeitet, abgelegt oder fehlerhaft.

#### Import- und Watcher-Komponente
Überwacht einen definierten Ordner auf neu abgelegte Dokumente. Sobald dort ein Dokument gespeichert wird, soll die automatische Verarbeitung ausgelöst werden.

Zusätzliche Anforderungen:
- Dokumente aus dem Import-Ordner werden automatisch erkannt.
- Importierte Dateien können einen Zeitstempel im Dateinamen erhalten, der den Importzeitpunkt dokumentiert.
- Die automatische Verarbeitung startet ohne manuellen Eingriff.

#### Verarbeitungs-Pipeline
Verantwortet den Gesamtfluss eines Dokuments nach Eingang. Dazu zählen Einlesen, Parsen, OCR, inhaltliche Anreicherung, Suchindexierung, Statusänderungen und finale Ablage.

#### OCR-Komponente
Extrahiert Text aus den importierten PDF-Dokumenten, sofern dieser nicht direkt oder nicht vollständig maschinenlesbar vorliegt. Die OCR-Ergebnisse bilden eine Grundlage für Suche und weitere Analyse.

#### LLM-Integrationskomponente
Ermöglicht die inhaltliche Analyse von Dokumenten durch ein LLM. Ziel ist insbesondere die semantische Anreicherung, etwa durch Tagging, Klassifikation, Strukturierung oder ähnliche Zusatzinformationen.

#### Volltextsuch-Komponente
Stellt eine Volltextsuche über die verarbeiteten Dokumentinhalte bereit. Grundlage hierfür sind die extrahierten und gegebenenfalls per OCR gewonnenen Textinhalte sowie relevante Metadaten.

#### Ereignis- und Konsistenzkomponente
Setzt Event Sourcing fachlich um. Relevante Zustandsänderungen von Dokumenten werden als Ereignisse festgehalten, damit Änderungen nachvollziehbar bleiben und der Zustand konsistent rekonstruiert werden kann.

Wichtige Anforderungen:
- Keine Festlegung auf konkrete Technologien in dieser Dokumentation.
- Ereignisse sollen fachlich verständlich formuliert werden.
- Die Ereignisfolge soll Auditierbarkeit und Wiederherstellbarkeit unterstützen.

#### Ablage- und Strukturierungslogik
Verarbeitete Dokumente werden aus dem Import-Kontext in die finale Ablagestruktur überführt. Dabei sind folgende Anforderungen zu berücksichtigen:

- Verarbeitete Dokumente sollen nicht im Import-Ordner verbleiben.
- Verarbeitete Dokumente sollen in einen verarbeiteten Zielbereich überführt werden.
- Die finale Ordnerstruktur soll die tatsächliche Ablage widerspiegeln.
- Importierte beziehungsweise verarbeitete Dateien sollen in Jahresordner verschoben werden.
- Der Dateiname kann um einen Zeitstempel des Imports ergänzt werden.

#### Testschicht
Alle relevanten Schichten und Bausteine sollen durch Unit-Tests abgesichert werden. Die Architektur ist so zu gestalten, dass fachliche Logik isoliert testbar bleibt und Infrastrukturabhängigkeiten austauschbar oder kapselbar sind.

## 6. Laufzeitsicht

### 6.1 Import über überwachten Ordner

1. Ein Dokument wird im definierten Import-Ordner gespeichert.
2. Die Watcher-Komponente erkennt das neue Dokument.
3. Das System übernimmt das Dokument in die Verarbeitung.
4. Es wird geparst und bei Bedarf per OCR textuell erschlossen.
5. Das LLM reichert das Dokument semantisch an.
6. Die Inhalte werden für die Volltextsuche indexiert.
7. Fachlich relevante Schritte werden als Ereignisse erfasst.
8. Das Dokument wird in die finale Ablagestruktur verschoben.
9. Die Datei wird in einen Jahresordner einsortiert.
10. Optional erhält der Dateiname einen Zeitstempel des Imports.

### 6.2 Import über API

1. Ein Client übergibt ein Dokument über die API.
2. Das System legt das Dokument an und startet die Verarbeitung.
3. Danach folgt derselbe Verarbeitungsfluss wie beim dateibasierten Import.
4. Das Dokument wird abschließend suchbar gemacht und final abgelegt.

### 6.3 Suche

1. Ein Client sendet eine Suchanfrage an die API.
2. Die Volltextsuche durchsucht indizierte Dokumentinhalte und relevante Metadaten.
3. Das System liefert passende Treffer zurück.

### 6.4 Nachvollziehbarkeit von Zustandsänderungen

1. Jede wesentliche Aktion auf einem Dokument erzeugt ein fachliches Ereignis.
2. Diese Ereignisse bilden die Grundlage für Nachvollziehbarkeit und Konsistenz.
3. Der Status eines Dokuments kann aus den aufgezeichneten Ereignissen abgeleitet oder rekonstruiert werden.

## 7. Verteilungssicht

Das System ist für den Betrieb auf einem persönlichen oder dedizierten Server vorgesehen. Es soll mit möglichst wenig externen Abhängigkeiten auskommen und in einer einfachen Betriebsumgebung deploybar sein.

Wesentliche Deploymentsicht:
- Backend-Service zur Bereitstellung der API und Orchestrierung der Verarbeitung.
- Zugriff auf Dateisystembereiche für Import, Verarbeitung und finale Ablage.
- Einbindung der benötigten Komponenten für OCR, Suche und LLM-Nutzung.
- Build-, Test- und Deployment-Automatisierung über Gitea und Actions.

## 8. Querschnittliche Konzepte

### 8.1 Testbarkeit

Testbarkeit ist ein zentrales Architekturprinzip. Die Architektur soll so geschnitten werden, dass fachliche Kernlogik unabhängig von Infrastruktur getestet werden kann.

Anforderungen:
- Unit-Tests für alle wesentlichen Module.
- Klare Schnittstellen zwischen Fachlogik und Infrastruktur.
- Gute Mock- oder Stub-Fähigkeit für externe Abhängigkeiten.
- Reproduzierbare Tests für Import, Verarbeitung, Suchindexierung und Ereignisverarbeitung.

### 8.2 Ereignisorientierung und Konsistenz

Die Konsistenz fachlicher Zustände soll über ein Event-Sourcing-Konzept unterstützt werden. Änderungen an Dokumenten werden nicht nur als aktueller Zustand betrachtet, sondern auch als nachvollziehbare Abfolge fachlicher Ereignisse.

### 8.3 Dateiimport und Dateilebenszyklus

Dokumente können aktiv importiert oder passiv über einen überwachten Ordner aufgenommen werden. Nach erfolgreicher Verarbeitung sollen sie geordnet in die finale Ordnerstruktur verschoben werden.

Regeln:
- Automatische Verarbeitung beim Speichern im Import-Ordner.
- Kennzeichnung oder Umbenennung mit Importzeitpunkt möglich.
- Strukturierung nach Jahren in der Zielablage.

### 8.4 Suchkonzept

Die Volltextsuche ist ein fester Bestandteil des Systems. Sie soll die Auffindbarkeit über Dokumentinhalte sicherstellen und sowohl direkt lesbare als auch per OCR erschlossene Inhalte berücksichtigen.

### 8.5 LLM-gestützte Anreicherung

Die LLM-Integration dient der semantischen Verarbeitung von Dokumenten. Dazu können Tagging, inhaltliche Strukturierung, Klassifikation oder ähnliche Formen der Anreicherung gehören.

### 8.6 API-first

Die Roadmap sieht vor, zunächst ausschließlich die Schnittstelle produktiv nutzbar zu machen. Ein Frontend wird bewusst zurückgestellt, damit die Kernfunktionen unabhängig und stabil aufgebaut werden können.

### 8.7 Dokumentation

Die Architektur- und Systemdokumentation soll in einer arc42-orientierten Form gepflegt werden. Die Dokumentation soll die wesentlichen Entscheidungen, Bausteine, Abläufe, Risiken und Qualitätsanforderungen nachvollziehbar abbilden.

## 9. Architekturentscheidungen

- Das System wird zunächst als Backend- bzw. API-zentrierte Lösung umgesetzt.
- Ein Frontend ist Teil einer späteren Ausbaustufe und nicht Bestandteil der ersten Roadmap.
- Die Lösung soll bewusst einfach gehalten werden.
- Frameworks und externe Systeme sollen nur zurückhaltend eingesetzt werden.
- Event Sourcing wird als fachliches Konzept zur Nachvollziehbarkeit und Konsistenz berücksichtigt.
- Technologische Festlegungen für Event-Sourcing-Mechanismen werden in dieser Dokumentation bewusst vermieden.
- Die Architektur wird konsequent auf Testbarkeit ausgelegt.
- Unit-Tests sind kein Optionalbestandteil, sondern verbindlicher Bestandteil der Umsetzung.
- Volltextsuche ist ein verpflichtender Bestandteil des Systems.
- Ein automatischer Import über einen überwachten Ordner ist ein verpflichtender Bestandteil des Systems.
- Verarbeitete Dokumente werden in eine finale, strukturierte Zielablage überführt.
- Die finale Ablage berücksichtigt Jahresordner und optional Import-Zeitstempel in Dateinamen.
- Für Automatisierung im Entwicklungs- und Deployment-Prozess wird die vorhandene Gitea-/Actions-Umgebung berücksichtigt.

## 10. Qualitätsanforderungen

Wesentliche Qualitätsanforderungen sind:

- Einfachheit: Das System soll mit minimaler unnötiger Komplexität entworfen werden.
- Wartbarkeit: Die Bausteine sollen klar getrennt und verständlich aufgebaut sein.
- Testbarkeit: Jede wesentliche Funktionalität soll unit-testbar sein.
- Nachvollziehbarkeit: Dokumentänderungen und Statusübergänge sollen über Ereignisse nachvollziehbar bleiben.
- Konsistenz: Zustände und Übergänge sollen robust und rekonstruierbar sein.
- Automatisierbarkeit: Import, Verarbeitung, Test und Deployment sollen automatisierbar sein.
- Erweiterbarkeit: Ein späteres Frontend soll auf der vorhandenen API und Architektur aufsetzen können.
- Suchbarkeit: Dokumentinhalte sollen zuverlässig per Volltextsuche auffindbar sein.
- Zuverlässigkeit: Automatische Ordnerüberwachung und Verarbeitung sollen stabil funktionieren.

## 11. Risiken und technische Schulden

Mögliche Risiken:
- Event Sourcing erhöht die fachliche und technische Komplexität, wenn es zu breit oder zu früh umgesetzt wird.
- OCR-Qualität kann je nach Dokumentenqualität schwanken.
- LLM-gestützte Anreicherung kann variierende Ergebnisse liefern und muss fachlich eingeordnet werden.
- Automatische Dateiüberwachung und Verschiebung erfordern robuste Fehlerbehandlung, um Doppeleinträge oder inkonsistente Zustände zu vermeiden.
- Ohne frühzeitige Tests steigt das Risiko, dass Dateiverarbeitung, Suchindexierung und Ereignisabläufe schwer wartbar werden.

Offene Punkte, die später zu konkretisieren sind:
- Genaues Ereignismodell.
- Exaktes Metadatenmodell.
- Fehlerbehandlungsstrategie bei partiell fehlgeschlagener Verarbeitung.
- Detailregeln der finalen Ordnerstruktur.
- Such- und Ranking-Verhalten der Volltextsuche.

## 12. Glossar

- API: Programmierschnittstelle zur Nutzung der Systemfunktionen.
- OCR: Texterkennung aus Dokumenten oder Bildinhalten.
- LLM: Sprachmodell zur semantischen Verarbeitung und Anreicherung von Dokumentinhalten.
- Event Sourcing: Fachliches Konzept, bei dem Zustandsänderungen als Ereignisse festgehalten werden.
- Volltextsuche: Suche über die vollständigen textuellen Inhalte von Dokumenten.
- Import-Ordner: Überwachter Ordner, aus dem Dokumente automatisch übernommen werden.
- Jahresordner: Zielordnerstruktur, in der verarbeitete Dokumente nach Jahren abgelegt werden.
- Finale Ablagestruktur: Endgültige strukturierte Speicherung verarbeiteter Dokumente.