Design Philosophy

Every technical decision encodes a belief. Here’s what we believe.

Terra isn’t just a forms platform—it’s an opinionated take on how government intake infrastructure should work. This page explains the principles that guide our technical decisions.

Principle 1: Applicant Data Is Sacred

Government benefit applications contain the most sensitive information people share: Social Security numbers, income documentation, disability status, immigration records. A data breach doesn’t just expose information—it can result in identity theft, benefit denial, or deportation. This principle shapes everything:

Decision	Rationale
Private storage buckets	Files are never publicly accessible, even by accident
Signed URLs with 60s expiry	Leaked URLs become useless within a minute
Submissions succeed independently	External service failures don’t lose applicant data
Defense-in-depth security	Multiple layers mean single bugs don’t cause breaches

When we face a tradeoff between convenience and data protection, data protection wins. Every time.

Principle 2: Fail Secure, Not Fail Open

Security bugs are inevitable. The question is: when something goes wrong, what happens? Fail open means errors grant access. A crashed permission check lets the user through. Fail secure means errors deny access. A crashed permission check redirects to login. We chose fail secure:

// Every permission check follows this pattern
export async function requireAdmin() {
  try {
    const session = await getSession();
    const user = await getUserWithRole(session.user.id);

    if (user?.role !== 'admin' && user?.role !== 'super_admin') {
      throw new Error('Forbidden');
    }

    return user;
  } catch (error) {
    // ANY error = no access
    throw new Error('Unauthorized');
  }
}

This extends to every security decision:

Unknown role? Treat as applicant (lowest privilege)
Can’t parse redirect URL? Go to home page
File path looks suspicious? Reject the upload
Session decryption fails? Redirect to login

Principle 3: Explicit Over Magic

Frameworks love magic. Automatic code splitting, implicit data fetching, hidden configuration. Magic is convenient until it breaks—then you’re debugging something you don’t understand. Terra prefers explicit patterns: Server actions, not API routes

// Explicit: you see exactly what's happening
"use server";

export async function updateFormStatus(formId: string, status: FormStatus) {
  const user = await requireAdmin();

  await supabaseAdmin
    .from('forms')
    .update({ status })
    .eq('id', formId);

  await logAudit(user.id, 'form.status.updated', { formId, status });

  return { success: true };
}

Manual permission checks, not middleware magic

// We check permissions in every action, explicitly
export async function getSubmissions(formId: string) {
  const user = await requireFormAccess(formId); // Explicit check

  // Now we know the user has access
  const submissions = await fetchSubmissions(formId);
  return submissions;
}

Zustand stores, not Context gymnastics

// State management is explicit and inspectable
const useFormBuilder = create((set) => ({
  schema: initialSchema,
  selectedFieldId: null,

  addField: (field) => set((state) => ({
    schema: { ...state.schema, elements: [...state.schema.elements, field] }
  })),
}));

When you read Terra code, you should understand what’s happening without knowing framework internals.

Principle 4: JSON for Flexibility, Zod for Safety

Government forms are weird. Conditional sections, repeatable groups, custom validation rules, translated labels. A normalized database schema would require migrations for every new form feature. We use JSONB for flexibility:

// The entire form definition is one JSON tree
const form = {
  id: "rental-assistance",
  schema: {
    elements: [
      { type: "text", id: "name", label: { en: "Full Name" } },
      { type: "group", id: "household", elements: [...] },
      { type: "repeated", id: "income-sources", min: 1, max: 5, template: {...} }
    ]
  }
};

But JSON is stringly-typed. You can put anything in there. So we validate with Zod:

// Runtime validation catches schema errors
export const FormElementSchema = z.discriminatedUnion("type", [
  TextFieldSchema,
  ChoiceFieldSchema,
  GroupFieldSchema,
  RepeatedFieldSchema,
  // ... 20+ field types
]);

// This runs on every schema load
const validated = FormElementSchema.parse(element);

The combination gives us:

Flexibility: Add new field types without migrations
Safety: Invalid schemas fail fast with clear errors
Portability: Export/import forms as JSON files
Versioning: Store draft and published schemas side by side

Principle 5: Async by Default

External services fail. Airtable rate limits. Twilio has outages. Webhook endpoints timeout. If form submission depends on external services, applicants suffer for infrastructure problems. Our solution: submissions are synchronous, everything else is async. Benefits:

Applicants see success in ~300ms regardless of integration health
Failed operations retry automatically with exponential backoff
Dead-letter queue captures persistent failures for manual review
Integration outages don’t create support tickets

Principle 6: Server-First, Client-Lite

React traditionally runs in the browser. The server sends HTML, then JavaScript hydrates it into an interactive app. This creates security risks: secrets can leak into client bundles, API keys can be extracted, business logic can be reverse-engineered. Terra uses React Server Components (RSC) to keep sensitive logic on the server:

// This component runs ONLY on the server
export default async function SubmissionsPage({ params }) {
  // Database query happens server-side
  const submissions = await getSubmissions(params.formId);

  // Only the rendered HTML goes to the client
  return <SubmissionsTable data={submissions} />;
}

Client components exist for interactivity (form inputs, drag-drop, modals) but they receive pre-fetched data rather than making their own API calls. What stays on the server:

Database credentials and queries
Permission checks
File signed URL generation
Integration API keys
Encryption/decryption

What runs on the client:

Form input handling (react-hook-form)
Drag-and-drop (dnd-kit)
UI state (modals, tabs, accordions)
File uploads (after receiving signed URL)

Principle 7: White-Label as a Feature

Government agencies have strong brand requirements. Their forms should look like “their” forms, not a third-party service. Terra is designed to be invisible. Branding is configurable at every level:

Organization: Logo, colors, fonts
Folder (workspace): Override logo, custom domain
Form: Override any setting, form-specific domain

Custom domains are first-class:

housing.example.gov → routes to Housing folder
benefits.example.gov → routes to Benefits folder
apply.example.gov/rental → routes to specific form

Email templates are brandable:

<SubmissionReceipt
  logo={organization.branding.logo}
  primaryColor={organization.branding.primaryColor}
  supportUrl={form.supportUrl}
/>

The applicant never sees “Terra” or “Unify”—just their agency’s brand.

Principle 8: Multi-Language by Design

Government forms serve diverse populations. Language support isn’t a plugin—it’s baked into the data model. Every user-facing string is an I18nString:

type I18nString = {
  en: string;
  es?: string;
  zh?: string;
  // ... any language code
};

// Field labels, placeholders, error messages, help text
const field = {
  type: "text",
  label: { en: "Full Name", es: "Nombre Completo" },
  placeholder: { en: "Enter your name", es: "Ingrese su nombre" },
};

Translation workflow:

Create form in English
Add languages to form settings
Auto-translate with DeepL (or translate manually)
Applicants switch languages at runtime

The form builder shows all languages simultaneously—no switching modes to edit translations.

Principle 9: Audit Everything

When something goes wrong (and it will), you need to know what happened. Terra logs every significant action:

// Audit log entry structure
{
  user_id: "usr_123",
  action: "form.schema.updated",
  resource_type: "form",
  resource_id: "form_456",
  changes: {
    before: { status: "draft" },
    after: { status: "published" }
  },
  ip_address: "192.168.1.1",
  user_agent: "Mozilla/5.0...",
  created_at: "2025-01-02T10:30:00Z"
}

Every form edit, status change, permission grant, and file access is recorded. Audit logs are immutable (append-only table) and retained indefinitely. This enables:

Debugging: “Who changed this field label?”
Compliance: “Show all accesses to this applicant’s data”
Security: “What did this user do before we revoked access?”

Principle 10: Boring Technology (Mostly)

Innovation is expensive. Every new technology requires learning, debugging, and maintenance. Terra uses boring, proven technologies wherever possible:

Layer	Technology	Why
Framework	Next.js	Massive ecosystem, Vercel support
Database	PostgreSQL	30 years of battle-testing
Validation	Zod	Simple, composable, TypeScript-first
Styling	Tailwind	Utility-first, no CSS debugging
State	Zustand	Minimal API, great DevTools
Email	React Email	Just React, render to HTML

We reserve complexity for problems that need it:

Form schema (novel problem → custom solution)
Async queue (specific requirements → custom table)
AI form import (genuinely complex → novel approach)

But auth? We use WorkOS. Storage? Supabase. Email delivery? Resend. These are solved problems—we don’t need to re-solve them.

Summary

Principle	One-liner
Applicant Data Is Sacred	Protect data above all else
Fail Secure	Errors deny access, never grant it
Explicit Over Magic	Code should be readable without framework knowledge
JSON + Zod	Flexibility with safety
Async by Default	Submissions succeed, integrations retry
Server-First	Keep secrets and logic on the server
White-Label	Agencies own their brand
Multi-Language by Design	I18n isn’t an afterthought
Audit Everything	Know what happened
Boring Technology	Innovate only where necessary

Foundation

Core Systems

Features

Integrations

Operations

Reference

Design Philosophy

Design Philosophy

Principle 1: Applicant Data Is Sacred

Principle 2: Fail Secure, Not Fail Open

Principle 3: Explicit Over Magic

Principle 4: JSON for Flexibility, Zod for Safety

Principle 5: Async by Default

Principle 6: Server-First, Client-Lite

Principle 7: White-Label as a Feature

Principle 8: Multi-Language by Design

Principle 9: Audit Everything

Principle 10: Boring Technology (Mostly)

Summary

Next Steps

Forms Engine

Local Development

Foundation

Core Systems

Features

Integrations

Operations

Reference

​Design Philosophy

​Principle 1: Applicant Data Is Sacred

​Principle 2: Fail Secure, Not Fail Open

​Principle 3: Explicit Over Magic

​Principle 4: JSON for Flexibility, Zod for Safety

​Principle 5: Async by Default

​Principle 6: Server-First, Client-Lite

​Principle 7: White-Label as a Feature

​Principle 8: Multi-Language by Design

​Principle 9: Audit Everything

​Principle 10: Boring Technology (Mostly)

​Summary

​Next Steps

Forms Engine

Local Development

Design Philosophy

Principle 1: Applicant Data Is Sacred

Principle 2: Fail Secure, Not Fail Open

Principle 3: Explicit Over Magic

Principle 4: JSON for Flexibility, Zod for Safety

Principle 5: Async by Default

Principle 6: Server-First, Client-Lite

Principle 7: White-Label as a Feature

Principle 8: Multi-Language by Design

Principle 9: Audit Everything

Principle 10: Boring Technology (Mostly)

Summary

Next Steps