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](https://git.add-ideas.de/GovOPlaN/govoplan-records/issues/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

```text
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.