This website requires JavaScript.
Component Diagram: API Backend — Document Management & Canonical Import Component Diagram: API Backend — Document Management & Canonical Import API Backend (Spring Boot) [system] «component» DocumentController [Spring MVC — /api/documents] CRUD for documents: search, get by ID, update metadata, upload/download file, batch metadata updates, and per-month density aggregation for the timeline filter widget. «component» AdminController [Spring MVC — /api/admin] Triggers the asynchronous canonical import (requires ADMIN permission). Reports import state (IDLE/RUNNING/DONE/FAILED). Hosts the one-shot maintenance backfills (versions, file-hashes, titles) — synchronous, ADMIN-only. «component» DocumentService [Spring Service] Core document business logic: store, update, search. On update, regenerates an unchanged auto-title from the new date/location (exact old-vs-new match, #726); exposes backfillTitles() to clean already-stale titles in one sweep. Resolves persons and tags, delegates file I/O to FileService, builds dynamic JPA Specifications, and integrates with audit logging. «component» FileService [Spring Service] Wraps AWS SDK v2 S3Client. Uploads files with UUID-keyed paths, computes SHA-256 hash, downloads with content-type detection, and generates presigned URLs for OCR access. «component» CanonicalImportOrchestrator [Spring Service — @Async] Runs the four canonical loaders in an explicit dependency DAG (TagTree → PersonRegister → PersonTree → Document). Smoke-checks all four artifacts before starting, owns the IDLE/RUNNING/DONE/FAILED state machine, fails closed on a malformed artifact. «component» TagTreeImporter [Spring Component] Upserts the tag hierarchy from canonical-tag-tree.xlsx via TagService (by canonical tag_path). «component» PersonRegisterImporter [Spring Component] Upserts register persons from canonical-persons.xlsx via PersonService (by normalizer person_id). «component» PersonTreeImporter [Spring Component] Upserts tree persons + relationships from canonical-persons-tree.json via PersonService and RelationshipService. «component» DocumentImporter [Spring Component] Loads canonical-documents.xlsx: routes attribution register-first (raw cell always retained in sender_text/receiver_text), parses clean dates, builds the title via DocumentTitleFactory, keeps the S3 upload + thumbnail plumbing, and resolves each PDF by index (importDir/<index>.pdf) guarded by strict index validation + canonical-path containment + %PDF magic-byte check (no recursive walk). «component» DocumentTitleFactory [Spring Component] Single source of truth for the auto-title {index} – {dateLabel} – {location} (#726). The document package owns this formula; importer, save-time regeneration, and the backfill all build through it so they never diverge. «component» DocumentTitleFormatter [Pure helper (document pkg)] Formats the date label at exactly the data's precision (MONTH -> 'Juni 1916', never a fabricated day). Mirrors the frontend formatDocumentDate; both are pinned to docs/date-label-fixtures.json (#666). «component» DocumentTitleBackfillMatcher [Pure helper] Backfill-only heuristic deciding whether a STORED title is machine-generated (overwritable) vs hand-written prose. Index matched literally (no regex injection / ReDoS); fail-closed. «component» CanonicalSheetReader [POI helper] Maps a canonical .xlsx by header name (no positional indices), splits pipe-delimited list columns, fails closed (IMPORT_ARTIFACT_INVALID) on a missing required header. «component» MinioConfig [Spring @Configuration] Creates the S3Client and S3Presigner beans with path-style access for MinIO. Validates MinIO connectivity on startup. «component» DocumentRepository [Spring Data JPA] Queries documents with Specification-based dynamic search, full-text search with ranking and match highlighting, and transcription pipeline queue projections. «component» DocumentSpecifications [JPA Criteria API] Factory for composable predicates: hasText (full-text), hasSender, hasReceiver, isBetween (date range), hasTags (subquery AND/OR logic). «container» Web Frontend [SvelteKit] «container» PostgreSQL [PostgreSQL 16] «container» Object Storage [MinIO (S3-compatible)] «component» PersonService [Spring Service] See diagram 3e. Resolves sender / receiver persons by ID; upserts persons by source_ref for the importer. «component» TagService [Spring Service] See diagram 3d. Finds or creates tags by name; upserts tags by source_ref for the importer. «component» RelationshipService [Spring Service] See diagram 3e. Creates family relationships from the person tree during import. Document requests [HTTP / JSON] Trigger import [HTTP / JSON] Delegates to Triggers Upload / download files Reads / writes documents Builds search predicates Resolves sender / receivers Finds or creates tags 1. Loads tags 2. Loads register persons 3. Loads tree persons + relationships 4. Loads documents Reads canonical .xlsx Reads canonical .xlsx Reads canonical .xlsx Builds the auto-title Regenerates auto-title (save-time + backfill) Backfill overwrite test Formats the honest date label backfillTitles() / backfillFileHashes() Upserts tags by source_ref Upserts persons by source_ref Upserts persons by source_ref Creates relationships Upserts documents by index Register-first match / provisional person Attaches tag by source_ref Uploads resolved file Provides S3Client and S3Presigner beans PUT / GET / presigned URL objects [S3 API / HTTP] SQL queries [JDBC]
cf457cb96f