Docs

Architecture

Hosted read-only API plus optional local CLI.

One sentence: the hosted API returns data, the local CLI does the risky work. The split is deliberate and enforced in code review.

Components

┌────────────────────────────────────────────────────────────┐
│  Client (browser, AI agent, curl)                          │
└────────────┬───────────────────────────────────┬───────────┘
             │ x-nipcode-api-key                 │ session cookie
             ▼                                   ▼
┌────────────────────────────┐      ┌────────────────────────┐
│  Hosted API (Vercel)       │      │  Account UI            │
│  /api/search   /decision   │      │  /  /docs              │
│  /api/inspect  /install-plan│      │  /account             │
│  /api/auth*    /sign-out    │      │  /account/keys        │
└──────────┬──────────┬──────┘      └────────────────────────┘
           │          │
           ▼          ▼
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ Source          │ │ LLM (decision)  │ │ Supabase        │
│ registries      │ │                 │ │ Auth + Postgres │
│ npm, pypi,      │ │                 │ │ accounts        │
│ crates, github  │ │                 │ │ api_keys        │
│                 │ │                 │ │ api_usage       │
└─────────────────┘ └─────────────────┘ └─────────────────┘

Hard rules

  • Hosted API is read-only. Pull requests that add child_process, git clone, or package install commands inside api/ are rejected on review.
  • Local CLI is the only surface that touches the workspace. It requires explicit --target-confirmed or equivalent flags.
  • Package metadata is treated as untrusted data, never as agent instructions.
  • Rate limits are per-key, enforced by middleware on every /api/* handler.
  • Supabase row-level security gates every read against auth.uid(); service-role bypass is server-side only.

Persistence

Three tables in the public schema:

  • accounts. One row per signed-in user; mirrors auth.users
  • api_keys. One or many keys per account; RLS by account_id; primary key auto-minted by trigger on signup
  • api_usage. Fire-and-forget usage log; powers rate-limit window and account-scoped usage stats

Search queries and decision responses are not stored.