Skip to main content

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