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