AGEI

System Architecture

Technical design and infrastructure overview

Technology Stack

Backend

  • • PostgreSQL 15
  • • Supabase Cloud
  • • Next.js 14 API Routes
  • • pgcrypto (SHA-256)

Frontend

  • • Next.js 14 App Router
  • • TypeScript (strict)
  • • Tailwind CSS
  • • shadcn/ui components

Integrations

  • • SendGrid (email)
  • • Supabase Auth
  • • Python SDK
  • • REST API

Database Architecture

Core Tables (14 Migrations)

001
Core organizational structure
002
Policy gates and evaluation
003
Cryptographic receipts
004
Audit vault storage
005
Row-level security
013
HITL governance
014
Agent behavior monitoring

Key Design Patterns

Immutability

Receipts and decisions cannot be modified after creation

Multi-Tenancy

Organization-level isolation with RLS policies

Event Sourcing

Complete audit trail through chained receipts

JSONB Flexibility

Schema-less evidence payloads for adaptability

Evidence Flow

Complete lineage from data to deployment

1
Dataset Receipt

Training data ingestion with hash

2
Training Receipt

Model training evidence and metrics

3
Validation Gate

Policy evaluation (accuracy, bias checks)

4
Deployment Gate

Production deployment approval

5
Inference Requests

Runtime prediction tracking

6
Vault Archive

Sealed evidence with signatures

Security Model

Row-Level Security (RLS)

PostgreSQL RLS enforces multi-tenant isolation at the database level. Users can only access data from their organization.

CREATE POLICY org_isolation ON receipts
USING (organization_id = current_organization_id())

Service Role Isolation

API routes use service role key to bypass RLS for server-side operations. Clients use anon key with RLS enforcement.

Anon Key
Client-side, RLS enforced
Service Key
Server-side, RLS bypass

Token Security

HITL approval tokens are SHA-256 hashed before storage. Only hash is stored, plain token sent via email link.

  • • 64-character hex strings (32 random bytes)
  • • Constant-time comparison for validation
  • • Limited use count (10 for review page)
  • • Time-based expiration (SLA-driven)

Cryptographic Hashing

All evidence payloads are SHA-256 hashed for tamper detection. Hash chains link receipts to parent evidence.

  • • SHA-256 content hashing
  • • Optional digital signatures
  • • Merkle tree batch proofs
  • • Hash chain verification

API Architecture

Next.js 14 API Routes with service client

Endpoint Structure

All API routes follow RESTful conventions under /api/v1/*

/api/v1/gates/evaluate - Policy gate evaluation
/api/v1/hitl/request - Create HITL request
/api/v1/agents/sessions - Agent session management
/api/v1/agent-security/alerts - Anomaly alerts

Service Client Pattern

API routes use createServiceClient() with service role key to bypass RLS and perform server-side validation.

Scalability Considerations

Horizontal Scaling

  • • Stateless Next.js API routes
  • • PostgreSQL connection pooling
  • • Edge caching for static assets

Database Optimization

  • • Indexed foreign keys
  • • JSONB GIN indexes
  • • Partitioning for receipts (future)

Async Processing

  • • SendGrid email queue
  • • Background anomaly detection
  • • Batch audit pack generation

Monitoring

  • • Supabase dashboard metrics
  • • API response time tracking
  • • Database query performance