Settle — System Architecture

Architecture Principles

These principles are not aspirational — they are constraints. Every design decision in this document can be traced back to at least one of them. When a tradeoff arises, principles at the top of this list take precedence.

System Overview

Settle is architecturally a modular monolith deployed on Fly.io, backed by Neon Postgres and Cloudflare R2. It is not a microservices system — at Year 1 scale (500 estates), the operational overhead of distributed services outweighs the benefits. Service boundaries are enforced at the module level within the codebase, making extraction straightforward when scale demands it.

Deployment Topology

All server-side compute runs on Fly.io. The SvelteKit application serves both the frontend (SSR) and the API routes. A separate Fly.io machine type runs background workers (notification service, benefit scanner) on a schedule or queue trigger. Neon Postgres provides the primary data store with automatic branching for staging environments. Cloudflare R2 stores documents, accessed via pre-signed URLs generated by the API — the browser never talks directly to R2 in upload mode.

Frontend Architecture

The frontend is SvelteKit deployed to Cloudflare's global CDN edge network. This gives static assets and pre-rendered pages sub-50ms TTFB globally without any CDN configuration overhead. The SvelteKit application uses a hybrid rendering strategy: marketing pages and unauthenticated flows are fully SSR'd for SEO; the authenticated estate application is server-rendered for initial load then transitions to client-side navigation.

SSR Strategy

Grief-Aware UX Architecture

The people using Settle are in one of the most cognitively impaired states a person can experience. The architecture must account for this — not just the visual design, but the caching, session, and error recovery behavior of the application.

Client-Side State Preservation

SvelteKit's +page.server.ts load functions cache estate data with a 60-second stale-while-revalidate window. Form state is auto-saved to localStorage every 5 seconds during intake flows, keyed by estate ID and form name. If the browser tab is closed mid-form, the user resumes exactly where they left off on next visit.

// src/lib/stores/formPersist.ts
export function createPersistedForm(estateId: string, formKey: string) {
  const storageKey = `settle:form:${estateId}:${formKey}`;

  return {
    restore: () => {
      const raw = localStorage.getItem(storageKey);
      return raw ? JSON.parse(raw) : null;
    },
    save: (data: unknown) => {
      localStorage.setItem(storageKey, JSON.stringify({
        data,
        savedAt: Date.now()
      }));
    },
    clear: () => localStorage.removeItem(storageKey)
  };
}

Session Continuity for Long-Lived Workflows

Estate workflows span 16–18 months. Standard session expiry of 24–72 hours is inappropriate. Sessions are configured with a 30-day sliding window. The session cookie carries only the session ID; all session data (user ID, estate ID, role, last active page) lives in Redis. On each authenticated request, the session TTL is refreshed. The "last active page" is stored and presented as a resume prompt on next login.

Offline Support

Families in rural areas, or using cellular connections at a funeral home, may have intermittent connectivity. The application uses a Service Worker registered at the app root to cache the application shell and the current estate's task plan for offline viewing. Mutations made offline are queued and replayed when connectivity is restored.

Backend API

The API is implemented as SvelteKit server routes (+server.ts files), co-located with the frontend. This is not a tradeoff in Year 1 — it means a single deployment, shared TypeScript types between server and client, and zero serialization overhead. The API layer follows REST conventions with resource-oriented URLs and standard HTTP semantics.

Authentication and RBAC

Authentication is session-based with cookies. Sessions are stored in Upstash Redis with a 30-day sliding expiry. The session token is a cryptographically random 256-bit value (generated with crypto.getRandomValues). The session payload includes the user ID, estate ID (if applicable), role, and a fingerprint of the request IP and user agent for anomaly detection.

Role Definitions

RBAC is enforced at two layers: the route handler level (SvelteKit hooks check the session role before the handler executes) and the database level (Postgres row-level security policies that reference the current session's estate ID). This means a misconfigured route cannot accidentally return data from another estate — the database policy will reject the query.

Key API Endpoints

Estate Management

Sample: Create Estate

// POST /api/estates
// Request Body:
{
  "deceased": {
    "firstName": "Margaret",
    "lastName": "Chen",
    "dateOfBirth": "1942-03-15",
    "dateOfDeath": "2026-03-01",
    "stateOfResidence": "CA",
    "ssn": "XXX-XX-XXXX"  // encrypted in transit and at rest
  },
  "executor": {
    "relationship": "child"
  },
  "estateProfile": {
    "hasRealProperty": true,
    "estimatedAssetValue": "250000-500000",
    "hasWill": true,
    "hasTrust": false
  }
}

// 201 Created Response:
{
  "estateId": "est_01j9k3m...",
  "status": "intake_complete",
  "taskPlan": {
    "generatedAt": "2026-04-03T14:22:00Z",
    "ruleSetVersion": "CA-2026.1",
    "taskCount": 34,
    "requiredDeadlines": [
      { "task": "file_probate_petition", "dueByDays": 30 }
    ]
  }
}

// 422 Error (invalid state):
{
  "error": "INVALID_STATE_CODE",
  "message": "stateOfResidence must be a valid 2-letter US state code",
  "field": "deceased.stateOfResidence"
}

State Rules Engine

The rules engine is the most architecturally unique component in Settle. It must encode legally-correct, state-specific probate rules for all 50 states, remain maintainable by non-engineers (or at least by lawyers working with engineers), support versioning and rollback, and produce an auditable trail of exactly which rule set generated which task plan for a given estate.

Rule Set Schema

Each state has a versioned JSON rule set stored in Postgres. The JSON document defines the full task graph for that state, with conditions that filter and customize tasks based on estate attributes. The schema is designed to be readable by a paralegal reviewing the document — not just a developer.

// Table: state_rule_sets
// Column: rules JSONB

{
  "state": "CA",
  "version": "CA-2026.1",
  "effectiveDate": "2026-01-01",
  "legalSources": [
    "Cal. Prob. Code § 13100",
    "Cal. Prob. Code § 8000"
  ],
  "probateThreshold": {
    "grossEstateValueCents": 18450000,
    "realPropertyIncluded": true,
    "source": "Cal. Prob. Code § 13100 (adjusted annually)"
  },
  "smallEstateAffidavit": {
    "available": true,
    "maxValueCents": 18450000,
    "waitDays": 40,
    "form": "DE-305"
  },
  "tasks": [
    {
      "id": "obtain_death_certificates",
      "category": "immediate",
      "priority": 1,
      "title": "Order certified death certificates",
      "description": "Order at least 10 certified copies from VitalChek...",
      "conditions": [],
      "deadlineDays": 7,
      "requiredFor": ["open_estate_account", "notify_ssa"],
      "legalGuidance": "Procedural step. Order via VitalChek or local registrar."
    },
    {
      "id": "file_probate_petition",
      "category": "probate",
      "priority": 2,
      "title": "File petition for probate",
      "conditions": [
        {
          "field": "estate.requiresProbate",
          "operator": "eq",
          "value": true
        }
      ],
      "deadlineDays": 30,
      "court": "Superior Court, Probate Division",
      "forms": ["DE-111", "DE-140"],
      "filingFee": {
        "baseFeeCents": 39500,
        "source": "Cal. Gov. Code § 70650"
      }
    }
  ]
}

Rule Evaluation

The rules engine evaluates a rule set against an EstateContext object — a snapshot of all estate attributes relevant to task generation. Evaluation is a pure function with no side effects: given the same EstateContext and RuleSet, it always produces the same task list. This property makes it trivially testable.

// src/lib/rules/evaluator.ts

export interface EstateContext {
  estateId: string;
  stateCode: string;
  dateOfDeath: Date;
  estimatedGrossValueCents: number;
  hasRealProperty: boolean;
  hasWill: boolean;
  hasTrust: boolean;
  hasMinorChildren: boolean;
  hasVeteranStatus: boolean;
  hasBusinessInterests: boolean;
  requiresProbate: boolean; // derived: grossValue > threshold
}

export function evaluateRuleSet(
  context: EstateContext,
  ruleSet: StateRuleSet
): GeneratedTask[] {
  const tasks: GeneratedTask[] = [];

  for (const rule of ruleSet.tasks) {
    const conditionsMet = rule.conditions.every(
      (c) => evaluateCondition(c, context)
    );

    if (conditionsMet) {
      tasks.push({
        ruleId: rule.id,
        ruleSetVersion: ruleSet.version,
        title: rule.title,
        description: rule.description,
        category: rule.category,
        priority: rule.priority,
        dueDateCalc: rule.deadlineDays
          ? addDays(context.dateOfDeath, rule.deadlineDays)
          : null,
        legalGuidance: rule.legalGuidance,
        forms: rule.forms ?? [],
        status: 'pending'
      });
    }
  }

  return tasks.sort((a, b) => a.priority - b.priority);
}

function evaluateCondition(
  condition: RuleCondition,
  context: EstateContext
): boolean {
  const value = getNestedValue(context, condition.field);
  switch (condition.operator) {
    case 'eq': return value === condition.value;
    case 'gt': return value > condition.value;
    case 'lt': return value < condition.value;
    case 'in': return condition.value.includes(value);
    default: throw new Error(`Unknown operator: ${condition.operator}`);
  }
}

Versioning and the Audit Trail

Rule sets are immutable once published. When a legal change requires updating California's rules, a new version CA-2026.2 is created — the old version is never modified. Every generated task carries the ruleSetVersion that produced it. This creates a complete audit trail: any task in any estate can be traced to the exact rule text that created it, at the time it was created.

When new assets are discovered mid-process (e.g., a retirement account found three months in), the executor can trigger task plan regeneration. The engine runs against the current published rule set for the estate's state, adds any new tasks that aren't already present, and emits an estate_event recording the delta. Existing tasks are never deleted during regeneration — they may be superseded but the record of their creation is preserved.

Rule Update Process

Data Architecture

Postgres via Neon is the primary data store for all structured data. R2 stores documents. There is no separate analytics database at Year 1 — Neon's read replica capability provides read scaling without operational overhead. The schema is designed for the long-lived, event-sourced nature of estate workflows.

Core Schema

CREATE TABLE estates (
  id              TEXT PRIMARY KEY DEFAULT gen_estate_id(), -- 'est_' prefix + ulid
  status          TEXT NOT NULL DEFAULT 'intake',           -- intake|active|closing|closed|archived
  state_code      CHAR(2) NOT NULL,
  opened_at       TIMESTAMPTZ NOT NULL DEFAULT now(),
  closed_at       TIMESTAMPTZ,
  rule_set_version TEXT,                                     -- FK: state_rule_sets.version
  estimated_value_cents  BIGINT,
  requires_probate       BOOLEAN GENERATED ALWAYS AS (
    estimated_value_cents > (
      SELECT probate_threshold_cents
      FROM state_rule_sets
      WHERE state_code = estates.state_code
        AND status = 'published'
      LIMIT 1
    )
  ) STORED,
  metadata        JSONB NOT NULL DEFAULT '{}'               -- flexible attributes
);

CREATE INDEX idx_estates_state ON estates(state_code);
CREATE INDEX idx_estates_status ON estates(status)
  WHERE status NOT IN ('closed','archived');

CREATE TABLE deceased (
  id              TEXT PRIMARY KEY DEFAULT gen_id(),
  estate_id       TEXT NOT NULL REFERENCES estates(id),
  first_name      TEXT NOT NULL,
  last_name       TEXT NOT NULL,
  date_of_birth   DATE,
  date_of_death   DATE NOT NULL,
  state_of_residence CHAR(2) NOT NULL,
  -- Column-level encrypted fields (AES-256-GCM, application-layer)
  ssn_encrypted   BYTEA,                                    -- encrypted SSN
  ssn_last4       CHAR(4),                                  -- unencrypted for display/lookup
  -- Access to ssn_encrypted is audit-logged at application layer
  created_at      TIMESTAMPTZ NOT NULL DEFAULT now()
);

CREATE UNIQUE INDEX idx_deceased_estate ON deceased(estate_id);

CREATE TABLE tasks (
  id              TEXT PRIMARY KEY DEFAULT gen_id(),
  estate_id       TEXT NOT NULL REFERENCES estates(id),
  rule_id         TEXT NOT NULL,                            -- e.g. 'file_probate_petition'
  rule_set_version TEXT NOT NULL,                           -- immutable at creation
  title           TEXT NOT NULL,
  category        TEXT NOT NULL,                            -- immediate|probate|financial|notifications|etc
  status          TEXT NOT NULL DEFAULT 'pending',          -- pending|in_progress|complete|skipped|n_a
  priority        INTEGER NOT NULL DEFAULT 50,
  due_date        DATE,
  completed_at    TIMESTAMPTZ,
  completed_by    TEXT REFERENCES users(id),
  notes           TEXT,
  is_generated    BOOLEAN NOT NULL DEFAULT TRUE,             -- false = manually added
  superseded_at   TIMESTAMPTZ,                              -- set if task replaced on regeneration
  created_at      TIMESTAMPTZ NOT NULL DEFAULT now()
);

CREATE INDEX idx_tasks_estate ON tasks(estate_id) WHERE superseded_at IS NULL;
CREATE INDEX idx_tasks_status  ON tasks(estate_id, status)
  WHERE status IN ('pending','in_progress');

CREATE TABLE state_rule_sets (
  version               TEXT PRIMARY KEY,                   -- 'CA-2026.1'
  state_code            CHAR(2) NOT NULL,
  status                TEXT NOT NULL DEFAULT 'draft',      -- draft|review|published|superseded
  effective_date        DATE NOT NULL,
  superseded_by         TEXT REFERENCES state_rule_sets(version),
  probate_threshold_cents BIGINT NOT NULL,
  rules                 JSONB NOT NULL,                     -- full rule set document
  reviewed_by           TEXT,                              -- attorney name on record
  reviewed_at           TIMESTAMPTZ,
  published_by          TEXT REFERENCES users(id),
  published_at          TIMESTAMPTZ,
  created_at            TIMESTAMPTZ NOT NULL DEFAULT now()
);

CREATE INDEX idx_rules_state_published ON state_rule_sets(state_code)
  WHERE status = 'published';

CREATE TABLE notifications (
  id              TEXT PRIMARY KEY DEFAULT gen_id(),
  estate_id       TEXT NOT NULL REFERENCES estates(id),
  institution_id  TEXT REFERENCES institutions(id),
  tier            SMALLINT NOT NULL CHECK (tier IN (1, 2, 3)),
  channel         TEXT NOT NULL,                            -- api|mail|phone_script
  status          TEXT NOT NULL DEFAULT 'queued',           -- queued|processing|sent|delivered|failed
  idempotency_key TEXT UNIQUE NOT NULL,                    -- prevents duplicate sends
  external_id     TEXT,                                     -- Lob letter ID, API confirmation, etc.
  queued_at       TIMESTAMPTZ NOT NULL DEFAULT now(),
  sent_at         TIMESTAMPTZ,
  delivered_at    TIMESTAMPTZ,
  failed_at       TIMESTAMPTZ,
  failure_reason  TEXT,
  retry_count     SMALLINT NOT NULL DEFAULT 0,
  payload         JSONB NOT NULL                            -- full request payload, redacted of PII
);

CREATE INDEX idx_notif_estate   ON notifications(estate_id);
CREATE INDEX idx_notif_status   ON notifications(status) WHERE status IN ('queued','processing');
CREATE UNIQUE INDEX idx_notif_idempotency ON notifications(idempotency_key);

CREATE TABLE audit_log (
  id              BIGSERIAL PRIMARY KEY,
  estate_id       TEXT,                                     -- nullable for admin/system events
  actor_id        TEXT NOT NULL,                            -- user ID or 'system'
  actor_role      TEXT NOT NULL,
  action          TEXT NOT NULL,                            -- 'read_ssn', 'task_complete', etc.
  resource_type   TEXT NOT NULL,
  resource_id     TEXT,
  ip_address      INET,
  user_agent      TEXT,
  metadata        JSONB NOT NULL DEFAULT '{}',
  created_at      TIMESTAMPTZ NOT NULL DEFAULT now()
);

-- Append-only enforced via Postgres policy:
ALTER TABLE audit_log ENABLE ROW LEVEL SECURITY;
CREATE POLICY audit_insert_only ON audit_log
  FOR INSERT WITH CHECK (TRUE);
CREATE POLICY audit_no_update ON audit_log
  FOR UPDATE USING (FALSE);
CREATE POLICY audit_no_delete ON audit_log
  FOR DELETE USING (FALSE);

CREATE INDEX idx_audit_estate   ON audit_log(estate_id) WHERE estate_id IS NOT NULL;
CREATE INDEX idx_audit_action   ON audit_log(action, created_at DESC);
CREATE INDEX idx_audit_actor    ON audit_log(actor_id, created_at DESC);

Field-Level Encryption

The most sensitive fields — SSN, financial account numbers, medical record numbers — are encrypted at the application layer before being written to Postgres. Disk encryption (provided by Neon) is a necessary baseline but insufficient alone: it does not protect against a compromised database credential or a SQL injection vulnerability that returns raw rows. Field-level encryption ensures that even a full database dump is useless without the encryption keys.

Encryption Approach

• Algorithm: AES-256-GCM with a random 96-bit nonce per encryption operation
• Key Management: Per-estate derived keys using HKDF from a master key stored in Fly.io Secrets. The master key is rotatable without re-encrypting all records (re-encryption is a background job).
• Storage format: BYTEA column stores nonce (12 bytes) || ciphertext || auth_tag (16 bytes)
• Key derivation: HKDF(masterKey, salt=estateId, info="settle-v1-field-encryption")

// src/lib/crypto/fieldEncryption.ts

import { hkdf, getRandomValues } from 'node:crypto';

const MASTER_KEY = Buffer.from(process.env.FIELD_ENCRYPTION_KEY!, 'hex');
const ALGORITHM = 'aes-256-gcm';

export async function encryptField(
  plaintext: string,
  estateId: string
): Promise<Buffer> {
  const derivedKey = await deriveEstateKey(estateId);
  const nonce = getRandomValues(new Uint8Array(12));
  const cipher = createCipheriv(ALGORITHM, derivedKey, nonce);
  const encrypted = Buffer.concat([
    cipher.update(plaintext, 'utf8'),
    cipher.final()
  ]);
  const authTag = cipher.getAuthTag();
  // Pack: nonce (12) + ciphertext + authTag (16)
  return Buffer.concat([nonce, encrypted, authTag]);
}

export async function decryptField(
  cipherBuffer: Buffer,
  estateId: string
): Promise<string> {
  // Audit log this access BEFORE decryption
  await auditLog.write({ action: 'field_decryption', estateId });

  const derivedKey = await deriveEstateKey(estateId);
  const nonce = cipherBuffer.subarray(0, 12);
  const authTag = cipherBuffer.subarray(cipherBuffer.length - 16);
  const ciphertext = cipherBuffer.subarray(12, cipherBuffer.length - 16);

  const decipher = createDecipheriv(ALGORITHM, derivedKey, nonce);
  decipher.setAuthTag(authTag);
  return decipher.update(ciphertext) + decipher.final('utf8');
}

Fields That Require Encryption

Document Vault (Cloudflare R2)

Documents — death certificates, wills, financial statements — are stored in R2 with server-side encryption (SSE-C using a per-estate key). The API never streams document content directly; instead it issues short-lived (5-minute) presigned URLs for download and upload. Documents are organized in R2 by a path scheme that does not expose PII in the object key.

R2 path format: estates/{estateId}/{documentType}/{ulid}.{ext}

On upload, the Document Processor worker intercepts the R2 object:created event, performs virus scanning (ClamAV via a Fly.io sidecar), attempts OCR classification, and writes document metadata to Postgres. If virus scanning fails, the document is moved to a quarantine prefix and the estate is notified.

Notification Service Architecture

The notification service is the most operationally complex component in Settle. It must send actual cancellation requests to real institutions, generate and mail physical letters via Lob, and produce call scripts — each with fundamentally different reliability, latency, and tracking requirements. A failure in Tier 1 must not affect Tier 2; a physical letter sent twice is a worse failure mode than a digital request sent twice.

Worker Architecture

The notification worker is a long-running Fly.io process that polls the PgBoss job queue. It is isolated from the API server to prevent notification failures from impacting user-facing requests. The worker processes jobs by tier in priority order: Tier 2 (physical mail, longest lead time) processes first, then Tier 1, then Tier 3.

Tier 1 — API Cancellation

Tier 1 notifications call institution APIs directly to cancel subscriptions or notify of a death. The key engineering challenges are: (1) each institution has a different API contract, (2) idempotency must be enforced even if the request succeeds but the network drops before the response arrives, and (3) the system must distinguish between "institution confirmed cancellation" and "institution returned 200 but nothing happened."

// Institution adapter interface — each institution implements this
interface InstitutionAdapter {
  institutionId: string;
  sendNotification(
    payload: NotificationPayload,
    idempotencyKey: string
  ): Promise<NotificationResult>;
}

interface NotificationResult {
  success: boolean;
  externalId?: string;       // confirmation number from institution
  confirmedAction?: string;   // 'cancelled' | 'notified' | 'pending_review'
  errorCode?: string;
  retryable: boolean;          // false for 4xx, true for 5xx/network errors
}

// Idempotency key construction
const idempotencyKey = `tier1:${estateId}:${institutionId}:${notificationType}`;
// This key is stable across retries. Postgres UNIQUE constraint on
// notifications.idempotency_key ensures no duplicate processing.

Tier 2 — Physical Mail via Lob

Physical mail has the highest failure cost of the three tiers. A letter sent to a wrong address wastes money and time, but more importantly, it may delay asset recovery for a grieving family. The Tier 2 handler performs address validation via Lob's CASS-certified address API before creating the letter. Only after validation succeeds does it proceed to letter creation.

// Tier 2 handler flow
async function handleTier2(job: NotificationJob) {
  // 1. Check idempotency — was this letter already sent?
  const existing = await db.notifications.findByIdempotencyKey(job.idempotencyKey);
  if (existing?.external_id) {
    // Already sent to Lob — fetch status and return
    return { success: true, externalId: existing.external_id, alreadySent: true };
  }

  // 2. Validate address via Lob before creating letter
  const addressVerification = await lob.usVerifications.verify({
    primary_line: job.recipientAddress.line1,
    city: job.recipientAddress.city,
    state: job.recipientAddress.state,
    zip_code: job.recipientAddress.zip
  });
  if (addressVerification.deliverability === 'undeliverable') {
    throw new NotificationError('UNDELIVERABLE_ADDRESS', { retryable: false });
  }

  // 3. Fetch death certificate presigned URL from R2
  const deathCertUrl = await r2.getPresignedUrl(job.estateId, 'death_certificate');

  // 4. Create letter via Lob API
  const letter = await lob.letters.create({
    description: `Estate notification: ${job.estateId}`,
    to: addressVerification.components,
    from: SETTLE_RETURN_ADDRESS,
    file: job.templateId,
    merge_variables: {
      deceasedName: job.deceasedName,
      institutionName: job.institutionName,
      estateExecutor: job.executorName,
      deathCertificateEnclosure: true
    },
    // Lob idempotency header — prevents duplicate if network fails
    idempotencyKey: job.idempotencyKey
  });

  // 5. Store Lob letter ID for tracking
  await db.notifications.update(job.notificationId, {
    status: 'sent',
    external_id: letter.id,
    sent_at: new Date()
  });
}

Lob sends delivery status webhooks when a letter is in-transit, delivered, or returned. The webhook handler updates notifications.status and, on delivery failure (returned mail), creates a new task for the executor to verify the institution's address.

Tier 3 — Call Script Generation

Tier 3 is a pure computation: given an estate context and institution profile, generate a structured call script. No external API calls are made. The script object is returned synchronously to the client and also stored in notifications for record-keeping. The handler uses a template system with institution-specific overrides for hold queues, required account information, and department routing.

Reliability Model

Benefit Discovery Architecture

Benefit discovery is the process of finding assets and entitlements the family may not know about: unclaimed property held by states, life insurance policies, pension benefits, VA entitlements. Some sources have APIs; some require web scraping; some require manual submission. The architecture must handle all three and present results with appropriate confidence signals so families act on real findings, not false positives.

Source Taxonomy

Scanner Architecture

The benefit scanner is a Fly.io worker that runs on a cron schedule (once per week per active estate) and on-demand when triggered by the executor. It uses a source adapter pattern — each external source has an adapter implementing a common interface — allowing new sources to be added without modifying the core scanner logic.

// Source adapter interface
interface BenefitSourceAdapter {
  sourceId: string;
  type: 'api' | 'scrape' | 'manual_guidance';
  canAutoScan: boolean;

  scan(
    context: ScanContext
  ): Promise<BenefitScanResult[]>;
}

interface ScanContext {
  deceasedName: { first: string; last: string };
  deceasedSsn?: string;         // decrypted only for sources that require it
  dateOfDeath: Date;
  stateOfResidence: string;
  hasVeteranStatus: boolean;
}

interface BenefitScanResult {
  sourceId: string;
  confidence: 'confirmed' | 'probable' | 'possible';
  benefitType: string;
  estimatedValueCents?: number;
  claimUrl?: string;
  manualStepsRequired?: string[];
  rawData: Record<string, unknown>;
  scannedAt: Date;
}

Caching Strategy

External benefit databases must not be queried on every page load. Scan results are cached in Postgres with a scanned_at timestamp. The frontend shows the cached result with a freshness indicator. Scans are throttled: no source is queried more than once per 24 hours per estate, regardless of how many times the executor views the benefits page. This prevents accidental hammering of NAUPA or PBGC from a user repeatedly refreshing the page.

Confidence Model

Security Architecture

Settle handles death certificates, Social Security numbers, financial account numbers, and medical history. A breach of this data against a grieving family is a categorical failure. Security is not a feature to be added in Year 2 — every component in this document has been designed with Defense in Depth as a first principle.

Threat Model Summary

Defense in Depth: Layer View

Data Retention and the Right to Erasure

Estate records are retained for 7 years following estate closure, aligned with common statute of limitations for executor liability. At the 7-year mark, a background job initiates deletion: PII fields are overwritten with null values, documents are deleted from R2, and the estate record is anonymized (names replaced with hashed identifiers). The estate's task completion record and financial summary are retained in anonymized form for aggregate analytics.

For CCPA right-to-erasure requests during an active estate, the request is held pending estate closure (deletion during active administration would be legally problematic). The request is logged and honored automatically at closure plus a 90-day cooling-off period.

Scaling Strategy

Settle's growth trajectory — 500 estates in Year 1, 5,000 in Year 2, 50,000 in Year 3 — spans two orders of magnitude. The architecture is sized for Year 1 today and designed to scale to Year 3 without rearchitecting the core data model or notification service. Each year has a clear set of scaling gates that trigger architectural evolution.

Key Scaling Decisions and Their Triggers

Architecture Decision Records

Every significant architectural decision is recorded here with its context, the options considered, the decision made, and the tradeoffs accepted. These records are immutable once a decision is implemented — new decisions supersede rather than modify them.