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 15 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 15 application with App Router that serves as the entry point for users:

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

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

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

Middleware stack (execution order):

1. RequestIdMiddleware — Attaches X-Request-ID to every response
2. MetricsMiddleware — Tracks HTTP request count and latency
3. CORSMiddleware — Handles cross-origin requests
4. 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 15 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, compose, nginx
    supabase/             # SQL migrations
  docs/                   # MkDocs documentation

Managed with Turborepo and npm workspaces.

Security Model

Gremia follows a zero-trust security architecture:

1. Authentication — JWT tokens for API access, MFA support
2. Transport — TLS 1.3 for all connections, AES-256-GCM for tunnel messages
3. Identity — mTLS with 24-hour ephemeral certificates
4. Authorization — Row-Level Security (RLS) in Supabase
5. Encryption — AES-256-GCM for data at rest with versioned key rotation
6. Audit — Every action logged with actor, action, resource, and result
7. 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 Cloud Platform
        CDN[Vercel / CDN]
        LB[Load Balancer]
        O1[Orchestrator 1]
        O2[Orchestrator N]
    end

    subgraph Database
        SB[Supabase EU]
    end

    Browser --> CDN
    CDN --> LB
    Desktop --> LB
    LB --> O1
    LB --> O2
    O1 --> SB
    O2 --> SB

• Builder is deployed on Vercel (or similar CDN edge platform)
• Cloud runs as Docker containers behind a load balancer
• Shell is distributed as platform-specific installers
• Database is managed Supabase in the EU region