Technology Stack

Terra is built on a modern, serverless-first architecture. Each choice reflects a hypothesis we’re testing about building government intake infrastructure.

Monorepo Structure

Terra uses a Turborepo monorepo with pnpm workspaces:

unify-platform/
├── apps/
│   ├── terra/              # Main Next.js application
│   └── docs/               # Mintlify documentation
├── packages/
│   └── ui/                 # @unify/ui - Shared component library
├── turbo.json              # Turborepo configuration
└── pnpm-workspace.yaml     # Workspace definitions

Why Monorepo?

Shared Components: The @unify/ui package contains all Shadcn UI components, enabling reuse across future apps
Atomic Deploys: Turborepo ensures dependent packages build in the correct order
Single Lock File: pnpm workspaces share dependencies, reducing install times and disk usage

@unify/ui Package

All UI primitives (Button, Card, Input, Dialog, etc.) live in packages/ui:

// Import from the shared package
import { Button, Card, Input } from "@unify/ui";

This keeps apps/terra focused on business logic while UI components remain reusable.

Frontend

Next.js 16

App Router with React 19 Server Components. Server-side rendering keeps sensitive logic off the client.

Tailwind CSS 4

Utility-first CSS with Shadcn UI components built on Radix primitives.

Core Libraries

Library	Version	Purpose
`react-hook-form`	7.66	Form state management with minimal re-renders
`zod`	4.1	Runtime schema validation for forms and API inputs
`zustand`	5.0	Lightweight state management for the form builder
`@dnd-kit`	6.3	Drag-and-drop for form builder and folder organization
`framer-motion`	12.x	Animations and micro-interactions
`recharts`	2.15	Dashboard charts and visualizations
`lucide-react`	0.555	Icon library

Why Next.js App Router?

We’re testing whether React Server Components can improve security posture for government applications:

Server-side by default: Sensitive operations (database queries, auth checks) never reach the client bundle
Streaming: Large forms render progressively, improving perceived performance
Edge-ready: Middleware runs at the edge for fast auth checks globally

Backend

Supabase

PostgreSQL with Row Level Security, Auth helpers, and private Storage buckets.

WorkOS AuthKit

Enterprise-ready SSO (SAML, OIDC) with 1M free monthly active users.

Why Supabase?

We’re testing whether pushing authorization into the database layer reduces application risk:

-- Example: Row Level Security policy
CREATE POLICY "Users can only view their own submissions"
ON submissions FOR SELECT
USING (user_id = auth.uid());

Hypothesis: If the database enforces access control, application bugs are less likely to expose data. Storage: All file uploads go to private buckets. Zero public URLs—files are only accessible via 60-second signed URLs generated server-side.

Why WorkOS?

We chose WorkOS over Supabase Auth for several reasons:

Enterprise SSO Ready: Government agencies often require SAML/OIDC integration with Azure AD, Okta, or Google Workspace. WorkOS makes this trivial.
Generous Free Tier: 1 million monthly active users on the free plan—enough for most programs.
Clean Developer Experience: AuthKit handles session management, token refresh, and middleware with minimal boilerplate.
Future-Proof: Directory Sync and Audit Logs align with government compliance requirements.

Email

Resend

Transactional email with React Email templates. Production domain: notifications.withunify.org

Why Resend?

Resend handles lightweight, brandable receipts—the “your application was received” emails that applicants expect immediately. Complex notification workflows (reminders, status updates, multi-channel delivery) remain in external systems. This keeps Terra focused on intake, not becoming a notification platform.

// React Email template example
<SubmissionReceipt
  applicantName="Jane Doe"
  programName="Rental Assistance"
  submissionId="APP-2024-001"
  portalUrl="https://portal.example.gov"
/>

Translations

DeepL

Machine translation API for auto-translating form content and UI strings.

Why DeepL?

Government forms must serve diverse populations. DeepL offers:

Superior Quality: Consistently better translations than Google Translate for formal documents
Privacy-Conscious: Data not used for training models (important for government)
Simple API: Single endpoint for translation, no complex setup
Generous Free Tier: 500,000 characters/month on the free API

DeepL supports 14 languages with auto-translate. Languages not supported by DeepL (Somali, Vietnamese, etc.) can still be added for manual translation. See the Translations Guide for implementation details.

Address Verification

Smarty Streets

USPS address autocomplete and validation for accurate mail delivery.

Why Smarty Streets?

Government programs require accurate addresses for benefit delivery. Smarty Streets offers:

USPS Certified: Official CASS-certified address validation
Autocomplete: Real-time address suggestions as users type (requires US Autocomplete Pro subscription)
Standardization: Converts “123 main st” to “123 Main Street NW”
Deliverability: DPV codes indicate if mail can actually be delivered

How It Works

When Smarty credentials are configured:

User starts typing → Autocomplete suggestions appear after 3 characters
User selects suggestion → All address fields auto-fill + ”✓ Verified” badge appears
User manually edits → Badge changes to ”⚠ Unverified”

This provides frictionless UX while clearly indicating whether the address has been validated.

Smarty Products Required

Product	Purpose
US Autocomplete Pro	Type-ahead suggestions ($21/month)
US Street API	Address verification (free tier: 250/month)

Address fields work without Smarty—users just type manually without autocomplete.

Analytics

PostHog

Product analytics for understanding form completion rates and drop-off points.

Security

DOMPurify

XSS sanitization for user-generated HTML content (isomorphic-dompurify for SSR).

Aikido

Automated SAST scanning and dependency vulnerability detection.

Security Utilities

Terra includes centralized security functions in src/lib/security.ts:

Function	Purpose
`getSafeRedirectPath()`	Prevents open redirect attacks
`sanitizeStoragePath()`	Prevents path traversal in file storage
`cleanFileName()`	Sanitizes user-provided filenames
`DOMPurify.sanitize()`	Strips malicious scripts from HTML

See the Security Guide for implementation details.

Developer Tools

# Build System
turborepo           # Monorepo task orchestration
pnpm                # Fast, disk-efficient package manager

# Testing
vitest              # Unit tests (React Testing Library)
playwright          # E2E tests (multi-browser)

# Code Quality
typescript 5.x      # Type safety
eslint 9.x          # Linting
tailwindcss 4.x     # CSS

# Security
aikido              # SAST scanning on PRs

# CI/CD
github-actions      # Type check + test on every PR

Test Commands

pnpm test           # Unit tests (Vitest)
pnpm test:e2e       # E2E tests (Playwright)
pnpm lint           # ESLint
pnpm build          # Type check + production build (via Turborepo)
pnpm dev            # Start dev server (auto-injects Doppler secrets)

Database Schema

Terra uses a small number of tables with JSONB for flexibility:

-- Core Tables
forms              -- Form definitions (JSONB schema)
submissions        -- User submissions (JSONB answers)
users              -- User profiles synced from WorkOS
program_members    -- Form-level access control (RBAC)
folders            -- Form organization (drag-and-drop)

-- System Tables
organization_settings  -- Global branding and localization dictionary

Why JSONB for Forms?

See ADR-001: Recursive Form Schema for the full decision record. TL;DR: Government forms have deeply nested conditional logic. JSONB trees are more flexible than normalized tables for this use case.

Secrets Management

Doppler

Centralized secrets management with automatic environment syncing.

Why Doppler?

Managing environment variables across local development, staging, and production is error-prone. Doppler provides:

Single Source of Truth: All secrets in one dashboard
Environment Branching: Separate configs for dev/staging/prod
Team Sync: No more sharing .env files over Slack
Audit Logs: Track who accessed which secrets when
Automatic Rotation: Update secrets without redeploying

Usage

# Install CLI
brew install dopplerhq/cli/doppler

# Login and setup
doppler login
doppler setup

# Run with injected secrets
doppler run -- npm run dev

# Or create an alias
alias terra="doppler run -- npm run dev"

Vercel Integration

Doppler syncs directly to Vercel:

Connect Doppler to Vercel in the Doppler dashboard
Map your Doppler project to your Vercel project
Secrets automatically sync on change

Terra works fine with traditional .env.local files—Doppler is recommended but not required.

Infrastructure

Service	Provider	Purpose
Hosting	Vercel	Edge-optimized Next.js deployment
Database	Supabase	Managed PostgreSQL + Storage
Auth	WorkOS	Enterprise SSO and user management
Secrets	Doppler	Centralized secrets management
Email	Resend	Transactional receipts
Translation	DeepL	Auto-translate form content
Address	Smarty Streets	USPS address validation
DNS	Cloudflare	DDoS protection and caching

Next: Architecture Decisions

Read the ADRs explaining why we made these choices.

Getting Started

Architecture

Guides

Quality Improvements

​Technology Stack

​Monorepo Structure

​Why Monorepo?

​@unify/ui Package

​Frontend

Next.js 16

Tailwind CSS 4

​Core Libraries

​Why Next.js App Router?

​Backend

Supabase

WorkOS AuthKit

​Why Supabase?

​Why WorkOS?

​Email

Resend

​Why Resend?

​Translations

DeepL

​Why DeepL?

​Address Verification

Smarty Streets

​Why Smarty Streets?

​How It Works

​Smarty Products Required

​Analytics

PostHog

​Security

DOMPurify

Aikido

​Security Utilities

​Developer Tools

​Test Commands

​Database Schema

​Why JSONB for Forms?

​Secrets Management

Doppler

​Why Doppler?

​Usage

​Vercel Integration

​Infrastructure

Next: Architecture Decisions

Technology Stack

Monorepo Structure

Why Monorepo?

@unify/ui Package

Frontend

Core Libraries

Why Next.js App Router?

Backend

Why Supabase?

Why WorkOS?

Email

Why Resend?

Translations

Why DeepL?

Address Verification

Why Smarty Streets?

How It Works

Smarty Products Required

Analytics

Security

Security Utilities

Developer Tools

Test Commands

Database Schema

Why JSONB for Forms?

Secrets Management

Why Doppler?

Usage

Vercel Integration

Infrastructure