Skip to main content

​
System Map

A visual guide to how Pathfinder’s components connect and data flows through the system.

​
High-Level Architecture

​
Component Breakdown

​
Client Layer

ComponentPurposeTechnology
Web BrowserPrimary user interfaceReact 19, Next.js 15
PWA ShellInstallable app experiencenext-pwa, Service Worker
IndexedDB CacheOffline program storageCustom wrapper with IDB

​
Application Layer

ComponentPurposeLocation
App RouterPage routing and layoutssrc/app/
Server ActionsMutations and data fetchingsrc/app/actions/
Data Access LayerRepository pattern for DBsrc/lib/dal/
ComponentsReusable UI elementssrc/components/

​
Data Layer

ComponentPurposeDetails
PostgreSQLPrimary databaseSupabase-hosted, RLS enabled
Full-Text SearchProgram searchtsvector with GIN index
File StorageDocument uploadsSupabase Storage, signed URLs

​
Data Flow: Screener to Match

​
Data Flow: Document Upload

​
Data Flow: Notification Delivery

​
Directory Structure

apps/pathfinder/src/
├── app/
│   ├── (dashboard)/           # Authenticated pages
│   │   ├── dashboard/         # User dashboard
│   │   ├── programs/          # Program details
│   │   ├── applications/      # Application tracking
│   │   ├── documents/         # Document management
│   │   ├── notifications/     # Notification history
│   │   ├── share-story/       # Story submission
│   │   └── case-manager/      # Case manager portal
│   ├── (public)/              # Public pages
│   │   ├── browse/            # Program browser
│   │   ├── screener/          # Eligibility screener
│   │   └── stories/           # Success stories
│   ├── api/                   # API routes
│   └── actions/               # Server actions
├── components/
│   ├── browse/                # Browse page components
│   ├── screener/              # Screener flow components
│   ├── dashboard/             # Dashboard widgets
│   ├── documents/             # Document management
│   ├── calendar/              # Calendar integration
│   ├── notifications/         # Notification UI
│   ├── success-stories/       # Story components
│   ├── case-manager/          # Case manager UI
│   ├── map/                   # Map components
│   ├── pwa/                   # PWA install prompt
│   ├── offline/               # Offline indicators
│   └── skeletons/             # Loading skeletons
├── lib/
│   ├── dal/                   # Data Access Layer
│   │   └── repositories/      # Database repositories
│   ├── eligibility/           # Eligibility engine
│   ├── calendar/              # ICS generation
│   ├── offline/               # IndexedDB caching
│   ├── geocoding.ts           # ZIP to coordinates
│   ├── notifications.ts       # Email/SMS sending
│   ├── email.ts               # Resend client
│   └── sms.ts                 # Twilio client
├── hooks/                     # React hooks
└── types/                     # TypeScript types

​
Database Schema Overview

​
External Service Integration

Nominatim Geocoding

OpenStreetMap-based geocoding for ZIP to coordinates conversion. Self-hosted option available for high volume.

Resend Email

Transactional email delivery for notifications, reminders, and status updates. React Email templates.

Twilio SMS

SMS notifications for time-sensitive alerts like deadline reminders and status changes.

Supabase

PostgreSQL database with Row Level Security, real-time subscriptions, and file storage.

​
Next Steps

Programs Database

Deep dive into the programs schema and queries

Eligibility Engine

How the matching algorithm works