Dossier — Domain Model

The Schema is the spine — DataSources write to it (inbound), Bindings read from it (outbound). Cases own the data, Filings are snapshots submitted to court.

DataSource → [mapping] → Schema key → [Binding] → Form field
                              ↓
                         Entry on Case → Filing (snapshot)

Domain Concepts

Engine Layer (document assembly)

Runtime Layer (case management)

File Structure

domain_tools/                       — form processing scripts, prompts, and pipeline docs (in git)

domains/                            — NOT in git (IP)
├── bankruptcy/
│   ├── schemas/
│   │   ├── individual.json         — ~1,100 keys
│   │   └── nonindividual.json      — ~640 keys
│   ├── data-sources/
│   │   └── credit-report.json      — MISMO XML → schema key mapping
│   └── federal/
│       ├── forms/                  — 70 leaf forms (PDF + JSON per directory)
│       └── groups/                 — 16 composite forms (chapter packages, schedules, etc.)

Groups are composite forms stored separately from leaf forms because they have no PDF. A group like chapter-7-ind.json references leaf forms and other groups as children. In the database and type system, a group is just a Form with children and no filePath. There are 19 composite forms (chapter packages, petition variants, schedule groups, means-test packages, etc.).

---

Schema

The single source of truth for what data points exist in a domain. Every key has a type, label, hint, and group. Forms bind to schema keys. DataSources map to schema keys.

interface Schema {
  id: string
  name: string              // "bankruptcy.individual"
  description: string | null
  entries: SchemaEntry[]
}

interface SchemaEntry {
  key: string               // "debtor1.first_name", "creditors.secured[].name"
  type: 'text' | 'money' | 'date' | 'boolean' | 'enum' | 'number'
  label: string
  hint?: string
  group?: string            // UI grouping: "Debtor 1 — Identity"
  options?: string[]        // for enum type
}

One schema per domain variant. Bankruptcy has two:

The overlap is only administrative keys. All substantive data (debtors, income, property, creditors, entity, officers) is completely separate.

---

Form

A form can be a leaf (has PDF with fields), a composite (has children), or both. Recursive — composites contain composites.

interface Form {
  id: string
  tenantId: string | null
  schemaId: string | null       // which vocabulary
  number: string | null         // "101" for leaf forms
  name: string
  description: string | null
  version: number
  status: string
  filePath: string | null       // PDF path (leaf only)
  effectiveDate: string | null
  pages: number                 // 0 for composites
  fields: FormField[]           // empty for composites
  children: ChildEntry[]        // empty for leaves
  bindings: Binding[]
  validations: Validation[]
}

Leaf form example

Has a PDF, fields extracted from it, bindings mapping schema keys to PDF field names.

{
  "id": "F0001010-BA01-4000-8000-000000000000",
  "name": "Form 101 — Voluntary Petition",
  "schemaId": "S0000001-BA01-4000-8000-000000000001",
  "filePath": "b101/b101_2024-06-22.pdf",
  "pages": 9,
  "fields": [{ "key": "Debtor1.First name", "type": "text", "page": 1 }],
  "children": [],
  "bindings": [
    { "source": "debtor1.first_name", "targets": ["Debtor1.First name"] }
  ]
}

Composite form example (group)

Has children, no PDF. Bindings route schema keys to children.

{
  "id": "BB000106-BA01-4000-8000-5C4ED0000001",
  "name": "The Schedules (Individual)",
  "schemaId": "S0000001-BA01-4000-8000-000000000001",
  "filePath": null,
  "pages": 0,
  "fields": [],
  "children": [
    { "id": "F0010600-...", "key": "b106sum", "position": 1 },
    { "id": "F0001190-...", "key": "b119", "position": 3, "condition": "case.has_petition_preparer == true" }
  ],
  "bindings": [
    { "source": "debtor1.first_name", "targets": ["$b106sum.Debtor 1", "$b106ab.Debtor 1"] }
  ]
}

Leaf vs composite bindings

---

Field

A fillable spot on a PDF.

interface FormField {
  key: string                 // AcroForm field name
  type: 'text' | 'checkbox' | 'dropdown' | 'radio' | 'signature' | 'optionList'
  page: number
  rect: { x: number, y: number, w: number, h: number } | null
  options: string[] | null
  label: string | null
  hint: string | null
  needsReview: boolean        // true if field name is generic/auto-generated
  source: 'acro' | 'llm' | 'manual'
}

---

Binding

Maps a source expression to one or more target addresses.

interface Binding {
  source: string        // schema key or expression
  targets: string[]     // field names or $child addresses
  condition?: string    // boolean expression
  note?: string         // developer documentation
}

Array syntax

[] in a source/target means "each item in this array":

{
  "source": "creditors.secured[].name",
  "targets": ["Creditors Name"],
  "repeating": { "pattern": "Creditors Name_{n}", "startIndex": 2, "maxRows": 8 }
}

The repeating property (leaf forms only) tells the PDF filler how to map array items to numbered AcroForm field names.

Cross-form array sync

At the parent level, array bindings sync data between sibling forms:

{ "source": "$schedules.creditors.secured[].name", "targets": ["$plan.plan_secured_treatments.maintain_cure[].creditor"] }

One binding per target array. The user decides which creditors go in which treatment section — the binding keeps shared fields (names, amounts) in sync.

---

Validation

interface Validation {
  expression: string          // "case.district != ''"
  severity: 'error' | 'warning'
  description: string         // "District is required"
}

---

DataSource

Reusable recipe for getting external data into the schema. Platform-defined or tenant-created. Stored as JSON config files in domains/<domain>/data-sources/.

interface DataSource {
  id: string
  tenantId: string | null     // null = platform-provided
  name: string                // "Experian Credit Report"
  type: string                // "credit-report", "case-mgmt", "csv", "document"
  schemaId: string            // scoped to a schema
  config: unknown             // parse rules, field mappings, API config
}

DataSource mappings are inbound (external field → schema key). Bindings are outbound (schema key → form field). Both use the same key vocabulary — one key picker, one autocomplete, same [] array syntax.

Data flow

External data (XML, API, CSV, PDF)
    ↓
DataSource (parse + map rules)
    ↓
Schema keys (the shared vocabulary)
    ↓
Entry on Case (batch of key=value with source + timestamp + confirmed)
    ↓
Binding engine (resolves confirmed entries → form fields)
    ↓
Filled PDF

---

Case

A client matter. Owns all data and sub-resources.

interface Case {
  id: string
  tenantId: string
  schemaId: string            // which vocabulary drives this case
  formId: string              // the initial form package
  name: string                // "Garcia, Maria"
  status: string              // Intake, Prep, In Review, Ready, Filed, Active, Discharged, Closed
  references: Record<string, string>  // {"Case #": "26-12345", "Docket #": "...", "District": "NDIL"}
  dates: Record<string, string>       // {"Filed On": "2026-03-25", "341 Meeting": "2026-04-14"}
}

---

Filing

An envelope submitted (or to be submitted) to court. When status transitions to filed, filed_at and snapshot_at are stamped to NOW(); the merged values as of snapshot_at form the filing's frozen snapshot (replayed on read — there is no stored JSONB snapshot blob).

interface Filing {
  id: string
  caseId: string              // belongs to a case
  name: string                // "Ch.7 Petition Package"
  status: 'draft' | 'filed' | 'accepted' | 'rejected'
  courtReference: string | null   // ECF #
  filedAt: string | null
  snapshotAt: string | null   // timestamp cutoff for replay
  forms: FilingForm[]         // child form_versions, captured at envelope creation
  attachments: FilingAttachmentSummary[]
}

filings (envelope) ↔ filing_forms (which forms are in the envelope) ↔ filing_attachments (which uploaded attachments accompany it). Amendments and conversions create new filings. The original filing's snapshot is immutable — replay against snapshot_at always returns the same values.

---

Entry

A batch of data point changes on a case. One event (save, import, sync) = one entry with N values.

interface Entry {
  id: string
  caseId: string              // belongs to a case (not a filing)
  source: string              // "manual", "credit-report", "csv"
  dataSourceId: string | null
  timestamp: string
  confirmed: boolean          // false = pending review
  values: Record<string, unknown>
}

How entries work

• Lawyer types 5 fields, clicks save → 1 entry with 5 values, source = "manual", auto-confirmed
• Credit report is pulled → 1 entry with 80 values, source = "credit-report", pending confirmation
• Lawyer corrects a creditor name → 1 entry with 1 value, overrides the credit report entry for that key

Current state = merge all entries by timestamp (latest wins per key). Only confirmed entries are used for PDF generation.

Case history = auto-logged events (data changes, imports, status changes, filings). Separate from entries — entries are data, history is audit.

---

Child Entry

interface ChildEntry {
  id: string              // UUID of the child form
  key: string             // alias used in expressions: "b106ab", "petition"
  position: number        // ordering
  condition?: string      // boolean expression controlling inclusion
}

No type field — a child is always a form (which may itself be leaf or composite).

---

Expression Syntax

All source, condition, and target values are parsed by the expression engine.

Reference resolution

Disambiguation

• Starts with $ → form field reference
• Has a . but no $ → schema key
• No . and no $ → literal value or function name

Operators

+, -, *, /, ==, !=, >, <, >=, <=, &&, ||, !

Functions (22)

---

Scoping Rules

Ancestry rule: bindings can reference any descendant. Never up, never sideways — only down. Cross-form bindings live on the common ancestor.

---

IDs

JSON files on disk have no id field. The seed script assigns randomUUID() at load time. Groups reference children by key (the form's directory name or group filename), not by UUID. The seed builds a key → id lookup and wires up the references when inserting into the database.

Filenames: -ind / -nin always last suffix (e.g., petition-ch7-ind.json).

---

Database Tables

Engine

Runtime

Case Management

Platform