> ## Documentation Index
> Fetch the complete documentation index at: https://docs-terra.withunify.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Welcome to Pathfinder

> Engineering documentation for Pathfinder - a benefits discovery and eligibility screening platform

# Welcome to Pathfinder

> Pathfinder helps people discover government benefits they qualify for by transforming complex eligibility rules into simple, guided screening experiences.

In the United States, billions of dollars in public benefits go unclaimed each year—not because people don't need them, but because they don't know they exist or assume they won't qualify. Pathfinder bridges this gap by providing an intelligent benefits discovery platform that meets people where they are.

***

## What Pathfinder Does

At its core, Pathfinder is a **benefits discovery platform** with five integrated components:

<CardGroup cols={3}>
  <Card title="Benefits Browser" icon="compass">
    Searchable catalog of federal, state, and local benefit programs with full-text search and geographic filtering
  </Card>

  <Card title="Eligibility Screener" icon="clipboard-check">
    Multi-step questionnaire that matches users to programs based on their household situation
  </Card>

  <Card title="User Dashboard" icon="gauge">
    Personal hub for tracking applications, documents, and upcoming deadlines
  </Card>
</CardGroup>

<CardGroup cols={2}>
  <Card title="Case Manager Portal" icon="users">
    Tools for social workers and navigators to help clients discover and apply for benefits
  </Card>

  <Card title="Success Stories" icon="sparkles">
    Community testimonials that inspire action and reduce stigma around benefit programs
  </Card>
</CardGroup>

Underneath these user-facing features, Pathfinder handles:

* **Eligibility Matching**: Rule-based engine that evaluates household data against program requirements
* **Document Management**: Secure upload, preview, and expiration tracking for supporting documents
* **Notifications**: Email and SMS alerts for deadlines, status changes, and new opportunities
* **Calendar Integration**: One-click export of renewal dates and deadlines to Google Calendar
* **Offline Support**: PWA with cached data for users with unreliable internet access

***

## The Problem We're Solving

```mermaid theme={null}
flowchart LR
    subgraph Current State
        User[Person in Need] --> Search[Web Search]
        Search --> Confusion[Confusing Information]
        Confusion --> Overwhelm[Program Overload]
        Overwhelm --> Abandon[Give Up]
    end

    subgraph With Pathfinder
        User2[Person in Need] --> Screener[Answer Questions]
        Screener --> Match[Matched Programs]
        Match --> Apply[Guided Applications]
        Apply --> Benefits[Receive Benefits]
    end
```

| Challenge                          | How Pathfinder Helps                          |
| ---------------------------------- | --------------------------------------------- |
| "I don't know what programs exist" | Browsable catalog with 2,500+ programs        |
| "I probably don't qualify"         | Pre-screening shows estimated eligibility     |
| "Applications are too complicated" | Step-by-step guidance and document checklists |
| "I forgot to renew"                | Calendar reminders and SMS notifications      |
| "I don't have reliable internet"   | Offline-first PWA with local caching          |

***

## Architecture Overview

Pathfinder is built on the same foundation as Terra but optimized for the benefits discovery use case:

```mermaid theme={null}
flowchart TD
    subgraph Client
        Browser[Web Browser/PWA]
        Offline[IndexedDB Cache]
    end

    subgraph Edge
        Next[Next.js App Router]
        Static[Static Assets]
    end

    subgraph Backend
        Actions[Server Actions]
        DAL[Data Access Layer]
    end

    subgraph Storage
        Supabase[(Supabase PostgreSQL)]
        Files[(File Storage)]
    end

    subgraph External
        Geocoding[Nominatim Geocoding]
        Email[Resend Email]
        SMS[Twilio SMS]
    end

    Browser --> Next
    Offline --> Browser
    Next --> Actions
    Actions --> DAL
    DAL --> Supabase
    DAL --> Files
    Actions --> Geocoding
    Actions --> Email
    Actions --> SMS
```

***

## Who This Is For

This documentation is for **engineers** building and maintaining Pathfinder. It covers:

<Steps>
  <Step title="Foundation">
    Core concepts, system architecture, and the benefits matching mental model
  </Step>

  <Step title="Core Systems">
    Programs database, eligibility engine, and matching algorithms
  </Step>

  <Step title="Features">
    Screener, dashboard, notifications, calendar, documents, case manager, and success stories
  </Step>

  <Step title="Components">
    Reusable UI components with documentation and examples
  </Step>

  <Step title="Operations">
    Local development, deployment, and data management
  </Step>
</Steps>

***

## Quick Links

<CardGroup cols={2}>
  <Card title="Core Concepts" icon="brain" href="/pathfinder/foundation/core-concepts">
    Mental models for benefits matching and eligibility
  </Card>

  <Card title="System Map" icon="diagram-project" href="/pathfinder/foundation/system-map">
    How all the components connect
  </Card>

  <Card title="Programs Database" icon="database" href="/pathfinder/core-systems/programs-database">
    Schema and queries for benefit programs
  </Card>

  <Card title="Eligibility Engine" icon="gears" href="/pathfinder/core-systems/eligibility-engine">
    How screening and matching works
  </Card>
</CardGroup>

***

## Design Principles

<AccordionGroup>
  <Accordion title="Meet People Where They Are">
    Not everyone has reliable internet, speaks English, or trusts government websites. Pathfinder works offline, supports multiple languages, and builds trust through success stories from real people.
  </Accordion>

  <Accordion title="Assume Nothing About Eligibility">
    Many people self-exclude from benefits they actually qualify for. Pathfinder encourages exploration—show what's possible before asking for detailed information.
  </Accordion>

  <Accordion title="Reduce Cognitive Load">
    Benefits applications are mentally exhausting. Break complex processes into small steps. Show progress. Celebrate milestones. Make the next action obvious.
  </Accordion>

  <Accordion title="Empower Navigators">
    Case managers and social workers multiply impact. Give them tools to manage multiple clients, track outcomes, and make bulk referrals efficiently.
  </Accordion>

  <Accordion title="Celebrate Success">
    Receiving benefits can feel stigmatizing. Success stories normalize the experience and show real impact—putting human faces on abstract programs.
  </Accordion>
</AccordionGroup>

***

## Key Differences from Terra

While Pathfinder shares infrastructure with Terra, it serves a different purpose:

| Aspect                | Terra                                  | Pathfinder                        |
| --------------------- | -------------------------------------- | --------------------------------- |
| **Primary User**      | Government staff creating intake forms | Individuals discovering benefits  |
| **Data Flow**         | Collect applicant data for programs    | Match programs to applicant needs |
| **Form Ownership**    | Agencies create custom forms           | Pathfinder owns the screener      |
| **Integration Focus** | Case management systems                | Calendar, notifications, PWA      |
| **Success Metric**    | Submissions collected                  | Benefits accessed                 |

***

## Ready to Dive In?

Start with [Core Concepts](/pathfinder/foundation/core-concepts) to understand how benefits matching works, or jump to [Programs Database](/pathfinder/core-systems/programs-database) to see how we store and query benefit programs.