govoplan-records/docs/EAKTE_ARCHITECTURE.md

eAkte Architecture

Purpose

The eAkte is the authoritative institutional record context for a matter, procedure, subject, project, or responsibility. It answers what belongs to the record, how it is structured, why an item was filed, which version was known, who may use it for which purpose, when it closes, what must be retained, and how it is offered, transferred, preserved, or disposed.

GovOPlaN Records should provide this governance lifecycle natively while being able to place it over an external DMS, records system, long-term archive, or specialist procedure. It must not duplicate all document editing or storage.

Implementation is tracked in Records #1.

Implementation Status

The native foundation and governed lifecycle are implemented through the work packages tracked by Records #2-#6:

• versioned file plans and record classes;
• stable records, immutable revisions, volumes, exact record items, and chronology;
• tenant isolation, optimistic concurrency, replay-safe writes, independent valid/recorded time, purpose capture, institutional context, and search;
• a full-height eAkte workspace with file plan, list, details, chronology, temporal status, create/edit, and filing actions;
• a provider-neutral Core filing contract with exact Files-version, Cases-revision, Forms-submission, and formal-Decision providers;
• governed close/reopen transitions, class-bound retention calculation, effective-dated holds, appraisal, evidence-bound disposition proposals, and mandatory independent approval before finalization;
• archive-neutral transfer manifests and bounded receipts, plus an explicitly non-conformant simulation provider that never claims custody;
• durable recovery-ledger fences for every API write, atomic domain/checkpoint commits, Audit events, source-revision revalidation, transfer-manifest checksum checks, and an operator recovery-evidence view;
• tenant administration for versioned file-plan nodes and record classes, explicit volume management, and lifecycle controls in the eAkte workspace.

The remaining boundary is intentionally visible rather than implied: Records #7 requires selection and target testing of an archive/xdomea endpoint and conformance profile; #8 completes the cross-module reference journey and production evidence. Restricted per-record access grants also remain a dedicated access-policy slice. Destruction is represented only as an approved pending state; no content deletion or real archive effect is currently claimed.

Ownership Boundary

Records owns:

• file plans and record classes;
• record, volume, process/file, and record-item identity;
• classification, filing decision, ordering, and relationship to a case or other institutional context;
• effective retention rule application, closure, hold, appraisal, disposition proposal, approval, transfer, and destruction evidence;
• authoritative record metadata and exact content/reference manifests;
• external records-system mappings and source-authority mode;
• export, transfer, archive-offer, and custody receipts.

Records does not own:

• file bytes, versions, previews, or malware handling (Files);
• collaborative document editing, check-in/check-out, document review, or DMS provider behavior (DMS and connector owner);
• generated document definitions (Templates);
• case lifecycle (Cases), work coordination (Workflow Engine/Tasks), formal outcomes (Decisions), or general audit events (Audit);
• generic retention and access policy authoring (Policy);
• archive preservation implementation or evidence-renewal cryptography (external archive/TR-ESOR provider and Encryption/Identity Trust).

Core Object Model

Object	Meaning
File plan	Versioned hierarchy derived from institutional responsibilities
Record class	Rules for required metadata, allowed content, access, retention, closure, and disposition
Record	Stable legal/institutional record identity and context
Volume/part	Bounded subdivision for size, period, classification, or custody
Process/file	Optional business transaction grouping inside a record
Record item	Immutable filing event linking exact content or an external object revision
Filing note	Reason, source, relationship, ordering, actor/capacity, and evidence for inclusion
Hold	Effective-dated suspension of disposition with authority and scope
Appraisal	Archive value/offer decision and responsible archive interaction
Disposition case	Proposed retain, transfer, destroy, or reclassify action with review and evidence
Transfer package	Exact metadata/content manifest, profile, digest, encryption, and receipts
Custody event	Handoff, acceptance, rejection, correction, return, or destruction observation

Every object carries tenant/institution, valid and recorded time, revision, source authority, classification, purpose constraints, retention/hold state, institutional context, provenance, and optimistic-concurrency token.

Record Lifecycle

planned -> open -> closed -> retention_running -> appraisal_due
                                    |                  |
                                    v                  v
                                  held          offered_to_archive
                                                       |
                         +-----------------------------+------------------+
                         v                             v                  v
                      accepted                      rejected          retained
                         |                             |                  |
                         v                             v                  v
                    transferred                 disposal_due        reappraise
                                                       |
                                                       v
                                                   destroyed

Reopening creates a governed transition and preserves the preceding retention schedule. A later closure only restarts retention under an explicit administrator action. A hold preserves reason, authority, scope, effective interval, policy references, and release evidence. Holds block proposal, approval finalization, packaging, and dispatch. A destruction approval changes the record to destruction_pending; no source object or content is deleted. An unapproved disposition can be withdrawn through a new immutable revision so a corrected proposal can supersede it. An approved disposition cannot use this correction path.

Filing Semantics

• Filing links an exact immutable document/file/object revision; a later source revision is a new record item unless the record class permits an explicitly tracked living reference.
• The item records valid time of the represented fact and recorded time of filing independently.
• The current security context always controls browsing, including historical views.
• Purpose-aware access may be narrower than ordinary read permission and can require case assignment, represented function, mandate, legal basis, or reason-for-access capture.
• A record item can reference a message, decision, form submission, report, dataset materialization, external DMS object, physical item, or paper scan; it is not limited to Files.
• Corrections and replacements link items and retain what was previously part of the record.

Native, External, And Hybrid Operation

Mode	GovOPlaN behavior
Native authoritative	Records owns lifecycle and manifests; Files or object storage owns bytes
External authoritative	External eAkte/DMS owns structure and lifecycle; GovOPlaN keeps governed references and provider state
External mirror	GovOPlaN keeps a read/search projection and immutable evidence snapshots
Governed sync	Explicit metadata/filing fields can change on both sides with revision and conflict rules
Governance overlay	GovOPlaN owns case/workflow/policy/evidence around records held externally
Linked reference	Only stable identity, display metadata, authority, and launch link are retained

The mode is configurable by tenant, record class, provider binding, and where safe by field group. A migration assesses exact objects and receipts; enabling a connector never silently copies all records.

Standards And Provider Profiles

The domain contract remains neutral, while German public-sector deployments can add profiles for:

• xdomea exchange of files, processes, documents, file plans, and disposition messages. The IT-Planungsrat decision defines xdomea for inter-authority exchange and disposition scenarios: https://www.it-planungsrat.de/beschluss/beschluss-2017-39
• archive offering and transfer guidance from the Bundesarchiv, including xdomea and XAIP/LXAIP packages: https://www.bundesarchiv.de/unterlagen-abgeben/aussonderung-von-unterlagen/elektronische-akten/
• BSI TR-03125/TR-ESOR evidence preservation and archive information packages where cryptographic evidentiary value must be maintained: https://www.bsi.bund.de/dok/TR-03125
• provider-specific DMS/VBS, archive, and specialist-procedure adapters through the standard external-provider declaration and recovery gate.

A profile declares supported operations, conformance version, metadata mapping, content formats, evidence behavior, size limits, retries, conflicts, and target-tested provider. Naming a standard is not a conformance claim.

UI Model

The normal record workspace contains:

• file-plan tree and saved institutional contexts;
• record list with class, subject, responsibility, state, retention, holds, source, and access explanation;
• one record surface with metadata, chronology, structured contents, related case/service/decision/work, access reason, and evidence;
• filing action available from owner modules without exposing Records internals;
• close, reopen, hold, appraisal, transfer, and disposition workflows with consequence preview;
• temporal current/at/all browsing, while clearly separating valid and recorded time;
• search and export that honor current access, purpose, sealed content, and minimization.

Technical provider IDs, hashes, package schemas, and source mappings remain available in an evidence/details view.

Recovery And Scale

• PostgreSQL is the durable record-state authority; content uses shared object storage or an external provider, never node-local paths.
• Every external filing, transfer, or destruction uses intent-before-effect, idempotency, durable receipts, outcome-unknown state, and reconciliation.
• Native Records API writes use a per-resource distributed lease and the Core recovery ledger. Immutable revision, chronology, Audit projection, and the terminal checkpoint commit atomically.
• Backup evidence binds record rows, object manifests, provider mappings, policy/configuration versions, and key references.
• Restore verifies content digests, missing keys/objects, provider reachability, and disposition holds before reopening effects.
• Automated evidence tests prove that terminal Records operations and their hash chain remain verifiable after a database backup/restore round trip. An outcome-unknown transfer is persisted as non-retryable and cannot advance custody or record disposition state.
• Search indexes are rebuildable projections and cannot become record authority.

Delivery Order

1. Persist file plans, record classes, records, record items, exact references, chronology, permissions, temporal reads, institutional context, and search.
2. Integrate filing from Cases, Forms Runtime, Decisions, Campaign/Postbox, Files, and Reporting. Cases, Forms Runtime, Decisions, and Files are implemented; Campaign/Postbox and Reporting remain.
3. Add closure, retention calculation, holds, appraisal, and reviewed disposition without destructive provider effects. Implemented.
4. Add native transfer packages and one target-tested xdomea/archive provider. Native packaging and simulation are implemented; target selection/testing remains external.
5. Add destruction/recovery, TR-ESOR provider integration, migration, and signed reference-journey evidence.

The first reference package should file the digital and assisted variants of the same service-to-decision journey into equivalent records and prove search, historical reconstruction, hold, transfer, restore, and access explanation.