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)
Decision 01

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 · Storage-layer immutability
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.

Decision 02

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 · Deterministic replayability
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.

Decision 03

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 · Transactional audit wrapper
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.

Decision 04

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 · Type-system route taxonomy
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.

Decision 05

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 · Statute-bound action enums
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 datacivistara.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 overviewcivistara.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
security@civitascom.com