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

# Engineering Planning 2026

> Comprehensive capability audit, roadmap analysis, and strategic recommendations

# Engineering Planning 2026

> A deep dive into Terra's current capabilities, gap analysis, and strategic recommendations for the engineering roadmap.

***

## Executive Summary

Terra has achieved **feature parity with Tideswell** and offers significant architectural improvements. The platform is production-ready for application intake with strong foundations in security, multi-tenancy, and integrations.

**Key Decision**: Continue building Terra. The architectural investments (PostgreSQL, Next.js, DAL, audit logging) provide a superior foundation compared to alternatives or continued Tideswell investment.

**Strategic Focus Areas**:

1. Applicant identity unification (cross-program accounts)
2. Income/employment verification integrations
3. Impact dashboards and reporting
4. Payments API integrations

***

## Part 1: Current Capability Audit

### Application Intake (Applicant-Facing)

| Capability               | Status     | Implementation                    |
| ------------------------ | ---------- | --------------------------------- |
| Form builder (drag-drop) | ✅ Complete | `form-builder/`, dnd-kit          |
| Conditional logic        | ✅ Complete | JSON conditions in schema         |
| Multi-language           | ✅ Complete | I18nString + DeepL auto-translate |
| File uploads             | ✅ Complete | Supabase + Google Drive           |
| Anonymous forms          | ✅ Complete | `is_anonymous` flag               |
| Authenticated forms      | ✅ Complete | WorkOS OAuth                      |
| Scheduled publish/close  | ✅ Complete | `published_at`, `closes_at`       |
| Form freezing            | ✅ Complete | Auto-freeze on first submission   |
| ID verification          | ✅ Complete | Plaid Identity                    |
| Bank verification        | ✅ Complete | Plaid Auth                        |
| Address validation       | ✅ Complete | Smarty integration                |
| Status lookup            | ✅ Complete | Reference ID lookup page          |
| Applicant portal         | ✅ Complete | `/portal` with program filtering  |

### Data Processing (Internal)

| Capability             | Status     | Implementation                   |
| ---------------------- | ---------- | -------------------------------- |
| PostgreSQL storage     | ✅ Complete | Supabase hosted                  |
| Field-level encryption | ✅ Complete | `encryptSubmissionPII()`         |
| Soft delete            | ✅ Complete | DAL pattern, 30-day cleanup      |
| Audit logging          | ✅ Complete | 28 action types, 13 entity types |
| Async queue            | ✅ Complete | Database-backed, retry logic     |
| Background worker      | ✅ Complete | Lifecycle + cleanup tasks        |

### Integrations

| Integration      | Status     | Implementation                |
| ---------------- | ---------- | ----------------------------- |
| Airtable sync    | ✅ Complete | Bidirectional, field mapping  |
| Webhooks         | ✅ Complete | HMAC signed, event history    |
| Email (Resend)   | ✅ Complete | React Email templates         |
| SMS (Twilio)     | ✅ Complete | Template system               |
| Google Drive     | ✅ Complete | File uploads to shared drives |
| Plaid (ID/Bank)  | ✅ Complete | Identity + Auth products      |
| Smarty (Address) | ✅ Complete | Autocomplete + validation     |
| Sentry           | ✅ Complete | Error monitoring              |
| PostHog          | ✅ Complete | Product analytics             |

### Fraud Review

| Capability          | Status      | Implementation                    |
| ------------------- | ----------- | --------------------------------- |
| Geolocation capture | ✅ Complete  | IP, country, city, region         |
| User agent tracking | ✅ Complete  | Stored per submission             |
| Duration tracking   | ⚠️ Partial  | Session start/end available       |
| Behavioral signals  | ⚠️ Partial  | Need submission timing analysis   |
| Fraud database      | ❌ Not Built | Need cross-program fraud actor DB |

### Status Tracking (Applicant-Facing)

| Capability            | Status     | Implementation                 |
| --------------------- | ---------- | ------------------------------ |
| Status lookup page    | ✅ Complete | Reference ID + email lookup    |
| Outcome display       | ✅ Complete | `outcome` field on submissions |
| Status page defaults  | ✅ Complete | System-wide + form-level       |
| Multi-language status | ✅ Complete | i18n dictionary                |

### Data & Reporting

| Capability          | Status      | Implementation                |
| ------------------- | ----------- | ----------------------------- |
| Form insights       | ✅ Complete  | Visits, starts, completions   |
| UTM tracking        | ✅ Complete  | Source, medium, campaign      |
| CSV export          | ✅ Complete  | Insights + submissions        |
| Tableau integration | ❌ Not Built | Need data warehouse layer     |
| Impact dashboards   | ❌ Not Built | Need reporting infrastructure |

### Payments

| Capability           | Status      | Implementation |
| -------------------- | ----------- | -------------- |
| Payment collection   | ❌ Not Built | —              |
| Dots.dev integration | ❌ Not Built | —              |
| Recurring payments   | ❌ Not Built | —              |
| Refunds              | ❌ Not Built | —              |

### Customer Support

| Capability         | Status      | Implementation                   |
| ------------------ | ----------- | -------------------------------- |
| In-app chat        | ❌ Not Built | Could integrate Intercom/Zendesk |
| Help center        | ⚠️ Partial  | Support URL per form             |
| Ticket integration | ❌ Not Built | —                                |

***

## Part 2: Roadmap Item Analysis

Based on the product roadmap, here's the gap analysis:

### In-Progress / To-Do Items

| Roadmap Item                         | Terra Status | Effort | Recommendation                              |
| ------------------------------------ | ------------ | ------ | ------------------------------------------- |
| Income + employment verification     | ❌ Not Built  | Medium | **Build**: Integrate Plaid Income or Argyle |
| Tighter customer support integration | ❌ Not Built  | Low    | **Buy**: Integrate Intercom/Zendesk widget  |
| Dots.dev payments integration        | ❌ Not Built  | Medium | **Build**: High strategic value             |
| Impact dashboards + reporting        | ❌ Not Built  | High   | **Build**: Core differentiator              |
| Accessibility enhancements           | ⚠️ Partial   | Medium | **Build**: Incremental improvements         |
| White-labeling support               | ✅ Complete   | —      | Already done (custom domains, branding)     |
| Markdown rendering enhancements      | ⚠️ Partial   | Low    | **Build**: Quick wins                       |

### Current Strengths

| Strength                          | Terra Status | Notes                                  |
| --------------------------------- | ------------ | -------------------------------------- |
| Managing repeat payments          | ❌ Not Built  | Need payments infrastructure first     |
| Fraud mitigation (proprietary DB) | ❌ Not Built  | Need cross-program fraud database      |
| Fraud mitigation (behavioral)     | ⚠️ Partial   | Have geolocation, need timing analysis |

### Opportunities

| Opportunity                        | Terra Status | Strategic Value | Recommendation                                |
| ---------------------------------- | ------------ | --------------- | --------------------------------------------- |
| User management / unified identity | ⚠️ Partial   | High            | **Priority**: Expand applicant identity       |
| Cross-form account persistence     | ⚠️ Partial   | High            | **Priority**: Already have `applicants` table |
| Pre-fill from saved account        | ❌ Not Built  | Medium          | **Build**: Natural extension of identity      |
| Form templates                     | ⚠️ Partial   | Medium          | **Build**: Template library + duplication     |
| Recertification flows              | ❌ Not Built  | High            | **Build**: Required for recurring programs    |

***

## Part 3: Build vs Buy Analysis

### Continue Building Terra ✅ Recommended

**Pros:**

* Full control over features and deployment
* Data ownership and compliance control
* Tideswell parity already achieved
* Modern architecture (PostgreSQL, Next.js, TypeScript)
* DAL provides clean foundation for new features
* Seamless Airtable integration already working
* Cost-effective at scale

**Cons:**

* Small team bandwidth
* Opportunity cost during program launches

**Mitigations:**

* Freeze non-critical features during launches
* Prioritize high-leverage work (identity, payments)
* Use external services where appropriate (support, analytics)

### Switch to Alternative Form Platform ❌ Not Recommended

**Pros:**

* Potentially faster feature delivery
* Larger support team

**Cons:**

* Data migration complexity
* Loss of Airtable integration sophistication
* Loss of fraud detection infrastructure
* Vendor lock-in
* Ongoing licensing costs
* Limited customization for government use cases
* Would need to rebuild ID/bank verification integrations

**Verdict**: The investment in Terra is substantial and the architecture is sound. Switching would lose significant value and require rebuilding integrations.

### Hybrid Approach: Terra + External Services ✅ Recommended

| Function           | Approach          | Service           |
| ------------------ | ----------------- | ----------------- |
| Application intake | Build (Terra)     | —                 |
| Data processing    | Build (Terra)     | —                 |
| Payments           | Build integration | Dots.dev, Stripe  |
| Customer support   | Buy               | Intercom, Zendesk |
| Reporting          | Build + Buy       | Metabase, Tableau |
| Error monitoring   | Buy               | Sentry (done)     |
| Analytics          | Buy               | PostHog (done)    |

***

## Part 4: Strategic Recommendations

### Tier 1: High Priority (Q1 2026)

#### 1. Unified Applicant Identity

**Problem**: Users create new accounts per program, losing their history.

**Solution**: Expand the existing `applicants` table to be a true identity hub.

```typescript theme={null}
// Current: applicants are form-scoped
applicant_id -> linked to submissions

// Target: applicants are org-scoped with profile
applicant {
  id, org_id,
  email, phone, name,
  saved_profile: { address, household_size, income_range },
  verified_fields: { email: true, phone: true, identity: true },
  created_at, last_active_at
}
```

**Scope**:

* Expand applicant profile fields
* Add profile completion percentage
* Pre-fill forms from saved profile
* Single sign-on across programs (same org)

**Effort**: 2-3 weeks

#### 2. Income/Employment Verification

**Problem**: Manual income verification is time-consuming and fraud-prone.

**Solution**: Integrate Plaid Income or Argyle for instant verification.

**Scope**:

* Add `income_verification` field type
* Store verification results
* Display verified income in review

**Effort**: 2-3 weeks

#### 3. Recertification Flows

**Problem**: Recurring programs need periodic re-verification.

**Solution**: Submission continuation with pre-filled data.

**Scope**:

* Add `parent_submission_id` for continuation
* Pre-fill from previous submission
* Track recertification schedule
* Send reminder notifications

**Effort**: 2-3 weeks

### Tier 2: Medium Priority (Q2 2026)

#### 4. Payments Integration (Dots.dev)

**Problem**: Payment disbursement is manual.

**Solution**: Integrate Dots.dev for programmatic payments.

**Scope**:

* Payment configuration per form
* Disbursement triggers (on approval, scheduled)
* Payment status tracking
* Refund handling

**Effort**: 3-4 weeks

#### 5. Fraud Database

**Problem**: Fraud actors observed in one program aren't flagged in others.

**Solution**: Cross-program fraud signal database.

**Scope**:

* Fraud signal collection (IP, device, behavioral)
* Cross-program matching
* Risk score calculation
* Admin review interface

**Effort**: 4-6 weeks

#### 6. Impact Dashboards

**Problem**: No unified view of program impact.

**Solution**: Embedded analytics with key metrics.

**Scope**:

* Submission funnel metrics
* Geographic distribution
* Demographic breakdowns
* Outcome tracking
* Exportable reports

**Effort**: 4-6 weeks

### Tier 3: Lower Priority (Q3+ 2026)

#### 7. Customer Support Integration

**Solution**: Embed Intercom or Zendesk widget with submission context.

**Effort**: 1 week

#### 8. Text-Based Form Editing

**Problem**: UI form building is slow for power users.

**Solution**: Import/export JSON schema with validation.

**Scope**:

* JSON schema editor in UI
* Validation on import
* Version diffing

**Effort**: 1-2 weeks

#### 9. Accessibility Audit

**Solution**: WCAG 2.1 AA compliance audit and fixes.

**Effort**: 2-3 weeks (ongoing)

***

## Part 5: Architecture Decisions

### Keep Text-Based Form Export?

**Recommendation**: Yes, add JSON export/import.

Currently forms are only editable via UI. Adding a JSON export/import capability would:

* Speed up power user workflows
* Enable form versioning via git
* Allow programmatic form creation

```typescript theme={null}
// Export format (already similar to current schema)
{
  "version": "1.0",
  "title": { "en": "Rental Assistance" },
  "elements": [
    { "type": "text", "id": "name", "label": { "en": "Full Name" } },
    // ...
  ]
}
```

**Effort**: 1 week

### Form-Input Only vs Applicant Management?

**Recommendation**: Move toward applicant management.

Terra already has the foundation:

* `applicants` table exists
* Submissions link to applicants
* Portal shows all submissions per applicant

**Next steps**:

1. Expand applicant profile (contact info, documents)
2. Add profile editing UI
3. Pre-fill forms from profile
4. Single account across org's programs

This aligns with "making logins relevant across more of the pipeline."

### Tideswell vs Terra?

**Recommendation**: Terra is the path forward.

| Factor          | Tideswell         | Terra                | Winner |
| --------------- | ----------------- | -------------------- | ------ |
| Architecture    | MongoDB + Express | PostgreSQL + Next.js | Terra  |
| Type safety     | JavaScript        | TypeScript           | Terra  |
| Auth            | Custom            | WorkOS               | Terra  |
| Audit logging   | Manual            | Automatic (DAL)      | Terra  |
| Soft delete     | Manual            | Built-in             | Terra  |
| Integrations    | Legacy            | Modern               | Terra  |
| Maintainability | Technical debt    | Clean slate          | Terra  |

Terra should be the primary development focus. Tideswell can remain operational for existing deployments but shouldn't receive new features.

***

## Part 6: Proposed Roadmap

```mermaid theme={null}
gantt
    title Terra Engineering Roadmap 2026
    dateFormat  YYYY-MM
    section Q1 2026
    Unified Applicant Identity    :2026-01, 3w
    Income Verification           :2026-01, 3w
    Recertification Flows         :2026-02, 3w
    section Q2 2026
    Payments (Dots.dev)           :2026-04, 4w
    Fraud Database                :2026-05, 5w
    section Q3 2026
    Impact Dashboards             :2026-07, 5w
    Support Integration           :2026-08, 1w
    Accessibility Audit           :2026-08, 3w
    section Ongoing
    Program Launches              :2026-01, 12m
    Bug Fixes + Maintenance       :2026-01, 12m
```

### Quarterly Breakdown

**Q1 2026: Identity & Verification**

* Unified applicant identity (3w)
* Income/employment verification (3w)
* Recertification flows (3w)
* Buffer for program launches

**Q2 2026: Payments & Fraud**

* Dots.dev payments integration (4w)
* Cross-program fraud database (5w)
* Buffer for program launches

**Q3 2026: Reporting & Polish**

* Impact dashboards (5w)
* Support integration (1w)
* Accessibility audit (3w)

***

## Part 7: Quick Wins

These can be done in 1-2 days each:

1. **JSON form export** - Download form schema as JSON
2. **Markdown image sizing** - Add width/height to info fields
3. **Text color in markdown** - Support `<span style="color:red">`
4. **Remove "create new account" messaging** - Encourage single account
5. **Form templates library** - Curated starting points
6. **Bulk status update** - Update multiple submissions at once
7. **Keyboard shortcuts** - Form builder productivity

***

## Appendix: Current Tech Stack

| Layer      | Technology                      | Purpose                   |
| ---------- | ------------------------------- | ------------------------- |
| Framework  | Next.js 15                      | Full-stack React          |
| Database   | PostgreSQL (Supabase)           | Primary data store        |
| Auth       | WorkOS                          | SSO, MFA, user management |
| Storage    | Supabase Storage + Google Drive | File uploads              |
| Email      | Resend + React Email            | Transactional email       |
| SMS        | Twilio                          | Text notifications        |
| Payments   | — (planned: Dots.dev)           | Disbursements             |
| Analytics  | PostHog                         | Product analytics         |
| Monitoring | Sentry                          | Error tracking            |
| Queue      | PostgreSQL table                | Async operations          |
| Hosting    | Vercel                          | Edge deployment           |

***

## Appendix: Database Tables (35 total)

### Core

* `forms` - Form definitions
* `submissions` - Application data
* `applicants` - Applicant identity

### Identity

* `users` - Admin users (via WorkOS)
* `program_members` - Form-level access
* `agencies` - Multi-tenancy

### Workflow

* `form_sessions` - Draft progress
* `form_versions` - Schema history
* `audit_logs` - Change tracking

### Integrations

* `airtable_connections` - Sync config
* `webhook_configs` - Webhook settings
* `webhook_events` - Delivery history
* `notification_events` - Email/SMS history
* `notification_providers` - Provider config
* `notification_templates` - Message templates

### Async

* `async_operations` - Job queue

***

<Card title="Tideswell Comparison" icon="code-compare" href="/foundation/tideswell-comparison">
  How Terra relates to Tideswell
</Card>