Welcome to Terra

Terra is an experimental platform exploring how modern cloud primitives can transform government intake infrastructure.

Government benefit programs—housing assistance, childcare subsidies, food security—require complex application forms. These forms collect sensitive data, enforce intricate eligibility rules, and integrate with legacy case management systems. Terra is our laboratory for building this infrastructure better.

What Terra Does

At its core, Terra is a forms platform with three components:

Form Builder

Visual editor for creating complex, multi-language forms with conditional logic

Applicant Portal

Public-facing forms and status tracking for applicants

Admin Dashboard

Submission management, analytics, and team collaboration

But the forms are just the surface. Underneath, Terra handles:

Identity & Access: Enterprise SSO, role-based permissions, applicant identity
File Storage: Private buckets with signed URLs, Google Drive integration
Integrations: Airtable sync, webhooks, Plaid verification, email/SMS notifications
Multi-Language: Unlimited languages with auto-translation

The Hypothesis

We’re testing whether modern cloud primitives can solve problems that plague government tech:

Problem	Hypothesis
Forms break with complex logic	Can JSON trees with Zod validation handle arbitrary nesting?
File uploads leak data	Can strictly private storage with signed URLs prevent exposure?
Enterprise SSO is hard	Can WorkOS reduce integration to configuration?
Slow deployments	Can edge computing and serverless enable same-day launches?

Terra builds on lessons from Tideswell, our production platform powering intake for childcare subsidies, rental assistance, and housing applications. While Tideswell is battle-tested, Terra lets us experiment with newer patterns.

Who This Is For

This documentation is for engineers working on Terra. It covers:

Foundation

Mental models, system architecture, and design philosophy

Core Systems

Deep dives into forms, identity, data storage, and async operations

Features

Form lifecycle, translations, and interpolation

Integrations

Airtable, Google Drive, Plaid, notifications, and form import

Operations

Local setup, security, custom domains, and testing

Quick Links

Core Concepts

The mental models you need before diving into code

System Map

Visual overview of how components connect

Design Philosophy

Why we built it this way

Local Development

Get Terra running on your machine

Design Principles

Applicant Data Is Sacred

Government forms collect SSNs, bank accounts, medical records. Every architectural decision prioritizes data protection. Files are never publicly accessible. Submissions succeed even if integrations fail.

Fail Secure

When something goes wrong, Terra denies access rather than granting it. Unknown roles get minimal permissions. Suspicious paths reject. Decryption failures redirect to login.

Multi-Language by Design

Every user-facing string is an I18nString (locale → text map). Translation isn’t a plugin—it’s in the data model. Forms support unlimited languages with DeepL auto-translation.

White-Label Ready

Agencies customize logos, colors, domains, and email templates. Applicants see their agency’s brand, not ours.

Ready to Dive In?

Start with Core Concepts to understand the mental models, or jump to Local Development to get Terra running.