This document describes the HAIEC platform architecture, data flows, trust boundaries, and encryption zones. It is written for security reviewers and enterprise procurement teams.

1. Architecture Overview

HAIEC is a serverless Next.js 14 application deployed on Vercel. The platform consists of:

Application layer: Next.js 14 App Router on Vercel (serverless functions, edge network)
Database: Neon (serverless PostgreSQL, US-East region)
Scan execution: Modal (ephemeral containers for source code analysis)
Rate limiting & caching: Upstash Redis
Error monitoring: Sentry
Payments: Stripe (PCI DSS Level 1)
Transactional email: Resend
Source integration: GitHub App (installation-scoped tokens)

All providers are US-based and SOC 2 Type II certified (or PCI DSS for Stripe). See Subprocessor List for details.

2. Data Flow

Standard request flow

User → Vercel Edge (TLS 1.2+) → Next.js API Route → Prisma ORM → Neon (PostgreSQL)
                                         ↓
                                    Upstash Redis (rate limit check)

Static scan flow

User → API Route → Modal (ephemeral container)
                         ↓
                    Clone repo in-memory
                         ↓
                    Run rule-based analysis
                         ↓
                    Return findings only (no source code)
                         ↓
                    Container destroyed → Findings → Neon (PostgreSQL)

Email flow

API Route → Resend → User email (receipts, scan notifications)

Payment flow

User → Stripe Checkout (PCI DSS Level 1) → Stripe Webhook → API Route → Neon
(HAIEC never sees or stores card details)

3. Trust Boundaries

Boundary	Authentication	Encryption
Internet → Vercel Edge	None (public)	TLS 1.2+
Vercel → Neon (PostgreSQL)	Connection string + SSL	TLS 1.2+
Vercel → Modal	API key	TLS 1.2+
Vercel → Upstash Redis	Redis auth token	TLS 1.2+
Vercel → GitHub API	OAuth token / App installation token	TLS 1.2+
Vercel → Stripe	Stripe secret key	TLS 1.2+
Vercel → Resend	Resend API key	TLS 1.2+
Vercel → Sentry	Sentry DSN	TLS 1.2+

4. Encryption Zones

Zone 1: In transit

TLS 1.2+ enforced on all connections (TLS 1.3 preferred where supported)
HTTPS-only; HTTP requests redirected
HSTS headers applied via next.config.js (max-age=63072000; includeSubDomains; preload)

Zone 2: At rest

AES-256 encryption via Neon (PostgreSQL provider-managed)
SHA-256 content hashing for evidence integrity verification
SHA-256 hashing of NYC LL144 candidate identifiers before storage

Zone 3: Application layer

Sensitive wizard data encrypted client-side before localStorage persistence
API keys stored as SHA-256 hashes (plaintext shown only once at creation)
OAuth tokens (GitHub, Google) persisted in accounts table via NextAuth Prisma adapter. GitHub access token also stored in users.githubAccessToken for App integration.

5. Authentication Flow

User authentication

User → GitHub/Google OAuth 2.0 → NextAuth.js → Server-side session (HttpOnly cookie)
                                         ↓
                                    Prisma adapter → Neon (users, accounts, sessions tables)

API authentication (browser)

Browser → Session cookie → NextAuth getSession() → Organization context check

API authentication (CI/CD integrations)

Client → X-API-Key header or Bearer token → validateApiKey() → HMAC-SHA256 signature verification

6. Tenant Isolation Boundaries

HAIEC enforces tenant isolation through three layers of authorization:

requireOrganizationAccess() — Used by 49 API routes. Verifies authenticated session, resolves organization ID from multiple sources, checks active membership in organization_members table, and returns a verified organizationId for query scoping.
validateTenantContext() — Requires explicit X-Organization-Id header. Validates organization existence, checks user membership and permissions, and returns a TenantContext with role-based permissions.
requirePermission() — Fine-grained RBAC for kill-switch and compliance-twin operations. Checks specific permissions like canEditAssessments, canManageBilling, canViewEvidence.

See Access Controls for the full RBAC model.

System Architecture