The files in this directory define the platform-neutral case-management and billing model. They describe required concepts and behavior, not how a specific technology stores or implements them.
- Treat stable identifiers such as entity, field, and rule keys as API-like contracts. Rename them only through an explicit migration decision.
- Use
snake_casefor identifiers and singular nouns for entities. - Use display names and descriptions for human-readable language. Do not use a display name as an identifier.
- Represent implementation-specific choices outside the canonical model.
- Prefer references to duplicated data.
- Add enums and reference values only after the allowed values are understood.
- Keep calculated values out of the canonical record unless history or audit requirements require a stored snapshot.
- Keep
spec_versionunchanged until the initial model has been pushed. After that push, increasespec_versionwhen a model file changes. Before1.0.0, breaking changes are allowed but must be documented for reviewers.
schema.yamldefines entities, fields, and relationships.rules.yamldefines business requirements that implementations must enforce or explicitly document as gaps.forms.yamldefines case intake using case fields and related-record inputs.create-case.mdproposes the shared intake request/result, atomic effects, retry and error contract; it is not yet a deployed operation.workflows.yamldefines lifecycle, payment-request and invoice-import transitions.
Acceptance scenarios live in ../scenarios/. Reference sets named by
reference_data remain configurable vocabularies, not entity foreign keys.
Synthetic implementation fixtures do not establish canonical reference values.
See the model review for migration and open decisions.
A professional may have one qualification level through the optional
professional.qualification_level_id reference to qualification_levels.
Allowed levels remain to be defined as configurable reference data. This is
separate from professional_qualification, which records qualifications for
specific case categories. How qualification levels affect assignment eligibility
remains an unresolved decision.
An office is an organizational unit, optionally linked to an organization.
person_affiliation records effective organization/office membership and supports
multiple memberships over time. Assignment and participant records may retain a
specific affiliation. professional.office_id is now only an optional primary
office projection; it cannot replace affiliation history or grant access.
A county has a stable identifier, display name, and active status. Each case
may be associated with one county through the optional case.county_id
reference; a county may be associated with many cases.
Some cases are recorded with a setting in place of a county, such as
post-conviction or prison. These are county rows with is_county false, so a
case still has one value; pickers list them first. Users add a county that
isn't listed by typing it, and imports suggest one read from the file
(record_case_county in rules.yaml).
The case association is provisional. Whether counties should also or instead be associated with offices or professionals remains unresolved.
Each invoice has an ordered invoice_approval_chain. Each
invoice_approval_decision carries its own sequence_number and
step_type_id against the chain. invoice_review_assignment records who is
expected to act at each step: one line reviewer, and one or more sign-off
approvers in order. Assignments come from the case's case_invoice_reviewer
or the deployment's invoice_review_setting defaults, and staff may change
them (assign_invoice_review); ending and replacing an assignment keeps who
held the request. Configured policy may require invoice-level pre-approval by
another user before line review begins. This pre-approval is separate from
external-service preauthorization.
The invoice_approval_step_types reference data must distinguish invoice
pre-approval, line review and sign-off. invoice_approval_outcomes must
distinguish approval, rejection, and requests for changes.
invoice_decision_reasons lists why a line was approved in part or rejected;
each entry says which of the two lists it is on, or both, and administrators
maintain the lists.
invoice_receipt_channels lists how a request that staff entered for a
professional arrived, such as email or another tool
(authorize_staff_invoice_entry). Reference-data identifiers remain
configurable.
During review the reviewer's line decisions are invoice_line_working_decision
rows they can undo or change freely; these are not history. Finishing the
round records every line's decision as an immutable invoice_approval_decision
at a new sequence number (decide_invoice_lines). A rejected line is decided
with nothing approved and does not block the request. Sign-off decisions cover
the whole request; an approver may send it back to the reviewer with an
internal_only comment, which opens another round in the same chain. The
latest round's amounts are the approved amounts, and earlier rounds remain as
history. Line decision notes are visible to submitters; internal-only comments
are not (limit_review_comment_visibility). Overall approval is derived from a
complete latest round and every assigned approver's sign-off.
Only one chain per invoice may be non-superseded. Invoice contents and the
chain's decisions are frozen during that review attempt. Corrections or renewed
review require superseding the chain, preserving the reviewed values and
decisions, and starting a new chain without reusing old approvals. Each chain
now requires an immutable submission_snapshot, as described below.
Implementations must enforce the history requirement or document the gap.
The model uses sequential steps with one assigned user per step. Parallel review and delegation remain unresolved. External payment execution is outside the system boundary. Line decisions record approved amounts separately from requested amounts. An approval in part may also record the corrected hours or rate it was priced at.
person is contact identity. professional is an optional one-to-one profile
of that identity, carrying attributes (qualification, office, active) beyond
identity. Client is not a profile: an existing person participates in many
cases in different configured roles, including client, through
case_participant; do not add a client entity back. user_account remains
authenticated identity. Providers retain service_provider as a payee profile
of either a person or organization. Programs and funding sources remain simple
reference values; their effective case associations are child records. Do not
create an organization for each program, or a separate person for each
professional role.
case_participant.participant_role_id, person_affiliation.affiliation_role_id,
case_assignment.assignment_role_id, and user_account.system_role_id all
reference the single role entity rather than disconnected reference-data
vocabularies, each tagged with a role_context naming which relationship it
belongs to. This exists so a role-to-permission mapping has one stable key
(role_id) to attach to, instead of reimplementing access logic per
relationship type. system_role_id (role_context: user_account) is that key
for authenticated accounts; it configures a permission role but grants no
permission by itself until an actor-permission mapping resolves it — see
docs/DECISIONS.md. Adding a new relationship that needs configurable roles
should add a new role_context value, not a new parallel role entity.
Fields default to source-of-truth values. data_role: snapshot denotes a
deliberately frozen historical value. Reference fields select configured
values; UUID references identify explicit foreign keys. Every reference
implies many-to-one unless a rule restricts it. UUID identities must survive
exports and mappings; platform record IDs may need an explicit crosswalk. Do
not cascade-delete history.
The additional object type is a structured, schema-versioned value, used only
for immutable snapshots: the review submission_snapshot and the
invoice_import.extraction_result. Platforms may encode it as JSON or normalized
snapshot children; it is not permission to flatten operational relationships.
case.status_id/opened_on/closed_on/external_reference/client_id,
invoice.status_id/submitted_at, preauthorization.status_id, and
professional.display_name/office_id are, for now, plain stored fields set
directly by whatever writes the record (today, that's the review fixture
script). Each duplicates a value that a proper history table already makes
derivable: lifecycle events for case status/dates, case_identifier for the
external reference, case_participant for the current client,
invoice_event for invoice status/submission time, person/
person_affiliation for professional display name/office. They were briefly
modeled as data_role: derived projections, but nothing computes or refreshes
them at runtime yet, so that annotation claimed a guarantee the system
doesn't keep; they were reverted to plain fields rather than ship an unenforced
contract.
Before promoting any of these back to data_role: derived, there must be an
actual mechanism keeping them in sync with their source history — a rules/
workflow engine step, a database trigger, or (for the Dataverse implementation
specifically) a plugin, Power Automate flow, or calculated/rollup column — and
a rule that rejects direct writes once that mechanism exists. Until then, treat
values in these fields as informational, not authoritative; the tables below
list the correct authoritative source for each.
Calculate these read models instead of relying on the stored fields above:
| Read model | Source and interpretation |
|---|---|
| Current case status, first opened date, current closed date | Effective lifecycle events; closed date becomes null on reopening without deleting earlier closings |
| Case external reference | Value of the designated primary case_identifier, or null |
| Current client | The single current case_participant in the client role, when unambiguous; otherwise null |
| Current primary professional | Assignment in the primary role effective at the requested instant |
| Professional display name / office | Linked person.display_name; primary office from effective person_affiliation, when unambiguous |
| Invoice status, submitted time | Latest invoice_event; original submissions remain in history |
| Assignment/participation active | Start-inclusive, end-exclusive interval evaluated at an explicit as-of instant |
| Case age, threshold flags, date buckets | Lifecycle events and reporting as-of date/time zone; threshold and age convention are configured |
| Approved request amount | Final required line-review decisions in the non-superseded chain |
| Previously submitted amount | Frozen submissions as of a cutoff; distinguish all attempts from distinct requests to avoid double counting resubmissions |
| Previously approved amount | Effective approved allocation draws as of a cutoff, excluding the request being reviewed |
| Remaining authorization balance | Latest effective authorized ceiling minus effective approved draws, including paid draws |
| External payment completion | Completion confirmed when a payment confirmation exists; otherwise unconfirmed, independently of approval |
Case age may mean elapsed since first open, current open interval, or total open time excluding closed intervals. Reports must name their convention; none is silently selected. Pending reservations are separate from approved consumption and require policy before they affect an available balance.
Build a permission-filtered union of activity, case_note, communication,
time_entry, calendar_event, case_lifecycle_event, and optionally financial
history through each request's case. Return source entity/key, case ID, effective
time or service date, recorded time where present, actor/worker, type and summary.
Sort ties by source entity and stable key; lifecycle ordering uses its sequence.
Date-only time entries retain date precision, not an invented midnight instant.
Calendar records remain labelled scheduled or cancelled, distinct from completed
activities. Linked time and activity may be grouped in the UI but retain distinct
identities and amounts. Filter each source and attached evidence before counting,
sorting or summarizing; a case-level permission does not imply all note access.
A timeline is a read model, not a second history table.
The stable invoice key continues to mean a payment request. It now has one case
and payee and may contain multiple supporting_invoice references. It is not
necessary to add a competing payment_request entity. Requests with multiple
cases are outside this slice and require a deliberate future allocation design.
invoice_line retains the billable items and payment records external completion
evidence; it is not a payment instruction or disbursement engine.
preauthorization is an external-service ceiling, distinct from chain pre-approval.
submission_snapshot must contain spec_version, capture timestamp, request ID,
chain ID and exact reviewed values of the request, lines, trips, supporting invoice
references, allocations and payee contact/vendor details, and the billing rule
settings in force with their findings (apply_billing_rules). Capture relied-on case
identifiers, participant/assignment identities, jurisdiction, issue descriptions,
and attestation statement/signature document version IDs as deliberate evidence,
not extra mutable fields on each request. Include document version IDs and hashes.
Each snapshot section identifies source entity and stable record ID. Corrections
to source records cannot change the reviewed snapshot. Snapshot and attestations
are finalized atomically at submission; review cannot start without required
attestations. Storage format and electronic signature assurance remain mapping
and product decisions respectively.
Final approving line decisions may have invoice_allocation_decision children
that distribute the approved line amount across the request's authorizations.
Their sum supplies actual draws; requested allocations do not consume approved
capacity. Earlier review steps do not consume capacity. Approval and ceiling
updates require serialized checks across all competing requests, including API
and import writers. Unsupported transactional enforcement is an explicit platform
gap, not a relaxed domain rule.
An invoice line optionally derives from one source record through a typed
foreign key: invoice_line.source_time_entry_id or
invoice_line.source_expense_id. At most one is set and its target must be on
the same case; a manual line sets neither. These are real references with the
same integrity as every other relationship, not an untyped polymorphic pointer
— this replaces the earlier source_record_type/source_record_id pair.
Additional source types are added as further optional typed references after a
model decision, following the same one-of pattern as document_link.
Mileage is an expense type rather than a separate line type. A mileage line's
quantity is the miles claimed for the whole trip; it is priced at the
mileage_rate in force on its date (apply_mileage_rates).
A trip groups the separate lines one journey is claimed as: at most one
travel time line (a time line on a trip), at most one mileage line and any
number of other travel costs as expense lines. The trip holds what they share:
its date, trip_origin, trip_destination and round_trip. Each line is
still priced, reviewed and decided on its own; the trip is not a competing
aggregate. Time is work, travel (a time line on a trip) or waiting
(invoice_line.time_category). Travel and waiting time are priced from their
category's time_category_rate in force, whose basis is the hourly rate, a
percent of it or a flat rate (apply_time_category_rates). A reviewer may
approve a line at a changed rate, higher or lower, which sign-off sees flagged
(decide_invoice_lines). The optional mileage distance billing rule
records the driving distance found for each trip on the trip
(route_distance, route_checked_at), so the submission snapshot keeps what
the claim was compared with. Which routing service supplies distances is an
implementation choice. The time entries and expenses created from a trip's
lines reference it by trip_id.
A payee may upload a supporting invoice file instead of entering lines. The file
becomes a document working copy; an invoice_import records its format, the
extraction method and version, and an immutable extraction_result. Extraction
proposes one draft request; the submitter corrects it against the original file
(changing, removing or adding lines, without a reason) and confirms the
extracted values. Each line keeps its source_location in the file, so
reviewers see the file beside the lines, what the submitter changed and the
lines they removed. The file is kept while its request is live and its
content deleted, setting document.content_deleted_at and keeping only
metadata, hash and the extraction result, when its import is discarded or
expires or its request is withdrawn, deleted or recorded as paid. A file
that could not be read expires three days after upload; a draft read from a
file stays until its submitter sends, discards or deletes it. Document
storage is a working area, not a
record store: it accepts only configured
formats within configured limits, scans files before parsing, and keeps them out
of versioning and backups. From then on the draft request, and later its submission snapshot, is
the record of the supporting invoice. The file stays beside it for the
submitter and authorized reviewers until the request is withdrawn or deleted.
The draft stays editable until submitted through the ordinary
payment_request workflow, and a submission may be recalled to draft only
before any review decision. Starting over withdraws the draft and needs a new upload.
Extracted values never become submitted, approved or source records by
themselves.
extraction_result must contain spec_version, the import ID, and for the
request and each line the extracted value, its location in the source where
known (for a PDF, also the region of the page it was read from, so reviewers
can see it highlighted), an optional confidence, and any warnings. Items read
from attachments after the invoice (receipts, maps, another invoice, or files
embedded in the PDF) that match none of its lines are kept apart as suggested lines with their locations; they are offered
to the submitter and never become draft lines by themselves. For a file designated to one
professional, it also names that professional, whose work every line is. Structured formats such as
standard legal billing exchange files, delimited text and spreadsheets are
parsed directly; free-form documents need an extraction method. Neither the
model nor this contract selects a parser, extraction service or rendering
library. Production extraction stays within the system's processing boundary, which
includes services in the organization's own cloud account.
Imported lines keep supplier-stated detail on invoice_line: service date,
description, quantity, rate, timekeeper label and optional task, activity and
expense codes. These are evidence, not inputs to the amount. Codes stay free
text until a configured code set is adopted. Before confirming, the submitter
matches each timekeeper to an existing professional assigned to the case
(invoice_line.timekeeper_professional_id), or names someone who isn't listed
(proposed_timekeeper_name); a timekeeper the file names but nobody chose is
kept the same way. No people are created from labels or names: staff match or
add them before review (match_invoice_to_case). On submission, lines with a date and
hours create time entries for their matched professional, and lines the
submitter classifies as expenses create expense records, linked through
source_time_entry_id or source_expense_id, unless the submitter links an
existing record instead.
A configured delegate, such as office support staff, may upload, edit, recall
and submit requests for professionals in the same office. Delegate authority
comes only from a configured delegate role on an effective person_affiliation,
never from office membership alone, and never replaces the professionals' own
case assignments. The delegate is recorded as submitter and actor. Every line
of a delegated request names its professional; those represented professionals
need not attest or approve, and may view and export the request.
Exports render one identified submission attempt with its status and line decisions as a document or spreadsheet. Billing staff may export any submitted request; submitters and represented professionals only their own. Exports are not audited.
This system owns request submission, review and approval. Actual payment happens
elsewhere. Retain the stable payment entity key for external payment confirmation
only. An authorized user can record confirmation manually; a future integration
may import confirmation evidence but must not initiate payment.
Show approval and completion separately: for example, Approved / Completion unconfirmed, then Approved / Completion confirmed. No confirmation does not prove that payment has not occurred. Confirmation records who reported it, when, the source, the approved attempt, and optionally the reported payment date, external reference and amount. A confirmation attests completion of the request, not an installment. Unknown amount stays unknown; a reported discrepancy is flagged for reconciliation without changing the approval or hiding evidence. Do not derive an outstanding payment balance from missing amounts.
Payment execution, banking details and refund execution are outside scope. Partial-settlement evidence, correction of mistaken confirmation and reports of external reversals remain future reconciliation decisions, not planned payment processing features. Existing confirmations are preserved until those correction rules are defined.
Closing a case ends every active assignment, including primary and other staff roles, at the closure effective timestamp. The ending actor is the closing actor and the end reason identifies case closure. Preserve the assignment records; active state remains a calculation over their intervals. Closing history, assignment endings and current-state projections must commit atomically.
Ended assignments no longer count as active workload or provide assignment-based access; separately authorized access may remain. Reopening does not restore old assignments. Create new assignment records through normal eligibility checks. Assignments cannot start in or span a closed interval. Corrections to closure history must revalidate these intervals and preserve the earlier ending evidence.