Skip to main content

​
Architecture

Igris is a monorepo with two primary services, a shared database, and a Redis cache layer.

​
System Overview

​
Components

​
API Server (Hono)

The backend runs on Hono and listens on port 3100. It handles:
  • Proxy routes (/proxy/:serverId) — intercept MCP tool calls, evaluate policies, forward to upstream
  • REST API (/api/v1/*) — CRUD for policies, servers, sessions, audit events, compliance, billing
  • Auth (/api/auth/*) — Better Auth endpoints for session management
  • SSE (/api/v1/events) — real-time event stream for dashboard updates
  • Ingestion (/api/v1/ingest/*) — webhook receivers for external log providers

​
Web Frontend (Next.js)

The dashboard runs on Next.js on port 3200 and provides:
  • Governance management (servers, policies, sessions)
  • Real-time observe dashboard with risk heat maps
  • Compliance artifact generation and download
  • Organization settings, member management, billing

​
Database (Neon PostgreSQL)

All persistent state lives in Neon PostgreSQL. The schema is managed by Drizzle ORM with auto-migrations on startup. Key tables:
TablePurpose
user, account, sessionBetter Auth identity
organization, memberMulti-tenancy
mcp_serversRegistered MCP server configs
policiesGovernance rules per server
agent_sessionsActive proxy sessions
audit_eventsUnified audit trail (proxy + ingested)
baaHIPAA BAA records
ai_systemsEU AI Act system registry

​
Cache (Upstash Redis)

Upstash Redis handles:
  • Policy cache — hot policies cached with TTL to avoid DB lookups on every tool call
  • Rate limiting — sliding window counters for rate-limit policy rules
  • SSE pub/sub — event fan-out to connected dashboard clients
  • Session state — fast lookup for kill-switch status

​
Authentication (Better Auth)

Better Auth provides:
  • Email/password and OAuth (GitHub, Google) login
  • Organization-scoped sessions with RBAC
  • API key generation for programmatic access (proxy, ingestion)
  • Session tokens stored as igris.session_token cookies

​
Proxy Flow

When an MCP client calls a tool through the Igris proxy:
  1. Request arrives at /proxy/:serverId with the tool name and arguments
  2. Auth check — validate API key or session cookie
  3. Org resolution — determine which organization owns this server
  4. Policy evaluation — load rules from cache (or DB on cache miss), evaluate first-match against the tool name
  5. Action execution:
    • allow → forward to upstream, log the event
    • deny → return error to client, log the denial
    • alert → forward to upstream, log + emit anomaly event via SSE
  6. Anomaly check — evaluate rate spike and destructive pattern detectors
  7. Audit write — persist the event to audit_events with timing, result, and metadata
  8. SSE broadcast — push real-time event to connected dashboard clients

​
Deployment

Igris is designed to deploy on Fly.io with:
  • Single Dockerfile for the API server
  • Separate Fly app for the Next.js frontend (or Vercel)
  • Neon for managed PostgreSQL (serverless, auto-scaling)
  • Upstash for managed Redis (serverless, per-request pricing)
See Self-Hosted → Docker for deployment instructions.