From f52e4f62b04021ea16d58d0be3b05d4d66bb0171 Mon Sep 17 00:00:00 2001 From: Christoph Kroczek Date: Sun, 12 Jul 2026 10:23:12 +0200 Subject: [PATCH] Initial commit: Add README.md --- README.md | 272 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 272 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..8329ae8 --- /dev/null +++ b/README.md @@ -0,0 +1,272 @@ +# 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. + +Stakeholder und Hauptinteressen: +- Betreiber: einfache Installation, Betrieb und Automatisierung. +- Entwickler: klare Architektur, gute Testbarkeit, geringe technische Komplexität. +- Nutzer: zuverlässiger Import, konsistente Verarbeitung, gute 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. + +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. \ No newline at end of file