# xecipher/gemprism architecture

> Architecture diagram of the GitHub repository xecipher/gemprism, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/xecipher/gemprism
- Repository: https://github.com/xecipher/gemprism

## Overview

GemPrism is a Gemini API gateway that authenticates a gateway token, resolves model aliases and limits, selects a healthy least-loaded API key, forwards requests, retries eligible failures, and records usage. Users sign in and manage keys and monitor health and per-model usage through the dashboard. The proxy excerpt is partial, so the routing and persistence stages follow the documented flow; unshown dashboard behavior is represented only where the supplied excerpt supports it.

Main entry points: [`src/lib/supabaseAdmin.ts`](https://github.com/xecipher/gemprism/blob/main/src/lib/supabaseAdmin.ts) (Admin client), [`src/app/api/proxy/[...path]/route.ts`](https://github.com/xecipher/gemprism/blob/main/src/app/api/proxy/%5B...path%5D/route.ts) (Edge proxy handler), [`src/lib/supabase.ts`](https://github.com/xecipher/gemprism/blob/main/src/lib/supabase.ts) (Supabase client), [`src/app/dashboard/page.tsx`](https://github.com/xecipher/gemprism/blob/main/src/app/dashboard/page.tsx) (Key and usage dashboard)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_gateway["Gateway routing"]
  node_proxy["Edge proxy handler<br/>[route.ts]"]
  node_model["Model aliases and limits<br/>[modelLimits.ts]"]
  node_keyrouting["Key selection and retries<br/>[route.ts]"]
end

subgraph group_account["Accounts and dashboard"]
  node_login["Sign in and signup<br/>[page.tsx]"]
  node_dashboard["Key and usage dashboard<br/>[page.tsx]"]
  node_stats["Admin stats endpoint<br/>[route.ts]"]
  node_landing["Product landing page<br/>[page.tsx]"]
end

subgraph group_state["Configuration and state"]
  node_supabaseclient["Supabase client<br/>[supabase.ts]"]
  node_supabaseadmin["Admin client<br/>[supabaseAdmin.ts]"]
  node_database[("Gateway and usage tables")]
  node_keepalive["Keepalive endpoint<br/>[route.ts]"]
end

node_app(("SDK client app"))
node_gemini["Gemini API"]
node_supabaseauth["Supabase Auth"]

node_app -->|"sends request"| node_proxy
node_proxy -->|"resolves token"| node_supabaseadmin
node_supabaseadmin -->|"reads token"| node_database
node_proxy -->|"normalizes model"| node_model
node_proxy -->|"loads keys and usage"| node_supabaseadmin
node_supabaseadmin -->|"reads pool state"| node_database
node_proxy -->|"routes and retries"| node_keyrouting
node_keyrouting -->|"forwards request"| node_gemini
node_keyrouting -->|"updates key state"| node_supabaseadmin
node_keyrouting -->|"records usage"| node_supabaseadmin
node_supabaseadmin -->|"writes state"| node_database
node_login -->|"authenticates"| node_supabaseclient
node_supabaseclient -->|"signs in users"| node_supabaseauth
node_dashboard -->|"manages keys"| node_supabaseclient
node_dashboard -->|"fetches telemetry"| node_stats
node_stats -->|"loads dashboard data"| node_supabaseadmin
node_supabaseadmin -->|"reads and creates token"| node_database
node_keepalive -->|"checks activity"| node_supabaseclient
node_supabaseclient -->|"queries key table"| node_database
node_landing -.->|"shows integration"| node_app

click node_proxy "https://github.com/xecipher/gemprism/blob/main/src/app/api/proxy/%5B...path%5D/route.ts"
click node_model "https://github.com/xecipher/gemprism/blob/main/src/lib/modelLimits.ts"
click node_keyrouting "https://github.com/xecipher/gemprism/blob/main/src/app/api/proxy/%5B...path%5D/route.ts"
click node_login "https://github.com/xecipher/gemprism/blob/main/src/app/login/page.tsx"
click node_dashboard "https://github.com/xecipher/gemprism/blob/main/src/app/dashboard/page.tsx"
click node_stats "https://github.com/xecipher/gemprism/blob/main/src/app/api/admin/stats/route.ts"
click node_supabaseclient "https://github.com/xecipher/gemprism/blob/main/src/lib/supabase.ts"
click node_supabaseadmin "https://github.com/xecipher/gemprism/blob/main/src/lib/supabaseAdmin.ts"
click node_keepalive "https://github.com/xecipher/gemprism/blob/main/src/app/api/keepalive/route.ts"
click node_landing "https://github.com/xecipher/gemprism/blob/main/src/app/page.tsx"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_proxy,node_model,node_keyrouting,node_app toneBlue
class node_login,node_dashboard,node_stats,node_landing toneAmber
class node_supabaseclient,node_supabaseadmin,node_database,node_keepalive,node_gemini toneMint
class node_supabaseauth toneIndigo
```

## Components

### Gateway routing

- [Edge proxy handler](https://github.com/xecipher/gemprism/blob/main/src/app/api/proxy/%5B...path%5D/route.ts): `src/app/api/proxy/[...path]/route.ts`
- [Model aliases and limits](https://github.com/xecipher/gemprism/blob/main/src/lib/modelLimits.ts): `src/lib/modelLimits.ts`
- [Key selection and retries](https://github.com/xecipher/gemprism/blob/main/src/app/api/proxy/%5B...path%5D/route.ts): `src/app/api/proxy/[...path]/route.ts`

### Accounts and dashboard

- [Sign in and signup](https://github.com/xecipher/gemprism/blob/main/src/app/login/page.tsx): `src/app/login/page.tsx`
- [Key and usage dashboard](https://github.com/xecipher/gemprism/blob/main/src/app/dashboard/page.tsx): `src/app/dashboard/page.tsx`
- [Admin stats endpoint](https://github.com/xecipher/gemprism/blob/main/src/app/api/admin/stats/route.ts): `src/app/api/admin/stats/route.ts`
- [Product landing page](https://github.com/xecipher/gemprism/blob/main/src/app/page.tsx): `src/app/page.tsx`

### Configuration and state

- [Supabase client](https://github.com/xecipher/gemprism/blob/main/src/lib/supabase.ts): `src/lib/supabase.ts`
- [Admin client](https://github.com/xecipher/gemprism/blob/main/src/lib/supabaseAdmin.ts): `src/lib/supabaseAdmin.ts`
- **Gateway and usage tables**
- [Keepalive endpoint](https://github.com/xecipher/gemprism/blob/main/src/app/api/keepalive/route.ts): `src/app/api/keepalive/route.ts`

### Other components

- **SDK client app**
- **Gemini API**
- **Supabase Auth**

## Connections

- SDK client app → Edge proxy handler: sends request
- Edge proxy handler → Admin client: resolves token
- Admin client → Gateway and usage tables: reads token
- Edge proxy handler → Model aliases and limits: normalizes model
- Edge proxy handler → Admin client: loads keys and usage
- Admin client → Gateway and usage tables: reads pool state
- Edge proxy handler → Key selection and retries: routes and retries
- Key selection and retries → Gemini API: forwards request
- Key selection and retries → Admin client: updates key state
- Key selection and retries → Admin client: records usage
- Admin client → Gateway and usage tables: writes state
- Sign in and signup → Supabase client: authenticates
- Supabase client → Supabase Auth: signs in users
- Key and usage dashboard → Supabase client: manages keys
- Key and usage dashboard → Admin stats endpoint: fetches telemetry
- Admin stats endpoint → Admin client: loads dashboard data
- Admin client → Gateway and usage tables: reads and creates token
- Keepalive endpoint → Supabase client: checks activity
- Supabase client → Gateway and usage tables: queries key table
- Product landing page → SDK client app: shows integration