> ## 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.

# Welcome to Terra

> Engineering documentation for Terra's government intake platform

# 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:

<CardGroup cols={3}>
  <Card title="Form Builder" icon="hammer">
    Visual editor for creating complex, multi-language forms with conditional logic
  </Card>

  <Card title="Applicant Portal" icon="user">
    Public-facing forms and status tracking for applicants
  </Card>

  <Card title="Admin Dashboard" icon="gauge">
    Submission management, analytics, and team collaboration
  </Card>
</CardGroup>

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:

<Steps>
  <Step title="Foundation">
    Mental models, system architecture, and design philosophy
  </Step>

  <Step title="Core Systems">
    Deep dives into forms, identity, data storage, and async operations
  </Step>

  <Step title="Features">
    Form lifecycle, translations, and interpolation
  </Step>

  <Step title="Integrations">
    Airtable, Google Drive, Plaid, notifications, and form import
  </Step>

  <Step title="Operations">
    Local setup, security, custom domains, and testing
  </Step>
</Steps>

***

## Quick Links

<CardGroup cols={2}>
  <Card title="Core Concepts" icon="brain" href="/foundation/core-concepts">
    The mental models you need before diving into code
  </Card>

  <Card title="System Map" icon="diagram-project" href="/foundation/system-map">
    Visual overview of how components connect
  </Card>

  <Card title="Design Philosophy" icon="lightbulb" href="/foundation/design-philosophy">
    Why we built it this way
  </Card>

  <Card title="Local Development" icon="laptop-code" href="/operations/local-development">
    Get Terra running on your machine
  </Card>
</CardGroup>

***

## Design Principles

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="White-Label Ready">
    Agencies customize logos, colors, domains, and email templates. Applicants see their agency's brand, not ours.
  </Accordion>
</AccordionGroup>

***

## Ready to Dive In?

Start with [Core Concepts](/foundation/core-concepts) to understand the mental models, or jump to [Local Development](/operations/local-development) to get Terra running.