Skip to content

Latest commit

 

History

History
84 lines (67 loc) · 4.61 KB

architecture.md

File metadata and controls

84 lines (67 loc) · 4.61 KB

System Architecture

Origin AI is an AI text detection and provenance platform. It combines edge server-side rendering with server-isolated streaming inference to provide passage analysis without exposing API keys or infrastructure secrets to client browsers.

Architecture Diagram

+------------------------------------------------------------------------+
|                             Client Browser                             |
|  - React 19 / TanStack Router                                          |
|  - Radix UI Component Library                                          |
|  - Browser Guest Token (Random 256-bit entropy stored in localStorage) |
+------------------------------------+-----------------------------------+
                                     |
                         HTTPS / SSE | Server Functions (RPC)
                                     v
+------------------------------------------------------------------------+
|                       TanStack Start / Nitro Edge                      |
|  - Cloudflare Workers / Node Runtime                                   |
|  - Request IP Hashing (SHA-256 for quota tracking)                     |
|  - Guest Token Hashing (SHA-256 salt + token)                          |
+------------------+----------------------------------+------------------+
                   |                                  |
                   v                                  v
+------------------------------------+   +-------------------------------+
|         AI Gateway Engine          |   |       Supabase Database       |
|  - Streaming Responses API         |   |  - scans table                |
|  - Chunk parser & validation       |   |  - scan_quota_claims table    |
|  - Likelihood & Signal Aggregator  |   |  - assets table               |
+------------------------------------+   +---------------+---------------+
                                                         |
                                                         v
                                         +-------------------------------+
                                         |    Private Supabase Storage   |
                                         |  - origin-assets bucket       |
                                         |  - 7-day retention policy     |
                                         |  - Daily cron cleanup worker  |
                                         +-------------------------------+

Core Architectural Pillars

1. Edge Server-Side Rendering

The frontend runs on TanStack Start powered by Nitro. This architecture supports:

  • Full server-side rendering for search indexability and instant page loads.
  • Client-side navigation via TanStack Router with type-safe routing.
  • Direct invocation of server functions through type-safe RPC boundaries.

2. Server-Isolated AI Gateway Streaming

All text analysis requests execute through the analyzeText server function:

  • Client browsers never hold AI Gateway API credentials.
  • Input text is streamed directly to the AI Gateway Responses API.
  • SSE responses are parsed, validated using Zod schemas, and structured into:
    • Overall AI likelihood score (0 to 100).
    • Confidence rating (high, moderate, low).
    • Categorized passage segments with individual reasoning.
    • Multi-dimensional signal markers (perplexity, burstiness, syntax uniformity).
  • Completed scans are persisted to PostgreSQL before the response completes.

3. Identity and Authorization Model

Origin AI supports both authenticated users and anonymous guest visitors:

  • Authenticated Users: Access scans linked directly to their Supabase user_id.
  • Guest Visitors: A random 256-bit token is generated on the client and stored in localStorage.
  • The server computes SHA-256('guest:' + guestToken) and stores only the hash in guest_token_hash.
  • Raw guest tokens are never stored in the database.
  • Direct table access is blocked; all queries run through the administrative server client after explicit ownership checks.

4. Abuse Prevention and Quota Enforcement

  • Quotas are calculated server-side in src/lib/scans.server.ts.
  • Guest quotas limit scans by hashing the client IP address (ip_hash) and checking the 24-hour sliding window in scan_quota_claims.
  • Authenticated accounts receive tier-based scan allocations tracked by user_id.

5. Ephemeral Asset Storage

  • Uploaded files are placed in the private origin-assets Supabase Storage bucket.
  • Uploads are recorded in the database with an exact 7-day expiration timestamp.
  • A scheduled cron job calls cleanupExpiredAssets() using a server-only credential to prune expired records and object storage binaries.