System Overview

Status: Canonical (Draft) Last Updated: 2026-02-06 Owner: Engineering

Purpose

This document provides a high-level architectural overview of the CAIRL system.

It is intended to:

  • Orient engineers, auditors, and AI agents
  • Explain major system boundaries and responsibilities
  • Clarify how core subsystems interact
  • Provide context for deeper specs, contracts, and flows

This document is descriptive, not prescriptive. Detailed rules are defined in contracts and specifications.

System Goals

CAIRL is designed to:

  • Handle sensitive and regulated data (HIPAA)
  • Enforce strict authorization and isolation
  • Scale across consumer and B2B use cases
  • Protect shared infrastructure and reputation
  • Support auditability and compliance (HIPAA, SOC 2)

High-Level Architecture

CAIRL is a web-based platform built on a modern server-rendered stack with strong database-level enforcement and external provider integrations.

Core Stack

  • Frontend / Application Layer

    • Next.js (App Router)
    • Server Components, Server Actions, Route Handlers
    • Client components for interactive UI only

  • Authentication

    • NextAuth
    • Session-based authentication
    • Identity mapped to Postgres UUIDs

  • Database

    • Supabase Postgres
    • Row Level Security (RLS) as primary enforcement layer
    • Service-role access restricted to server contexts

  • Object Storage

    • AWS S3
    • Private buckets with signed URL access
    • Lifecycle policies aligned with retention contracts

  • External Providers

    • Email (proxy + transactional)
    • Phone (Twilio)
    • Payments and billing (Stripe)
    • Identity and verification services
    • Partner B2B integrations

Major System Boundaries

Client Boundary

  • Runs in the user’s browser
  • Never holds secrets
  • Never bypasses authorization
  • UI gating is non-authoritative

Application Server Boundary

  • Executes Next.js server logic
  • Enforces authorization checks
  • Orchestrates provider calls
  • Acts as the sole holder of privileged credentials

Database Boundary

  • Supabase Postgres enforces RLS
  • Database is the final authority for data access
  • All sensitive data is protected at this layer

Provider Boundary

  • External services enforce their own limits
  • CAIRL applies stricter internal controls
  • Provider failures are isolated and handled defensively

Core Subsystems

Identity and Authorization

  • User identity established via NextAuth
  • Authorization enforced via:
    • Server-side checks
    • Postgres RLS policies
  • Admin access is explicit and scoped

Data Storage and Retention

  • User-owned and compliance-regulated data stored in Postgres and S3
  • Retention governed by explicit contracts
  • Deletion, anonymization, and retention are distinct operations
  • HIPAA and audit requirements override user deletion

Rate Limiting and Abuse Prevention

  • Multi-layer rate limiting
  • Infrastructure safety limits (email, phone)
  • Abuse guardrails for user and partner actions
  • Enforcement precedence favors safety and compliance

Messaging and Communication

  • Proxy email systems protect user privacy and sender reputation
  • Transactional messaging isolated from proxy systems
  • Phone features protected by fraud guardrails
  • Communication systems treated as high-risk infrastructure

Partner and B2B Integrations

  • Partner APIs protected by deduplication and guardrails
  • Billing events carefully controlled
  • Test modes provided to prevent accidental charges
  • Partner behavior monitored and logged

Observability and Auditability

  • All critical actions are logged
  • Access to regulated data is auditable
  • Enforcement actions are traceable
  • Logs retained per compliance requirements

Detailed observability requirements are defined separately.

Failure and Safety Posture

CAIRL follows a fail-safe design philosophy:

  • Authorization failures fail closed
  • RLS misconfiguration blocks access
  • Provider outages degrade gracefully
  • Abuse triggers protective shutdowns where required

Relationship to Other Documentation

This overview is supported by:

  • Governance documents (how docs work)
  • Contracts (non-negotiable rules)
  • Specifications (feature behavior)
  • User flows (page-by-page experience)
  • Runbooks (operational response)

This document does not override any contract.

References

  • docs/governance/doc-authority.new.md
  • docs/contracts/authz-and-roles.new.md
  • docs/contracts/data-retention.new.md
  • docs/contracts/rate-limits-and-abuse.new.md
  • docs/contracts/rls-standard.new.md

End of Document