Platform · Architectural deep-dive
Five design principles, built into the schema.
This page is for the technical reviewer. Its readers are state Chief Technology Officers, Managed Care Organization (MCO) security leads, and the architecture teams a procurement officer forwards a screenshot to. The five principles below are built into the database schema and the route layer rather than left to policy. Civistara calculates status from the evidence and routes it to state staff; the state agency decides.
What follows is a principle-by-principle walk-through with the mechanism category, the enforcement surface, and the public statutory or precedent basis for each. Source citations are available under NDA. Everything else is published on this site.
- Audit model
- Append-only · corrections are new entries
- Rules
- Versioned · deterministic calculation
- Decision authority
- The state agency · Civistara routes, staff decide
- Statute
- H.R. 1 §71119 · 42 U.S.C. §1396a(xx)
Records are added, never rewritten.
The plain-language form of the first principle. The technical name is append-only ledger. Audit and ledger records are written as new rows and are not updated in place; a correction is a new entry that points back to what it corrects.
The mechanism is a row-level trigger that raises an exception on UPDATE or DELETE attempts against the protected tables. The database refuses the operation regardless of which application client asks. Integrity is enforced at the storage layer, not the policy layer, so the history is still there when someone reviews it years later.
- Mechanism
- Row-level triggers raise exception on UPDATE / DELETE attempts against ledger tables · enforcement at storage, not policy
- Surface
- Applied to audit and ledger tables · refuses the operation regardless of application caller
- Purpose
- History preserved for later review · corrections recorded as new entries
- Standard
- ACID isolation · append-only ledger pattern
Read the full architectural record at/decisions/append-only-decision-ledger.
Rules are versioned.
The plain-language form of the second principle. The technical name is deterministic replayability. Status calculations are deterministic and tied to a versioned rule set, so the same inputs under the same rule version give the same result.
The design goal is that a reviewer working years later can see which rule version applied and reconstruct how a status was reached. There is no clock-bound randomness and no model output in the calculation path. The status is a calculation that state staff act on; the state agency makes the decision.
- Mechanism
- Versioned rule set · deterministic calculation · inputs and rule version captured for replay
- Scope
- Status calculations that state staff review · not the state agency’s eligibility decision
- Goal
- A reviewer can reconstruct how a status was reached under the rules in force at the time
- Discipline
- No clock-bound randomness · no model output · no current-best-estimate logic in determination paths
Read the full architectural record at/decisions/deterministic-replayability.
The platform is designed to fail safe.
The plain-language form of the third principle. The technical name is fail-closed audit. Access is designed to be denied when authentication or tenant context is missing, and state-changing operations are designed to roll back when their audit write fails.
The pattern is a transactional wrapper around state-changing operations: the audit log write and the business change share a single database transaction. If the audit write fails, the transaction rolls back, so the change is not made silently.
- Mechanism
- The business change and the audit-log write share a single database transaction
- Surface
- State-changing route handlers · audit write and change succeed or fail together
- Failure mode
- Audit-write failure rolls back the business mutation · fail-closed at the route layer
- Standard
- ACID atomicity
Read the full architectural record at/decisions/fail-closed-audit-transaction.
Viewing and changing are separate.
The plain-language form of the fourth principle. The technical name is view / mutation separation. Read endpoints are built not to change a member’s record as a side effect of someone viewing it.
The codebase uses a typed split at the route layer: read endpoints call read-tagged functions and write endpoints call mutation-tagged functions, with lint rules and strict typing to catch code that crosses the boundary.
- Mechanism
- Read endpoints can only call functions tagged readonly · write endpoints can only call functions tagged mutation · no shared layer that does both
- Surface
- Read handlers tagged readonly across the member-facing API
- Enforcement
- Compile-time refusal to build code that crosses the boundary · lint-rule + strict type discipline
- Result
- Viewing a record is designed not to change it · a build-time check, not only a policy
Read the full architectural record at/decisions/view-mutation-type-separation.
Only defined actions exist.
The plain-language form of the fifth principle. The technical name is closed-set actions. Audit actions and compliance statuses come from fixed lists, so the record never holds a state the rules do not define.
The mechanism is an explicit enum of admissible audit actions and statuses, modeled as database-layer constraints and type-system discriminated unions. Adding a value takes a code change and a rule-version bump, not a configuration tweak.
- Mechanism
- Audit actions and statuses modeled as database-layer constraints and type-system discriminated unions
- Surface
- Audit actions: create, update, state change, version, delete, link, unlink · statuses: eligible, ineligible, pending, waived
- Enforcement
- DB-level CHECK · type-level discriminated union · enum membership rejected at request boundary
- Authority
- H.R. 1 § 71119 · 42 U.S.C. § 1396a(xx)(7)
Read the full architectural record at/decisions/closed-set-actions.
Audit it yourself
Verifiable by the public.
- i.Sitemap and structured data
civistara.com/sitemap-index.xml· Schema.org Organization JSON-LD on every page · AboutPage schema on /about · TechArticle schema on /platform - ii.Security disclosure (RFC 9116)
civistara.com/.well-known/security.txt· machine-readable contact, expiration, canonical URL - iii.LLM-readable site overview
civistara.com/llms.txt· per llmstxt.org spec · structured access for evaluation agents - iv.Beneficiary safeguards registercivistara.com/safeguards· five member protections, with the status of each