> ## 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. # Repository Overview > **Next-generation government intake infrastructure** built with modern cloud primitives The Unify Platform is a monorepo containing experimental and production tools for government benefit program applications. We're exploring how serverless computing, edge networks, and composable authentication can transform public sector digital services. ## What's Inside This monorepo contains three applications and three shared packages: ### Applications * **[Terra](./apps/terra)** - Form builder and intake management platform for government programs (experimental) * **[Pathfinder](./apps/pathfinder)** - Client-facing portal for application tracking and document management * **[Docs](./apps/docs)** - Internal technical documentation (Mintlify) ### Packages * **[@unify/ui](./packages/ui)** - Shared React component library built with Radix UI and Tailwind CSS * **[@unify/database](./packages/database)** - Shared database types and utilities for Supabase * **[@unify/identity](./packages/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](https://github.com/Schniz/fnm) or nvm) * **pnpm 9.14+** (`npm install -g pnpm@9.14.4`) * **Doppler CLI** (optional, for secrets management) ### Installation ```bash theme={null} # Clone the repository git clone 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 ``` This starts: * Terra at `http://localhost:3000` * Pathfinder at `http://localhost:3001` ### Environment Setup #### Option 1: Doppler (Recommended for Teams) ```bash theme={null} # 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 Required environment variables for Terra: ```env theme={null} # 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/... ``` See `apps/terra/.env.example` for complete configuration. ## Development ### Available Commands | Command | Description | | ----------------- | ----------------------------- | | `pnpm dev` | Start all development servers | | `pnpm build` | Build all apps for production | | `pnpm lint` | Run ESLint across all apps | | `pnpm test` | Run all tests in watch mode | | `pnpm test:terra` | Run Terra tests only | | `pnpm test:e2e` | Run Playwright E2E tests | | `pnpm format` | Format code with Prettier | ### Working with Specific Apps ```bash theme={null} # Run specific app pnpm --dir apps/terra dev pnpm --filter pathfinder dev # Build specific app pnpm --dir apps/terra build # Test specific app pnpm --dir apps/terra test ``` ### Code Quality We enforce code quality through: * **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 ```bash theme={null} # Run all tests (watch mode) pnpm test # Run tests once (CI mode) pnpm --dir apps/terra exec vitest run # Run with coverage pnpm --dir apps/terra test:coverage # Run with UI pnpm --dir apps/terra test:ui ``` ### E2E Tests ```bash theme={null} # Install Playwright browsers (first time only) pnpm --dir apps/terra exec playwright install # Run E2E tests pnpm test:e2e # Run with browser visible pnpm --dir apps/terra test:e2e:headed # Run with interactive UI pnpm --dir apps/terra test:e2e:ui ``` **Current Test Coverage:** * **310 passing unit/integration tests** (\~3.8s runtime) * **E2E tests configured** (requires authentication setup to enable) See `apps/terra/tests/README.md` for E2E testing documentation. ## 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 Our CI pipeline runs on every push and pull request: ```yaml theme={null} 1. Type Check (tsc --noEmit) 2. Lint (ESLint across all apps) 3. Test (Vitest unit tests) 4. Build (Next.js production builds) ``` **Current Status:** ✅ All checks passing ### 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 We follow [Conventional Commits](https://www.conventionalcommits.org/): ```bash theme={null} 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 We maintain a backlog of technical improvements. Run `pnpm --dir apps/terra lint` to see current warnings. Common patterns to address: * Replace `any` with proper types (`@typescript-eslint/no-explicit-any`) * Remove unused imports (`@typescript-eslint/no-unused-vars`) * Use Next.js `` for image optimization See the [Engineering Planning](./apps/docs/operations/engineering-planning.mdx) doc for the roadmap. ## Resources ### Internal Documentation * **[Technical Docs](./apps/docs)** - Architecture, decisions, and guides * **[Core Concepts](./apps/docs/foundation/core-concepts.mdx)** - Mental models and system overview * **[Local Development](./apps/docs/operations/local-development.mdx)** - Setup and workflow * **[Testing Guide](./apps/terra/tests/README.md)** - E2E testing documentation * **[Changelog](./apps/docs/reference/changelog/overview.mdx)** - Release notes ### External References * **[Supabase Docs](https://supabase.com/docs)** - Database and auth * **[WorkOS Docs](https://workos.com/docs)** - SSO and SCIM * **[Next.js Docs](https://nextjs.org/docs)** - Framework reference * **[Sentry Docs](https://docs.sentry.io/platforms/javascript/guides/nextjs/)** - Error monitoring ## License Proprietary - All rights reserved ## Support For questions or issues: * **Internal**: Post in #engineering Slack channel * **External**: Create a GitHub issue *** Built for better government services