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.

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 does not reset elapsed retention without an explicit rule. A hold preserves the reason and affected scope. A destruction action requires exact manifest, current authority, policy, approval, preflight, idempotency, outcome-unknown recovery, and evidence.

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.
• 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.
• 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.
3. Add closure, retention calculation, holds, appraisal, and reviewed disposition without destructive provider effects.
4. Add native transfer packages and one target-tested xdomea/archive provider.
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.