diff --git a/README.md b/README.md new file mode 100644 index 0000000..2fb854a --- /dev/null +++ b/README.md @@ -0,0 +1,11 @@ +# govoplan-cases + +`govoplan-cases` will own formal administrative case records for GovOPlaN. + +The module should stay focused on case identity, lifecycle state, assignments, +deadlines, participants, evidence links, and case-level audit context. It should +not own forms, files, workflow execution, task queues, templates, payments, or +mail delivery; those are integrated through GovOPlaN capabilities, events, +commands, and DTOs. + +See [docs/CONCEPT.md](docs/CONCEPT.md) for the current module concept. diff --git a/docs/CONCEPT.md b/docs/CONCEPT.md new file mode 100644 index 0000000..83212b5 --- /dev/null +++ b/docs/CONCEPT.md @@ -0,0 +1,143 @@ +# 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 parties and role labels such as applicant, assignee, reviewer, and owner +- 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 + +## 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 +- 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: + +```json +{ + "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 and assignments stored as access subject 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` + +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.