System Architecture¶

Gremia is a Universal Meta-Agent Aggregator composed of three primary components that work together to generate and execute AI operational infrastructure for any business.

High-Level Architecture¶

graph TB
    subgraph User Layer
        U[User / Business Owner]
    end

    subgraph Builder ["Gremia Builder (Web)"]
        WEB[Next.js 16 App]
        CHAT[Chat Interface]
        PREVIEW[Manifest Preview]
    end

    subgraph Cloud ["Gremia Cloud (Orchestrator)"]
        API[FastAPI + LangGraph]
        ARCH[Architect Agent]
        EXEC[Execution Engine]
        BRIDGE[Tool Bridge]
        SEC[Security Layer]
    end

    subgraph Shell ["Gremia Shell (Desktop)"]
        TAURI[Tauri v2 + Rust]
        TUNNEL[WebSocket Tunnel]
        MCPMGR[MCP Manager]
        MCP1[MCP Server 1]
        MCP2[MCP Server N]
    end

    subgraph Data ["Data Layer"]
        SUPA[Supabase PostgreSQL]
        RAG[RAG Knowledge Base]
    end

    U --> WEB
    WEB --> CHAT
    CHAT --> API
    API --> ARCH
    ARCH --> SUPA
    PREVIEW --> API

    API --> EXEC
    EXEC --> BRIDGE
    BRIDGE --> TUNNEL
    TUNNEL --> MCPMGR
    MCPMGR --> MCP1
    MCPMGR --> MCP2

    SEC --> API
    SUPA --> API
    RAG --> ARCH

Component Overview¶

Gremia Builder (`apps/web/`)¶

A Next.js 16 application with App Router that serves as the entry point for users:

Layer	Technology
Framework	Next.js 16 (App Router)
UI	Shadcn/UI + Tailwind v4
Validation	Zod (manifest schema)
i18n	Built-in (English + Spanish)
Auth	Supabase Auth + MFA + Google One Tap

Key pages:

/builder/new — Chat interface for manifest generation
/dashboard — Manifest list and team overview
/teams — Team management
/login, /register — Authentication

The Builder communicates with the Cloud via REST API, streaming responses through Server-Sent Events (SSE).

Gremia Cloud (`services/orchestrator/`)¶

The FastAPI orchestrator is the brain of the system:

Layer	Technology
Framework	FastAPI
Agent orchestration	LangGraph 1.0.7+
AI provider	Anthropic (Claude models)
Database	Supabase (PostgreSQL)
Security	JWT, mTLS, AES-256-GCM
Cache	Upstash Redis (rate limiting, execution cache)

Routers (API surface):

Router	Prefix	Purpose
`chat`	`/api/v1/chat`	Architect conversation streaming
`tunnel`	`/api/v1/tunnel`	WebSocket bridge to Shell
`manifest`	`/api/v1/manifests`	CRUD for team manifests
`auth`	`/api/v1/auth`	JWT verification
`certs`	`/api/v1/certs`	mTLS certificate signing
`execution`	`/api/v1/executions`	Task execution management
`billing`	`/api/v1/billing`	Subscription and credits
`privacy`	`/api/v1/privacy`	GDPR consent and erasure
`admin`	`/api/v1/admin`	Key rotation and admin ops
`sessions`	`/api/v1/sessions`	Builder session management
`dashboard`	`/api/v1/dashboard`	Dashboard stats
`branding`	`/api/v1/branding`	Team branding configuration

Middleware stack (execution order):

RequestIdMiddleware — Attaches X-Request-ID to every response
MetricsMiddleware — Tracks HTTP request count and latency
CORSMiddleware — Handles cross-origin requests
GZipMiddleware — Compresses responses > 1KB

Gremia Shell (`apps/desktop/`)¶

A Tauri v2 desktop application with a Rust backend:

Layer	Technology
Framework	Tauri v2
Frontend	React 19 + TypeScript + Vite 6
Backend	Rust
Encryption	AES-256-GCM (aes-gcm crate)
TLS	ring + rcgen (EC P-256)
Auto-update	tauri-plugin-updater

Rust modules:

Module	Purpose
`tunnel.rs`	WebSocket connection, message routing, encryption
`mcp_manager.rs`	MCP server lifecycle (spawn, init, call, stop)
`cert_rotation.rs`	mTLS certificate auto-renewal
`crypto.rs`	Encryption utilities
`manifest.rs`	Manifest parsing and validation
`jsonrpc.rs`	JSON-RPC 2.0 client for MCP stdio
`commands.rs`	Tauri IPC commands exposed to frontend
`session.rs`	User session and auth token management
`audit.rs`	Local audit logging
`zero_trust.rs`	Security policy enforcement
`updater.rs`	Auto-update checker and installer
`state_sync.rs`	Cross-thread state synchronization

Monorepo Structure¶

gremia-labs/
  apps/
    web/                  # Next.js 16 Builder
    desktop/              # Tauri v2 Shell
  packages/
    types/                # Shared TypeScript types
    manifest-schema/      # Zod manifest validation
    ui/                   # Shared UI components
  services/
    orchestrator/         # FastAPI + LangGraph Cloud
  infra/
    docker/               # Dockerfiles
    nginx/                # Nginx reverse proxy config
    supabase/             # SQL migrations
    prometheus/           # Prometheus config
    grafana/              # Grafana dashboards
  docker-compose.prod.yml # Production Docker Compose (root)
  docs/                   # MkDocs documentation

Managed with Turborepo and npm workspaces.

Security Model¶

Gremia follows a zero-trust security architecture:

Authentication — JWT tokens for API access, MFA support
Transport — TLS 1.3 for all connections, AES-256-GCM for tunnel messages
Identity — mTLS with 24-hour ephemeral certificates
Authorization — Row-Level Security (RLS) in Supabase
Encryption — AES-256-GCM for data at rest with versioned key rotation
Audit — Every action logged with actor, action, resource, and result
Compliance — GDPR consent management, erasure support, EU AI Act transparency

Technology Decisions¶

Decision	Choice	Rationale
Desktop framework	Tauri v2	Small binary, Rust security, native performance
Agent framework	LangGraph	Graph-based orchestration, streaming support
Database	Supabase	PostgreSQL with built-in auth, RLS, and real-time
Tool protocol	MCP	Anthropic standard, JSON-RPC 2.0, growing ecosystem
Schema validation	Zod (TS) + Pydantic (Python)	Type-safe validation at every boundary
Encryption	AES-256-GCM	NIST standard, authenticated encryption
Certificate format	EC P-256	Modern, efficient, NIST-approved elliptic curve

Deployment Architecture¶

graph LR
    subgraph Internet
        Browser[Browser]
        Desktop[Desktop App]
    end

    subgraph "Managed Services"
        VCL[Vercel CDN]
        RW[Railway europe-west4]
        RD[Upstash Redis]
    end

    subgraph Database
        SB[Supabase EU]
    end

    Browser --> VCL
    VCL --> RW
    Desktop --> RW
    RW --> SB
    RW --> RD

Builder is deployed on Vercel (CDN edge, auto-deploy from main)
Cloud runs on Railway (europe-west4, auto-deploy from main for prod, deploy/dev for dev)
Shell is distributed as platform-specific installers (Windows NSIS, macOS DMG, Linux AppImage/deb)
Database is managed Supabase in the EU region (Frankfurt)
Cache is Upstash Redis (TLS, rate limiting, execution cache)