Skip to main content

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.

​
System Map

A bird’s-eye view of how Terra’s components connect.
This page provides visual maps of Terra’s architecture. Use it as a reference when navigating the codebase or debugging data flow issues.

​
High-Level Architecture

Terra follows a layered architecture with clear boundaries between concerns:

​
Request Flow

Every request follows a consistent path through the system:

​
Key Decision Points

StepDecisionFail Behavior
MiddlewareValid session?Redirect to login
MiddlewareCustom domain?Route to correct folder
Server ActionHas permission?Throw unauthorized
DatabaseRLS policiesN/A (using service role)

​
Form Submission Flow

When an applicant submits a form, here’s what happens:

​
Timing

StepTypical DurationBlocking?
Client validation50-100msYes
Server save100-200msYes
Queue enqueue10-20msYes
User sees success~300ms total—
Airtable sync500ms-2sNo
Email send200-500msNo
Webhook fire100-500msNo
The applicant sees “Thank you” in ~300ms. Everything else happens in the background.

​
Authentication Flow

How users authenticate and how sessions are managed:

​
Session Management

​
Data Model Overview

The core database entities and their relationships: For complete schema documentation, see Database Schema.

​
File Upload Flow

How files move from the applicant’s browser to secure storage:

​
Storage Paths

Files are stored with unpredictable paths to prevent enumeration: 
form-uploads/
  {formId}/
    {uuid}/
      {sanitized-filename}

​
Async Queue Architecture

The persistent queue that powers background processing:

​
Operation Types

TypeTriggerRetry Strategy
airtable_syncSubmission/update5 retries, exponential backoff
send_emailSubmission3 retries, 1 min delay
send_smsSubmission/status change3 retries, 1 min delay
fire_webhookSubmission/status change5 retries, exponential backoff
plaid_enrichmentPlaid link complete3 retries, 30s delay

​
Directory Structure

Where to find things in the codebase: 
apps/terra/src/
├── app/                    # Next.js App Router
│   ├── (dashboard)/        # Admin routes (protected)
│   ├── (portal)/           # Applicant portal routes
│   ├── (public)/           # Public routes
│   ├── actions/            # Server actions (25 files)
│   ├── api/                # API routes (webhooks, uploads)
│   ├── auth/               # Auth callback routes
│   ├── f/[slug]/           # Public form renderer
│   └── p/[slug]/           # Portal program page
│
├── components/             # React components
│   ├── engine/             # Form field renderers
│   ├── form-builder/       # Visual editor
│   ├── dashboard/          # Admin UI
│   ├── portal/             # Applicant UI
│   └── emails/             # React Email templates
│
├── lib/                    # Business logic
│   ├── auth.ts             # Session management
│   ├── supabase.ts         # Database clients
│   ├── security.ts         # Security utilities
│   ├── async-queue.ts      # Queue operations
│   ├── logic-engine.ts     # Form visibility rules
│   └── form-import/        # AI import pipeline
│
├── stores/                 # Zustand stores
│   └── form-builder-store.ts
│
├── types/                  # TypeScript types
│   └── schema.ts           # Form schema (478 lines)
│
└── middleware.ts           # Edge middleware

​
Next Steps

Design Philosophy

Why we made these architectural choices

Database Schema

Complete table documentation