govoplan-cases/docs/CONCEPT.md

govoplan-cases Concept

Purpose

govoplan-cases is the formal administrative case module. It creates a durable container for a procedure such as a permit application, inspection, complaint, grant request, or internal administrative matter.

The case is not the workflow engine and not the file store. It is the stable record that ties together participants, status, assignments, deadlines, evidence, decisions, communications, audit events, and retention references.

Ownership

The module owns:

• case identifiers, references, titles, types, and status
• case-local party references and role labels such as applicant, respondent, beneficiary, and representative, using a shared Parties contract when present
• case metadata and tags
• due dates, service-level targets, and milestone dates
• links to evidence provided by other modules
• case comments and internal notes once the collaboration boundary is decided
• case-level access checks and resource ACL contributions
• case event emission for lifecycle changes
• case summary APIs and WebUI route contributions

The module does not own:

• form submissions and validation, owned by forms/forms-runtime
• binary file storage, owned by files or DMS
• workflow state machines and transition execution, owned by workflow
• work queues and task assignment semantics, owned by tasks
• generated documents, owned by templates/DMS
• appointments, mail, notifications, postbox, payments, or ledger postings
• identity/contact/organization masters, representation powers, formal institutional decision semantics, mandates, or jurisdiction

Core Contracts

The module should integrate through:

• module manifest metadata, route factories, permissions, and migrations
• a cases.access or similar case access capability for resource checks
• a cases.summary capability for dashboards and cross-module previews
• shared party, mandate, service, and decision reference DTOs when those providers are available
• events such as case.created, case.updated, case.status_changed, case.assigned, and case.closed
• commands such as cases.open, cases.update_status, cases.link_evidence, and cases.assign
• DTOs with stable IDs and labels, not ORM objects

Other modules should link to a case by stable references:

{
  "case_id": "case-uuid",
  "tenant_id": "tenant-uuid",
  "relation": "submission"
}

Reference Journey

Permit-to-payment MVP:

1. Portal/forms runtime receives a public application.
2. Workflow asks cases to create a case record.
3. Files/DMS links uploaded evidence to the case.
4. Tasks assigns an internal review task.
5. Workflow moves the case from intake to review to appointment to decision.
6. Templates generates the permit or decision document and links it to the case.
7. Payments links payment evidence.
8. Audit and records retain the case history.

Implemented MVP Backend

The persistent backend provides:

• tenant-local case type and status catalogs with guarded revisions
• create/list/read/update/history/timeline APIs
• stable case identities and immutable OCC-guarded record revisions
• parties stored as stable procedure-party references with a compatibility path for direct identity/organization references; assignments remain responsibility references
• evidence links as module/resource references
• replay-safe case timeline events carrying the institutional context and a stable event/audit reference
• tenant-level resource ACL and tenant summary providers
• tenant-wide or restricted object access with explicit, revisioned grants
• deterministic, replay-safe case launch from an exact Service binding
• deterministic, replay-safe Case escalation from an authorized Ticket handoff

The /cases list and /cases/:caseId detail workspace provide server-side search/status filtering, case facts, typed references, history, timeline, and OCC-guarded title/status/access revisions with an explicit change reason. Restricted cases are visible to their creator, case administrators, explicit user/group grants, and matching function, function-assignment, or organization-unit assignments. The same decision filters list, detail, history, timeline, and update operations so an inaccessible identifier does not disclose case existence. API reads and writes are tenant-bound, and create/update/assign/close/share/catalog operations have separate permissions.

Permissions

Implemented scopes:

• cases:case:read
• cases:case:create
• cases:case:update
• cases:case:assign
• cases:case:close
• cases:case:share
• cases:case:admin

Access decisions combine tenant permissions, creator/administrative authority, case assignments, and explicit case shares. Restricted access is versioned with the case record so its history remains reconstructable.

Data Model Sketch

Candidate tables:

• cases
• case_parties
• case_assignments
• case_evidence_links
• case_timeline_entries
• case_type_definitions
• case_status_definitions
• case_access_grants

case_parties is a compatibility seed for a Cases-only composition. It must not grow a second identity/contact master or duplicate effective-dated powers of representation. Once a shared Parties provider exists, Cases should retain the provider reference plus the minimal immutable role/evidence snapshot needed to reconstruct the case.

The implemented headless compatibility path therefore accepts only a stable subject reference, case-local role, effective interval, permitted/preferred channels, delivery flag, evidence, and immutable contact snapshot references. It cannot model representation powers. When parties.resolver is available, Cases uses its effective, tenant-scoped party and representation records and rejects mismatched procedures or conflicting active role assignments. Shared Core revision helpers keep corrections, expiry, supersession, and revocation immutable and OCC-guarded. Representation revocation has its own effective timestamp so a historical delivery decision can be reconstructed.

cases.service_intake consumes a published, effective shared Service definition. It requires one case binding and preserves the exact Service version plus its responsible unit/function, Mandate, jurisdictions, legal bases, required evidence, deadlines, forms, workflows, and result bindings in a governed intake plan. It does not copy or persist the Service definition.

cases.service_launcher is the effect boundary used by Portal. It derives a stable case ID from tenant, exact Service revision, and idempotency key, creates the case through the normal registry, and returns that exact case and Service reference. Retrying the same launch returns the existing case; a changed request cannot reuse the key. Portal therefore cannot create duplicate cases after an ambiguous network response and does not gain access to Cases tables.

tickets.case_escalation is the optional effect boundary used by Tickets. It rechecks cases:case:create, tenant identity, and the requested active Case type, then derives a stable Case identifier from the Ticket and idempotency key. The Case stores a governed work_item reference plus bounded source and handoff metadata. It never imports Tickets or copies Ticket messages, files, participants, assignment, or lifecycle. Replaying the same handoff returns the existing Case, while an unavailable Cases capability leaves the operational Ticket intact.

Cases links formal Decision records and may retain a current outcome/status projection. It does not own decision authority, rule versions, reasoning, correction, revocation, or remedy semantics.

The Case detail decision path is a guarded composition boundary. It resolves an exact Case revision, rechecks Case update access, verifies the current acting assignment through Access, and requires exactly one effective Mandate for cases.formal_decision and the selected Decision type. Only then does it call the optional Decisions registry and append the exact Decision reference to a new Case revision in the same transaction. Deterministic identifiers make an unchanged retry safe, while changed replay payloads and stale Case revisions fail closed. Cases still does not store the protected result or reasoning.

Evidence links should store only stable module/resource references and display metadata snapshots. The owning module remains responsible for the real object.

When Records is enabled, records.source.cases resolves one exact immutable case revision for eAkte filing. Cases rechecks current tenant, scope, and object-level access, then returns the case number, lifecycle state, represented valid interval, recorded time, canonical snapshot digest, and launch link. Records owns the filing decision and chronology; Cases remains authoritative for the case and its revision history.

When Search is enabled, cases.cases indexes current Case titles, numbers, types, states, and the existing bounded search projection. It includes no provider-owned evidence content or protected Decision reasoning. Restricted Case candidates carry bounded ACL tokens and every result is checked again against the current Case object-access decision before disclosure.

WebUI

Initial route contributions:

• /cases
• /cases/:caseId

The detail view renders the module-owned record, stable references, history, timeline, and provider-resolved formal Decisions when currently authorized. It can record a direct officer Decision when Access, Mandates, and Decisions are enabled and can launch exact Case or Decision filing when Records is enabled. Future linked forms, files, tasks, workflow state, appointments, documents, communication, payment evidence, and richer audit panels must arrive through declarative extension points, without direct UI imports from sibling modules.

Tests

The focused suite covers:

• provider-neutral Service intake and Party resolution
• committed-only lifecycle events with institutional context
• replay conflict detection, stale revision rejection, and immutable history
• tenant isolation, terminal status handling, and server-side filtering
• stable typed assignment/evidence/Decision/record references
• migration, uninstall-guard, ACL, summary, and capability registration
• explicit and assignment-derived case access, including non-disclosure
• exact Service launch, deterministic replay, and conflict behavior

Data-subject requests

Cases publishes privacy.dsar.cases. Canonical account, identity, and membership selectors cover Cases-owned operator attribution; account and identity selectors also cover explicit case-access grants. Exact cases.case, cases.revision, cases.access_grant, and cases.timeline references select lifecycle data. When a canonical and direct selector are combined, a Cases-owned relationship must corroborate them and all supplied direct references must identify the same case.

Direct case results are typed projections rather than stored snapshots. They exclude opaque metadata, search text, free-text change reasons, timeline payloads and summaries, evidence identifiers, request hashes, idempotency keys, audit identifiers, and unrelated access subjects. Applicant-to-identity correlation is owned by Parties; Cases does not infer it from opaque party identifiers. Immutable case identities, revisions, timelines, and operator attribution receive retention actions. Current open case facts and active access grants receive non-executable manual-review actions and can only be changed through the authorized case/access lifecycle.

Open Decisions

• Whether comments belong in cases, tasks, or a collaboration module.
• Whether case type/status catalogs are fully configurable in MVP or seeded.
• How records/legal-hold integration should own retention of closed cases.