Skip to main content

​
Core Concepts

Before diving into code, understand the mental models that shape how Pathfinder matches people to benefits.
Pathfinder transforms the chaotic landscape of government benefits into a structured discovery experience. To work effectively with the codebase, internalize these five core concepts.

​
1. Programs Are Structured Data

Every benefit program—from federal SNAP to local utility assistance—is stored as a structured record with consistent fields. This enables searching, filtering, and automated eligibility checking. 
interface Program {
  id: string;
  name: string;                    // "Supplemental Nutrition Assistance Program"
  shortName: string;               // "SNAP"
  category: ProgramCategory;       // "food_assistance"
  agency: string;                  // "USDA Food and Nutrition Service"

  // Geographic scope
  coverageType: "federal" | "state" | "county" | "city";
  coverageStates: string[];        // ["CA", "TX", "NY"] or ["*"] for all
  coverageFips: string[];          // County FIPS codes for local programs

  // Eligibility
  eligibilityRules: EligibilityRule[];
  incomeLimit: IncomeLimit | null;

  // Impact
  benefitValueCents: number | null;
  benefitFrequency: "monthly" | "annual" | "one_time";

  // Content
  description: string;
  shortDescription: string;
  howToApply: ApplyStep[];
  requiredDocuments: DocumentRequirement[];

  // Search
  searchVector: tsvector;          // PostgreSQL full-text search
  tags: string[];
}
What this means for you:
  • Programs live in the programs table with a consistent schema
  • Adding new fields doesn’t require code changes—just database columns
  • The search_vector column enables fast full-text search with ranking
  • Geographic filtering uses FIPS codes for precision
See Programs Database for the full schema.

​
2. Eligibility Is Rule-Based

Each program has eligibility rules stored as JSON. The screener collects household data, then evaluates these rules to determine potential eligibility. Rules follow a composable structure: 
interface EligibilityRule {
  field: string;        // "household_income_monthly"
  operator: Operator;   // "less_than_or_equal"
  value: number | string | boolean;

  // Optional: for compound rules
  conjunction?: "AND" | "OR";
  children?: EligibilityRule[];
}

// Example: SNAP eligibility
const snapRules: EligibilityRule[] = [
  {
    field: "household_income_monthly",
    operator: "less_than_fpl_percent",
    value: 130  // 130% of Federal Poverty Level
  },
  {
    field: "citizenship_status",
    operator: "in",
    value: ["citizen", "qualified_alien", "refugee"]
  },
  {
    field: "resources",
    operator: "less_than",
    value: 250000  // $2,500 in cents
  }
]
What this means for you:
  • Rules are data, not code—you can update eligibility without deploys
  • The engine handles FPL calculations based on household size
  • “Maybe eligible” is a valid result when data is incomplete
  • Programs without explicit rules are assumed “possibly eligible”
See Eligibility Engine for the matching algorithm.

​
3. Screening Is Progressive

Users don’t answer all questions upfront. The screener progressively refines matches as more information is provided. Each step:
  1. Collects one piece of information
  2. Immediately updates the match count
  3. Shows progress toward personalized results
What this means for you:
  • The screener state tracks partial answers
  • Match queries run after each step (debounced)
  • Empty fields don’t disqualify—they reduce confidence
  • Users can skip steps and return later

​
4. Geography Is Hierarchical

Benefits exist at multiple levels: federal, state, county, city. A user in Austin, Texas might qualify for:
  • Federal programs (SNAP, Medicaid)
  • Texas state programs (CHIP, TWC)
  • Travis County programs (housing assistance)
  • City of Austin programs (utility assistance)
Geographic resolution:
  1. ZIP to Coordinates: Geocode via Nominatim
  2. Coordinates to FIPS: Point-in-polygon to county FIPS code
  3. FIPS to Programs: Filter programs by coverage area
-- Programs available in Travis County, TX
SELECT * FROM programs
WHERE coverage_type = 'federal'
   OR (coverage_type = 'state' AND 'TX' = ANY(coverage_states))
   OR (coverage_type = 'county' AND '48453' = ANY(coverage_fips))
   OR (coverage_type = 'city' AND '48453' = ANY(coverage_fips)
       AND service_area @> '{"city": "Austin"}');
What this means for you:
  • Always store FIPS codes, not just city/state names
  • Use the geocoding.ts utilities for ZIP resolution
  • Some programs serve multiple counties—use array containment
  • Federal programs use coverage_states = ['*'] for “all states”

​
5. Trust Is Earned Through Stories

Government benefits carry stigma. Many people won’t apply because they feel ashamed or assume “those programs aren’t for people like me.” Success stories counter this by showing real people—with faces and names—who benefited. Story data model: 
interface SuccessStory {
  id: string;
  authorName: string;
  isAnonymous: boolean;

  // Content
  title: string;
  story: string;           // Full narrative
  quote: string | null;    // Pull quote for cards

  // Association
  programId: string | null;
  benefitReceivedCents: number | null;

  // Moderation
  status: "pending" | "approved" | "rejected" | "featured";
  moderatedBy: string | null;
  rejectionReason: string | null;

  // Engagement
  viewCount: number;
  helpfulCount: number;
}
What this means for you:
  • Stories require moderation before publishing
  • Anonymous stories show “Anonymous” but we track author_id for editing
  • The quote field enables compact display in carousels
  • helpfulCount uses deduplicated voting (one per user/session)
See Success Stories for implementation details.

​
How These Concepts Connect

A typical user flow:
  1. User arrives at Pathfinder, browses programs by category
  2. Starts screener, enters ZIP code
  3. Engine matches programs by geography
  4. User provides income/household data
  5. Engine applies eligibility rules
  6. User sees personalized recommendations
  7. User saves programs to dashboard
  8. Calendar reminders for application deadlines
  9. After receiving benefits, shares success story

​
Next Steps

System Map

Visual overview of all Pathfinder components

Programs Database

Deep dive into the programs schema