GovOPlaN/govoplan-cases
2
0
Fork 0
Code Issues 1 Pull Requests Actions Packages Projects Releases Wiki Activity
Page: Repo-docs-CONCEPT
Pages
Repo-README Repo-docs-CONCEPT
Clone
1
Repo-docs-CONCEPT
zemion edited this page 2026-08-01 08:55:50 +02:00
Table of Contents

Mirrored from /mnt/DATA/git/govoplan-cases/docs/CONCEPT.md. Origin: repository. Active tasks and changing state belong in Gitea issues; this wiki page is durable project context.

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.

MVP Slice

The first implementation should provide:

  • case type registry with a minimal tenant-local configuration
  • create/list/read/update case APIs
  • status values with a simple configurable catalog
  • 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
  • case timeline from local events plus linked audit event IDs
  • basic WebUI list/detail route
  • resource ACL provider for case read/update
  • tenant summary provider for dashboard counts

Permissions

Candidate scopes:

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

Access decisions should combine tenant permissions, case ownership/assignment, and explicit case shares when those are introduced.

Data Model Sketch

Candidate tables:

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

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

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

WebUI

Initial route contributions:

  • /cases
  • /cases/:caseId

The case detail view should expose extension points for linked forms, files, tasks, workflow state, appointments, documents, communication, payment evidence, and audit timeline. Extension points must be declarative; no direct UI imports from sibling modules.

Tests

Minimum tests:

  • core can start with cases present and sibling modules absent
  • creating a case emits a case event and audit event
  • case ACL blocks unauthorized read/update
  • evidence links accept only module/resource references
  • optional modules can contribute detail panels without direct imports
  • migration metadata registers through the module manifest

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.
  • Whether case shares are local to cases or use a generic resource ACL module.