auto uebersetzung
This commit is contained in:
Christoph Kroczek
@@ -1,271 +1,270 @@
|
|||||||
# Dokumentenmanagement-System
|
# Document Management System
|
||||||
|
|
||||||
## 1. Einführung und Ziele
|
## 1. Introduction and Objectives
|
||||||
|
|
||||||
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.
|
The goal is to develop a lean, server-based document management system focused on implementing an interface first rather than a frontend. Initial usage will be entirely programmatic via an API; a frontend is intentionally scheduled for a later expansion phase.
|
||||||
|
|
||||||
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.
|
The system shall process PDF documents, capture their contents via OCR, provide full-text search capabilities, and enable LLM-supported content enrichment. Additionally, automated file import from a monitored folder shall be supported.
|
||||||
|
|
||||||
Wichtige Qualitätsziele:
|
Key quality objectives:
|
||||||
- Einfache und möglichst schlanke Lösung.
|
- Simple and lean solution.
|
||||||
- So wenig Frameworks und externe Systeme wie möglich; externe Komponenten nur dort, wo sie klaren Mehrwert liefern.
|
- Minimal frameworks and external systems; external components only where they provide clear added value.
|
||||||
- Testbare Architektur mit konsequenter Unit-Test-Unterstützung.
|
- Testable architecture with comprehensive unit test support.
|
||||||
- Nachvollziehbarkeit und Konsistenz von Zustandsänderungen durch Event Sourcing.
|
- Traceability and consistency of state changes through Event Sourcing.
|
||||||
- Klare, wartbare und erweiterbare Struktur.
|
- Clear, maintainable, and extensible structure.
|
||||||
- einfache Installation, Betrieb und Automatisierung.
|
- Simple installation, operation, and automation.
|
||||||
- zuverlässiger Import und konsistente Verarbeitung
|
- Reliable import and consistent processing.
|
||||||
- zuverlaessige Suchbarkeit der Dokumente.
|
- Reliable searchability of documents.
|
||||||
|
|
||||||
## 2. Randbedingungen
|
## 2. Constraints and Boundary Conditions
|
||||||
|
|
||||||
- Die Implementierungssprache ist Go.
|
- The implementation language is Go.
|
||||||
- Die Architektur soll technologisch so offen beschrieben werden, dass keine unnötigen Festlegungen auf konkrete Werkzeuge oder Produkte vorgenommen werden.
|
- The architecture shall be described in a technology-agnostic way to avoid unnecessary constraints on specific tools or products.
|
||||||
- Das System soll zunächst ohne Frontend nutzbar sein; der Zugriff erfolgt vorerst über die API.
|
- The system shall initially be usable without a frontend; access is provided via the API.
|
||||||
- Automatisierung für Build, Test und Deployment soll über die bestehende Umgebung mit Gitea und Actions berücksichtigt werden.
|
- Automation for build, test, and deployment shall consider the existing Gitea and Actions environment.
|
||||||
- Die Dokumentation soll sich an der arc42-Struktur orientieren.
|
- Documentation shall follow the arc42 structure.
|
||||||
- Zu allen wesentlichen Architekturbausteinen und Verhaltensweisen sollen Unit-Tests vorgesehen werden.
|
- Unit tests shall be provided for all essential architectural components and behaviors.
|
||||||
|
|
||||||
## 3. Kontextabgrenzung
|
## 3. Context and Scope
|
||||||
|
|
||||||
### Fachlicher Kontext
|
### Business Context
|
||||||
|
|
||||||
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.
|
The system manages incoming documents, particularly PDF files. Documents can be actively submitted via the API or automatically ingested from a defined import folder. Later, it shall also be possible to send documents via email to the system for import.
|
||||||
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.
|
After import, documents are processed, analyzed, made searchable, and transferred to a final storage structure. Processing also includes enrichment with additional information from LLM-supported analysis.
|
||||||
|
|
||||||
### Technischer Kontext
|
### Technical Context
|
||||||
|
|
||||||
Externe oder angrenzende Systeme und Schnittstellen:
|
External or adjacent systems and interfaces:
|
||||||
- Dateisystem für Import-Ordner, temporäre Verarbeitung und finale Ablagestruktur.
|
- File system for import folder, temporary processing, and final storage structure.
|
||||||
- API-Clients zur Nutzung der Systemschnittstelle.
|
- API clients for using the system interface.
|
||||||
- LLM-Anbindung für semantische Analyse, Tagging oder ähnliche inhaltliche Verarbeitung.
|
- LLM integration for semantic analysis, tagging, or similar content processing.
|
||||||
- OCR-Verarbeitung zur Texterkennung aus Dokumenten.
|
- OCR processing for text recognition from documents.
|
||||||
- Automatisierungsumgebung mit Gitea und Actions für Build-, Test- und Deployment-Prozesse.
|
- Automation environment with Gitea and Actions for build, test, and deployment processes.
|
||||||
|
|
||||||
## 4. Lösungsstrategie
|
## 4. Solution Strategy
|
||||||
|
|
||||||
Die Lösung soll schrittweise und mit minimaler Komplexität umgesetzt werden:
|
The solution shall be implemented incrementally and with minimal complexity:
|
||||||
|
|
||||||
1. Zuerst wird das Backend mit klarer API umgesetzt.
|
1. First, the backend with a clear API shall be implemented.
|
||||||
2. Danach werden Import, Parsing, OCR, Suchindexierung und Ereignisverarbeitung integriert.
|
2. Then import, parsing, OCR, search indexing, and event processing shall be integrated.
|
||||||
3. Ein Frontend wird bewusst zurückgestellt und erst nach Stabilisierung der Schnittstelle betrachtet.
|
3. A frontend is intentionally deferred and considered only after stabilization of the interface.
|
||||||
|
|
||||||
Leitprinzipien der Lösung:
|
Core principles of the solution:
|
||||||
- API-first-Ansatz.
|
- API-first approach.
|
||||||
- Schlanke, modular geschnittene Komponenten.
|
- Lean, modularly designed components.
|
||||||
- Klare Trennung von Domänenlogik, Infrastruktur und Anwendungslogik.
|
- Clear separation of domain logic, infrastructure, and application logic.
|
||||||
- Event Sourcing zur Nachvollziehbarkeit von Änderungen und zur Unterstützung der Datenkonsistenz.
|
- Event Sourcing for traceability of changes and support of data consistency.
|
||||||
- Testbarkeit als architektonische Leitentscheidung, nicht als nachgelagerter Aspekt.
|
- Testability as an architectural guiding principle, not an afterthought.
|
||||||
- Automatisierter dateibasierter Import als integraler Bestandteil der Lösung.
|
- Automated file-based import as an integral part of the solution.
|
||||||
|
|
||||||
## 5. Bausteinsicht
|
## 5. Building Block View
|
||||||
|
|
||||||
### 5.1 Überblick über die Hauptbausteine
|
### 5.1 Overview of Main Components
|
||||||
|
|
||||||
Das System besteht aus folgenden zentralen Bausteinen:
|
The system consists of the following central building blocks:
|
||||||
|
|
||||||
- API-Schicht
|
- API Layer
|
||||||
- Anwendungslogik
|
- Application Logic
|
||||||
- Dokumentenverwaltung
|
- Document Management
|
||||||
- Import- und Watcher-Komponente
|
- Import and Watcher Component
|
||||||
- Verarbeitungs-Pipeline
|
- Processing Pipeline
|
||||||
- OCR-Komponente
|
- OCR Component
|
||||||
- LLM-Integrationskomponente
|
- LLM Integration Component
|
||||||
- Volltextsuch-Komponente
|
- Full-Text Search Component
|
||||||
- Ereignis- und Konsistenzkomponente
|
- Event and Consistency Component
|
||||||
- Ablage- und Strukturierungslogik
|
- Storage and Structuring Logic
|
||||||
- Testschicht
|
- Test Layer
|
||||||
|
|
||||||
### 5.2 Bausteinbeschreibungen
|
### 5.2 Building Block Descriptions
|
||||||
|
|
||||||
#### API-Schicht
|
#### API Layer
|
||||||
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.
|
Provides the interface through which documents can be imported, searched, queried, and managed. Since the frontend is not initially implemented, the API is the primary entry point of the system.
|
||||||
|
|
||||||
#### Anwendungslogik
|
#### Application Logic
|
||||||
Koordiniert Anwendungsfälle wie Import, Verarbeitung, Suche, Verschiebung und Abfrage. Diese Schicht kapselt die Ablauflogik und soll unabhängig von Infrastrukturkomponenten testbar sein.
|
Coordinates use cases such as import, processing, search, relocation, and retrieval. This layer encapsulates workflow logic and shall be independently testable from infrastructure components.
|
||||||
|
|
||||||
#### Dokumentenverwaltung
|
#### Document Management
|
||||||
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.
|
Manages metadata, status, identities, and the business lifecycle of a document. This includes states such as newly imported, in processing, processed, archived, or failed.
|
||||||
|
|
||||||
#### Import- und Watcher-Komponente
|
#### Import and Watcher Component
|
||||||
Überwacht einen definierten Ordner auf neu abgelegte Dokumente. Sobald dort ein Dokument gespeichert wird, soll die automatische Verarbeitung ausgelöst werden.
|
Monitors a defined folder for newly deposited documents. When a document is saved there, automatic processing shall be triggered.
|
||||||
|
|
||||||
Zusätzliche Anforderungen:
|
Additional requirements:
|
||||||
- Dokumente aus dem Import-Ordner werden automatisch erkannt.
|
- Documents from the import folder are automatically detected.
|
||||||
- Importierte Dateien können einen Zeitstempel im Dateinamen erhalten, der den Importzeitpunkt dokumentiert.
|
- Imported files can receive a timestamp in the filename documenting the import time.
|
||||||
- Die automatische Verarbeitung startet ohne manuellen Eingriff.
|
- Automatic processing starts without manual intervention.
|
||||||
|
|
||||||
#### Verarbeitungs-Pipeline
|
#### Processing Pipeline
|
||||||
Verantwortet den Gesamtfluss eines Dokuments nach Eingang. Dazu zählen Einlesen, Parsen, OCR, inhaltliche Anreicherung, Suchindexierung, Statusänderungen und finale Ablage.
|
Responsible for the overall flow of a document after ingestion. This includes reading, parsing, OCR, content enrichment, search indexing, status changes, and final storage.
|
||||||
|
|
||||||
#### OCR-Komponente
|
#### OCR Component
|
||||||
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.
|
Extracts text from imported PDF documents where text is not directly or fully machine-readable. OCR results serve as a foundation for search and further analysis.
|
||||||
|
|
||||||
#### LLM-Integrationskomponente
|
#### LLM Integration Component
|
||||||
Ermöglicht die inhaltliche Analyse von Dokumenten durch ein LLM. Ziel ist insbesondere die semantische Anreicherung, etwa durch Tagging, Klassifikation, Strukturierung oder ähnliche Zusatzinformationen.
|
Enables content analysis of documents through an LLM. The goal is particularly semantic enrichment, such as through tagging, classification, structuring, or similar additional information.
|
||||||
|
|
||||||
#### Volltextsuch-Komponente
|
#### Full-Text Search Component
|
||||||
Stellt eine Volltextsuche über die verarbeiteten Dokumentinhalte bereit. Grundlage hierfür sind die extrahierten und gegebenenfalls per OCR gewonnenen Textinhalte sowie relevante Metadaten.
|
Provides full-text search over processed document contents. This is based on extracted and potentially OCR-derived text content as well as relevant metadata.
|
||||||
|
|
||||||
#### Ereignis- und Konsistenzkomponente
|
#### Event and Consistency Component
|
||||||
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.
|
Implements Event Sourcing at the business level. Relevant state changes in documents are recorded as events so that changes remain traceable and state can be consistently reconstructed.
|
||||||
|
|
||||||
Wichtige Anforderungen:
|
Important requirements:
|
||||||
- Keine Festlegung auf konkrete Technologien in dieser Dokumentation.
|
- No commitment to specific technologies in this documentation.
|
||||||
- Ereignisse sollen fachlich verständlich formuliert werden.
|
- Events shall be expressed in business-understandable terms.
|
||||||
- Die Ereignisfolge soll Auditierbarkeit und Wiederherstellbarkeit unterstützen.
|
- The sequence of events shall support auditability and recoverability.
|
||||||
|
|
||||||
#### Ablage- und Strukturierungslogik
|
#### Storage and Structuring Logic
|
||||||
Verarbeitete Dokumente werden aus dem Import-Kontext in die finale Ablagestruktur überführt. Dabei sind folgende Anforderungen zu berücksichtigen:
|
Processed documents are transferred from the import context to the final storage structure. The following requirements shall be considered:
|
||||||
|
|
||||||
- Verarbeitete Dokumente sollen nicht im Import-Ordner verbleiben.
|
- Processed documents shall not remain in the import folder.
|
||||||
- Verarbeitete Dokumente sollen in einen verarbeiteten Zielbereich überführt werden.
|
- Processed documents shall be transferred to a processed target area.
|
||||||
- Die finale Ordnerstruktur soll die tatsächliche Ablage widerspiegeln.
|
- The final folder structure shall reflect actual storage.
|
||||||
- Importierte beziehungsweise verarbeitete Dateien sollen in Jahresordner verschoben werden.
|
- Imported and processed files shall be moved to year-based folders.
|
||||||
- Der Dateiname kann um einen Zeitstempel des Imports ergänzt werden.
|
- The filename can be supplemented with an import timestamp.
|
||||||
|
|
||||||
#### Testschicht
|
#### Test Layer
|
||||||
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.
|
All relevant layers and components shall be secured through unit tests. The architecture shall be designed so that business logic remains independently testable and infrastructure dependencies are interchangeable or encapsulated.
|
||||||
|
|
||||||
## 6. Laufzeitsicht
|
## 6. Runtime View
|
||||||
|
|
||||||
### 6.1 Import über überwachten Ordner
|
### 6.1 Import via Monitored Folder
|
||||||
|
|
||||||
1. Ein Dokument wird im definierten Import-Ordner gespeichert.
|
1. A document is saved in the defined import folder.
|
||||||
2. Die Watcher-Komponente erkennt das neue Dokument.
|
2. The watcher component detects the new document.
|
||||||
3. Das System übernimmt das Dokument in die Verarbeitung.
|
3. The system takes over the document for processing.
|
||||||
4. Es wird geparst und bei Bedarf per OCR textuell erschlossen.
|
4. It is parsed and, if necessary, made textually accessible via OCR.
|
||||||
5. Das LLM reichert das Dokument semantisch an.
|
5. The LLM enriches the document semantically.
|
||||||
6. Die Inhalte werden für die Volltextsuche indexiert.
|
6. Contents are indexed for full-text search.
|
||||||
7. Fachlich relevante Schritte werden als Ereignisse erfasst.
|
7. Business-relevant steps are captured as events.
|
||||||
8. Das Dokument wird in die finale Ablagestruktur verschoben.
|
8. The document is moved to the final storage structure.
|
||||||
9. Die Datei wird in einen Jahresordner einsortiert.
|
9. The file is sorted into a year-based folder.
|
||||||
10. Optional erhält der Dateiname einen Zeitstempel des Imports.
|
10. Optionally, the filename receives an import timestamp.
|
||||||
|
|
||||||
### 6.2 Import über API
|
### 6.2 Import via API
|
||||||
|
|
||||||
1. Ein Client übergibt ein Dokument über die API.
|
1. A client submits a document via the API.
|
||||||
2. Das System legt das Dokument an und startet die Verarbeitung.
|
2. The system creates the document and starts processing.
|
||||||
3. Danach folgt derselbe Verarbeitungsfluss wie beim dateibasierten Import.
|
3. Subsequently, the same processing flow as file-based import is followed.
|
||||||
4. Das Dokument wird abschließend suchbar gemacht und final abgelegt.
|
4. The document is finally made searchable and archived.
|
||||||
|
|
||||||
### 6.3 Suche
|
### 6.3 Search
|
||||||
|
|
||||||
1. Ein Client sendet eine Suchanfrage an die API.
|
1. A client sends a search query to the API.
|
||||||
2. Die Volltextsuche durchsucht indizierte Dokumentinhalte und relevante Metadaten.
|
2. Full-text search queries indexed document contents and relevant metadata.
|
||||||
3. Das System liefert passende Treffer zurück.
|
3. The system returns matching results.
|
||||||
|
|
||||||
### 6.4 Nachvollziehbarkeit von Zustandsänderungen
|
### 6.4 Traceability of State Changes
|
||||||
|
|
||||||
1. Jede wesentliche Aktion auf einem Dokument erzeugt ein fachliches Ereignis.
|
1. Each significant action on a document generates a business event.
|
||||||
2. Diese Ereignisse bilden die Grundlage für Nachvollziehbarkeit und Konsistenz.
|
2. These events form the foundation for traceability and consistency.
|
||||||
3. Der Status eines Dokuments kann aus den aufgezeichneten Ereignissen abgeleitet oder rekonstruiert werden.
|
3. The status of a document can be derived or reconstructed from recorded events.
|
||||||
|
|
||||||
## 7. Verteilungssicht
|
## 7. Deployment View
|
||||||
|
|
||||||
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.
|
The system is intended for operation on a personal or dedicated server. It shall require minimal external dependencies and be deployable in a simple operating environment.
|
||||||
|
|
||||||
Wesentliche Deploymentsicht:
|
Essential deployment view:
|
||||||
- Backend-Service zur Bereitstellung der API und Orchestrierung der Verarbeitung.
|
- Backend service for providing the API and orchestrating processing.
|
||||||
- Zugriff auf Dateisystembereiche für Import, Verarbeitung und finale Ablage.
|
- Access to file system areas for import, processing, and final storage.
|
||||||
- Einbindung der benötigten Komponenten für OCR, Suche und LLM-Nutzung.
|
- Integration of required components for OCR, search, and LLM usage.
|
||||||
- Build-, Test- und Deployment-Automatisierung über Gitea und Actions.
|
- Build, test, and deployment automation via Gitea and Actions.
|
||||||
|
|
||||||
## 8. Querschnittliche Konzepte
|
## 8. Cross-Cutting Concepts
|
||||||
|
|
||||||
### 8.1 Testbarkeit
|
### 8.1 Testability
|
||||||
|
|
||||||
Testbarkeit ist ein zentrales Architekturprinzip. Die Architektur soll so geschnitten werden, dass fachliche Kernlogik unabhängig von Infrastruktur getestet werden kann.
|
Testability is a central architectural principle. The architecture shall be designed so that core business logic can be tested independently of infrastructure.
|
||||||
|
|
||||||
Anforderungen:
|
Requirements:
|
||||||
- Unit-Tests für alle wesentlichen Module.
|
- Unit tests for all essential modules.
|
||||||
- Klare Schnittstellen zwischen Fachlogik und Infrastruktur.
|
- Clear interfaces between business logic and infrastructure.
|
||||||
- Gute Mock- oder Stub-Fähigkeit für externe Abhängigkeiten.
|
- Good mocking or stubbing capability for external dependencies.
|
||||||
- Reproduzierbare Tests für Import, Verarbeitung, Suchindexierung und Ereignisverarbeitung.
|
- Reproducible tests for import, processing, search indexing, and event processing.
|
||||||
|
|
||||||
### 8.2 Ereignisorientierung und Konsistenz
|
### 8.2 Event-Orientation and Consistency
|
||||||
|
|
||||||
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.
|
Business state consistency shall be supported through an Event Sourcing concept. Changes to documents are considered not only as current state but also as a traceable sequence of business events.
|
||||||
|
|
||||||
### 8.3 Dateiimport und Dateilebenszyklus
|
### 8.3 File Import and Document Lifecycle
|
||||||
|
|
||||||
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.
|
Documents can be actively imported or passively ingested from a monitored folder. After successful processing, they shall be orderly transferred to the final folder structure.
|
||||||
|
|
||||||
Regeln:
|
Rules:
|
||||||
- Automatische Verarbeitung beim Speichern im Import-Ordner.
|
- Automatic processing when saved to the import folder.
|
||||||
- Kennzeichnung oder Umbenennung mit Importzeitpunkt möglich.
|
- Marking or renaming with import timestamp is possible.
|
||||||
- Strukturierung nach Jahren in der Zielablage.
|
- Organization by year in the target storage.
|
||||||
|
|
||||||
### 8.4 Suchkonzept
|
### 8.4 Search Concept
|
||||||
|
|
||||||
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.
|
Full-text search is an integral part of the system. It shall ensure discoverability through document contents and consider both directly readable and OCR-derived contents.
|
||||||
|
|
||||||
### 8.5 LLM-gestützte Anreicherung
|
### 8.5 LLM-Supported Enrichment
|
||||||
|
|
||||||
Die LLM-Integration dient der semantischen Verarbeitung von Dokumenten. Dazu können Tagging, inhaltliche Strukturierung, Klassifikation oder ähnliche Formen der Anreicherung gehören.
|
LLM integration serves semantic processing of documents. This can include tagging, content structuring, classification, or similar forms of enrichment.
|
||||||
|
|
||||||
### 8.6 API-first
|
### 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.
|
The roadmap provides for initially making the interface exclusively operationally usable. A frontend is intentionally deferred so that core functionality can be built independently and stably.
|
||||||
|
|
||||||
### 8.7 Dokumentation
|
### 8.7 Documentation
|
||||||
|
|
||||||
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.
|
Architecture and system documentation shall be maintained in an arc42-oriented form. The documentation shall clearly depict essential decisions, components, processes, risks, and quality requirements.
|
||||||
|
|
||||||
## 9. Architekturentscheidungen
|
## 9. Architectural Decisions
|
||||||
|
|
||||||
- Das System wird zunächst als Backend- bzw. API-zentrierte Lösung umgesetzt.
|
- The system is initially implemented as a backend and API-centric solution.
|
||||||
- Ein Frontend ist Teil einer späteren Ausbaustufe und nicht Bestandteil der ersten Roadmap.
|
- A frontend is part of a later expansion phase and not part of the initial roadmap.
|
||||||
- Die Lösung soll bewusst einfach gehalten werden.
|
- The solution shall intentionally be kept simple.
|
||||||
- Frameworks und externe Systeme sollen nur zurückhaltend eingesetzt werden.
|
- Frameworks and external systems shall be used sparingly.
|
||||||
- Event Sourcing wird als fachliches Konzept zur Nachvollziehbarkeit und Konsistenz berücksichtigt.
|
- Event Sourcing is considered as a business concept for traceability and consistency.
|
||||||
- Technologische Festlegungen für Event-Sourcing-Mechanismen werden in dieser Dokumentation bewusst vermieden.
|
- Technological commitments to Event Sourcing mechanisms are intentionally avoided in this documentation.
|
||||||
- Die Architektur wird konsequent auf Testbarkeit ausgelegt.
|
- The architecture is consistently designed for testability.
|
||||||
- Unit-Tests sind kein Optionalbestandteil, sondern verbindlicher Bestandteil der Umsetzung.
|
- Unit tests are not optional but a binding part of the implementation.
|
||||||
- Volltextsuche ist ein verpflichtender Bestandteil des Systems.
|
- Full-text search is a mandatory component of the system.
|
||||||
- Ein automatischer Import über einen überwachten Ordner ist ein verpflichtender Bestandteil des Systems.
|
- Automatic import from a monitored folder is a mandatory component of the system.
|
||||||
- Verarbeitete Dokumente werden in eine finale, strukturierte Zielablage überführt.
|
- Processed documents are transferred to a final, structured target storage.
|
||||||
- Die finale Ablage berücksichtigt Jahresordner und optional Import-Zeitstempel in Dateinamen.
|
- Final storage considers year-based folders and optionally import timestamps in filenames.
|
||||||
- Für Automatisierung im Entwicklungs- und Deployment-Prozess wird die vorhandene Gitea-/Actions-Umgebung berücksichtigt.
|
- Automation in development and deployment processes shall consider the existing Gitea/Actions environment.
|
||||||
|
|
||||||
## 10. Qualitätsanforderungen
|
## 10. Quality Requirements
|
||||||
|
|
||||||
Wesentliche Qualitätsanforderungen sind:
|
Essential quality requirements are:
|
||||||
|
|
||||||
- Einfachheit: Das System soll mit minimaler unnötiger Komplexität entworfen werden.
|
- Simplicity: The system shall be designed with minimal unnecessary complexity.
|
||||||
- Wartbarkeit: Die Bausteine sollen klar getrennt und verständlich aufgebaut sein.
|
- Maintainability: Components shall be clearly separated and understandably structured.
|
||||||
- Testbarkeit: Jede wesentliche Funktionalität soll unit-testbar sein.
|
- Testability: Every essential function shall be unit-testable.
|
||||||
- Nachvollziehbarkeit: Dokumentänderungen und Statusübergänge sollen über Ereignisse nachvollziehbar bleiben.
|
- Traceability: Document changes and state transitions shall remain traceable through events.
|
||||||
- Konsistenz: Zustände und Übergänge sollen robust und rekonstruierbar sein.
|
- Consistency: States and transitions shall be robust and reconstructible.
|
||||||
- Automatisierbarkeit: Import, Verarbeitung, Test und Deployment sollen automatisierbar sein.
|
- Automatability: Import, processing, testing, and deployment shall be automatable.
|
||||||
- Erweiterbarkeit: Ein späteres Frontend soll auf der vorhandenen API und Architektur aufsetzen können.
|
- Extensibility: A later frontend shall be able to build on the existing API and architecture.
|
||||||
- Suchbarkeit: Dokumentinhalte sollen zuverlässig per Volltextsuche auffindbar sein.
|
- Searchability: Document contents shall be reliably discoverable via full-text search.
|
||||||
- Zuverlässigkeit: Automatische Ordnerüberwachung und Verarbeitung sollen stabil funktionieren.
|
- Reliability: Automatic folder monitoring and processing shall function stably.
|
||||||
|
|
||||||
## 11. Risiken und technische Schulden
|
## 11. Risks and Technical Debt
|
||||||
|
|
||||||
Mögliche Risiken:
|
Possible risks:
|
||||||
- Event Sourcing erhöht die fachliche und technische Komplexität, wenn es zu breit oder zu früh umgesetzt wird.
|
- Event Sourcing increases business and technical complexity if implemented too broadly or too early.
|
||||||
- OCR-Qualität kann je nach Dokumentenqualität schwanken.
|
- OCR quality can vary depending on document quality.
|
||||||
- LLM-gestützte Anreicherung kann variierende Ergebnisse liefern und muss fachlich eingeordnet werden.
|
- LLM-supported enrichment can yield varying results and must be understood in business context.
|
||||||
- Automatische Dateiüberwachung und Verschiebung erfordern robuste Fehlerbehandlung, um Doppeleinträge oder inkonsistente Zustände zu vermeiden.
|
- Automatic file monitoring and relocation require robust error handling to avoid duplicates or inconsistent states.
|
||||||
- Ohne frühzeitige Tests steigt das Risiko, dass Dateiverarbeitung, Suchindexierung und Ereignisabläufe schwer wartbar werden.
|
- Without early testing, the risk increases that file processing, search indexing, and event flows become difficult to maintain.
|
||||||
|
|
||||||
Offene Punkte, die später zu konkretisieren sind:
|
Open items to be clarified later:
|
||||||
- Genaues Ereignismodell.
|
- Exact event model.
|
||||||
- Exaktes Metadatenmodell.
|
- Precise metadata model.
|
||||||
- Fehlerbehandlungsstrategie bei partiell fehlgeschlagener Verarbeitung.
|
- Error handling strategy for partially failed processing.
|
||||||
- Detailregeln der finalen Ordnerstruktur.
|
- Detailed rules for the final folder structure.
|
||||||
- Such- und Ranking-Verhalten der Volltextsuche.
|
- Search and ranking behavior of full-text search.
|
||||||
|
|
||||||
## 12. Glossar
|
## 12. Glossary
|
||||||
|
|
||||||
- API: Programmierschnittstelle zur Nutzung der Systemfunktionen.
|
- API: Application Programming Interface for using system functions.
|
||||||
- OCR: Texterkennung aus Dokumenten oder Bildinhalten.
|
- OCR: Optical Character Recognition; text recognition from documents or image contents.
|
||||||
- LLM: Sprachmodell zur semantischen Verarbeitung und Anreicherung von Dokumentinhalten.
|
- LLM: Large Language Model for semantic processing and enrichment of document contents.
|
||||||
- Event Sourcing: Fachliches Konzept, bei dem Zustandsänderungen als Ereignisse festgehalten werden.
|
- Event Sourcing: Business concept in which state changes are recorded as events.
|
||||||
- Volltextsuche: Suche über die vollständigen textuellen Inhalte von Dokumenten.
|
- Full-Text Search: Search across the complete textual contents of documents.
|
||||||
- Import-Ordner: Überwachter Ordner, aus dem Dokumente automatisch übernommen werden.
|
- Import Folder: Monitored folder from which documents are automatically ingested.
|
||||||
- Jahresordner: Zielordnerstruktur, in der verarbeitete Dokumente nach Jahren abgelegt werden.
|
- Year Folder: Target folder structure where processed documents are stored by year.
|
||||||
- Finale Ablagestruktur: Endgültige strukturierte Speicherung verarbeiteter Dokumente.
|
- Final Storage Structure: Final structured storage of processed documents.
|
||||||
Reference in New Issue
Block a user