Repository Overview

Next-generation government intake infrastructure built with modern cloud primitives

​

What’s Inside

​

Applications

• Terra - Form builder and intake management platform for government programs (experimental)
• Pathfinder - Client-facing portal for application tracking and document management
• Docs - Internal technical documentation (Mintlify)

​

Packages

• @unify/ui - Shared React component library built with Radix UI and Tailwind CSS
• @unify/database - Shared database types and utilities for Supabase
• @unify/identity - Shared applicant identity, profile, and history modules

​

Tech Stack

​

Core Framework

• Next.js 16 - React framework with App Router
• React 19 - UI library
• TypeScript 5 - Type safety
• Tailwind CSS 4 - Styling with @tailwindcss/postcss

​

Infrastructure

• Supabase - Postgres database with Row Level Security
• WorkOS - Enterprise SSO and authentication
• Vercel - Hosting and edge computing
• Doppler - Secrets management
• Resend - Transactional email
• Twilio - SMS notifications
• Sentry - Error monitoring and performance tracking
• PostHog - Product analytics

​

Developer Experience

• pnpm - Fast, disk-efficient package manager
• Turbo - High-performance monorepo build system
• Vitest - Unit and integration testing
• Playwright - End-to-end testing
• ESLint 9 - Code linting with flat config
• Prettier - Code formatting
• Husky - Git hooks

​

Quick Start

​

Prerequisites

• Node.js 20+ (via fnm or nvm)
• pnpm 9.14+ (npm install -g pnpm@9.14.4)
• Doppler CLI (optional, for secrets management)

​

Installation

# Clone the repository
git clone <repository-url>
cd unify-platform

# Install dependencies
pnpm install

# Set up environment variables
cp apps/terra/.env.example apps/terra/.env.local
# Edit .env.local with your credentials

# Run development servers
pnpm dev

• Terra at http://localhost:3000
• Pathfinder at http://localhost:3001

​

Environment Setup

​

Option 1: Doppler (Recommended for Teams)

# Install Doppler CLI
brew install dopplerhq/cli/doppler  # macOS
# or curl -sLf https://cli.doppler.com/install.sh | sh

# Login and configure
doppler login
doppler setup

# Run with Doppler
cd apps/terra
pnpm dev  # Automatically uses Doppler

​

Option 2: Local .env Files

# Supabase
NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=your-anon-key
SUPABASE_SERVICE_ROLE_KEY=your-service-role-key

# WorkOS (SSO)
WORKOS_API_KEY=sk_live_...
WORKOS_CLIENT_ID=client_...
WORKOS_COOKIE_PASSWORD=complex-password-min-32-chars
WORKOS_REDIRECT_URI=http://localhost:3000/auth/callback

# Resend (Email)
RESEND_API_KEY=re_...
EMAIL_FROM=noreply@yourdomain.com

# Twilio (SMS)
TWILIO_ACCOUNT_SID=AC...
TWILIO_AUTH_TOKEN=...
TWILIO_PHONE_NUMBER=+1...

# SmartyStreets (Address Validation)
SMARTY_AUTH_ID=your-auth-id
SMARTY_AUTH_TOKEN=your-auth-token

# DeepL (Translation)
DEEPL_API_KEY=your-deepl-key

# Google Drive (File Storage - Optional)
GOOGLE_SERVICE_ACCOUNT_EMAIL=...@...iam.gserviceaccount.com
GOOGLE_PRIVATE_KEY=-----BEGIN PRIVATE KEY-----...

# Sentry (Error Monitoring - Optional)
SENTRY_DSN=https://...@sentry.io/...
NEXT_PUBLIC_SENTRY_DSN=https://...@sentry.io/...

​

Development

​

Available Commands

​

Working with Specific Apps

# Run specific app
pnpm --filter terra dev
pnpm --filter pathfinder dev

# Build specific app
pnpm --filter terra build

# Test specific app
pnpm --filter terra test

​

Code Quality

• ESLint - Linting with React, TypeScript, and Next.js rules
• Prettier - Consistent code formatting
• TypeScript - Strict type checking
• Husky - Pre-commit hooks for formatting and linting
• Vitest - Unit and integration tests
• Playwright - End-to-end tests

​

Testing

​

Unit & Integration Tests

# Run all tests (watch mode)
pnpm test

# Run tests once (CI mode)
pnpm --filter terra exec vitest run

# Run with coverage
pnpm --filter terra test:coverage

# Run with UI
pnpm --filter terra test:ui

​

E2E Tests

# Install Playwright browsers (first time only)
pnpm --filter terra exec playwright install

# Run E2E tests
pnpm test:e2e

# Run with browser visible
pnpm --filter terra test:e2e:headed

# Run with interactive UI
pnpm --filter terra test:e2e:ui

• 310 passing unit/integration tests (~3.8s runtime)
• E2E tests configured (requires authentication setup to enable)

​

Project Structure

unify-platform/
├── apps/
│   ├── terra/                   # Main form builder application
│   │   ├── src/
│   │   │   ├── app/
│   │   │   │   ├── actions/     # Server Actions (database mutations)
│   │   │   │   ├── (dashboard)/ # Admin pages
│   │   │   │   └── (public)/    # Public form pages (/f/[slug])
│   │   │   ├── components/
│   │   │   │   ├── ui/          # Shadcn components
│   │   │   │   └── engine/      # Form rendering engine
│   │   │   ├── lib/
│   │   │   │   ├── dal/         # Data Access Layer (repositories)
│   │   │   │   └── form-import/ # PDF/image form import
│   │   │   └── types/           # TypeScript types
│   │   ├── migrations/          # SQL migrations (076+)
│   │   └── tests/               # E2E tests (Playwright)
│   ├── pathfinder/              # Client portal application
│   │   └── src/
│   │       ├── app/             # Portal pages
│   │       └── lib/             # Portal utilities
│   └── docs/                    # Technical documentation (Mintlify)
├── packages/
│   ├── ui/                      # Shared component library
│   ├── database/                # Shared database types
│   └── identity/                # Shared identity modules
│       └── src/
│           ├── profile/         # User profile management
│           └── history/         # Application history
├── .github/
│   └── workflows/               # CI/CD pipelines
├── turbo.json                   # Turbo configuration
└── pnpm-workspace.yaml          # Workspace configuration

​

Architecture Highlights

​

Terra (Form Builder)

• Form Engine: Recursive JSON schema with Zod validation
• Drag-and-Drop: @dnd-kit for intuitive form organization
• Multi-language: I18nString objects for unlimited translations
• Conditional Logic: Dynamic field visibility based on user input
• File Security: Supabase private buckets or Google Drive integration
• RBAC: Row Level Security in Postgres + WorkOS organizations
• White-label: Custom branding per agency (logos, colors, emails)
• Data Access Layer: Repository pattern with soft delete and audit hooks
• Notification Hub: Multi-channel notifications (email + SMS) with templates

​

Pathfinder (Client Portal)

• Application Tracking: Applicants can view submission status
• Document Management: Upload and manage supporting documents
• Multi-program Support: Browse and apply to multiple programs
• Profile Management: Shared identity across applications

​

Integrations

• Airtable: Two-way sync with automatic field mapping
• Google Drive: Direct file uploads with permanent URLs
• Plaid: Bank account verification for financial programs
• Webhooks: Outbound webhooks for downstream systems

​

Security Features

• Auth Guards: Centralized authorization checks for all server actions
• Path Traversal Protection: Sanitized file paths
• Open Redirect Prevention: Safe redirect validation
• XSS Prevention: React escaping + Content Security Policy + DOMPurify
• CSRF Protection: Server actions with token validation
• Rate Limiting: Upstash Redis-based API throttling (required in production)
• Audit Logging: All sensitive operations tracked
• PII Redaction: Automatic PII filtering in logs

​

CI/CD

​

GitHub Actions

1. Type Check (tsc --noEmit)
2. Lint (ESLint across all apps)
3. Test (Vitest unit tests)
4. Build (Next.js production builds)

​

Deployment

• Production: Automatically deployed via Vercel on merge to main
• Preview: Every PR gets a unique preview URL
• Environment Variables: Managed through Vercel + Doppler

​

Contributing

​

Commit Convention

feat: add export to PDF functionality
fix: resolve form validation edge case
docs: update setup guide with Doppler instructions
refactor: simplify server action error handling
test: add integration tests for form submission
chore: upgrade dependencies

​

Pull Request Process

1. Create a feature branch: git checkout -b feature/your-feature
2. Make your changes with clear, atomic commits
3. Run tests: pnpm test
4. Run linter: pnpm lint
5. Format code: pnpm format
6. Push and create a PR
7. Address review feedback
8. Merge after approval (squash and merge)

​

Code Style

• Use TypeScript for all new code
• Follow React best practices (hooks, composition, etc.)
• Write tests for new features
• Add JSDoc comments for complex functions
• Keep components small and focused
• Use semantic HTML and ARIA labels

​

Technical Debt

• Replace any with proper types (@typescript-eslint/no-explicit-any)
• Remove unused imports (@typescript-eslint/no-unused-vars)
• Use Next.js <Image /> for image optimization

​

Resources

​

Internal Documentation

• Technical Docs - Architecture, decisions, and guides
• Core Concepts - Mental models and system overview
• Local Development - Setup and workflow
• Testing Guide - E2E testing documentation
• Changelog - Release notes

​

External References

• Supabase Docs - Database and auth
• WorkOS Docs - SSO and SCIM
• Next.js Docs - Framework reference
• Sentry Docs - Error monitoring

​

License

​

Support

• Internal: Post in #engineering Slack channel
• External: Create a GitHub issue