Architecture Overview

ggui is an Agent Interface Platform that enables AI agents to create rich, interactive interfaces for human communication. Instead of being limited to text-only interactions, agents can spawn ephemeral UIs on demand through a simple MCP interface.

Core Value Proposition

• Agents describe what they need in natural language
• ggui’s UI Builder Agent generates, evaluates, and iterates on the UI
• Users interact through a fluid carousel-based interface
• Structured input flows back to the agent

System Architecture

Agent (Claude, GPT, Custom)
  │
  │ MCP Protocol (@ggui-ai/mcp-client)
  ▼
API Gateway WebSocket (wss://ws.guuey.com)
  │
  │ Lambda → SQS
  ▼
UI Generator Service (ECS Fargate)
  │  Plan → Build → Validate → Compile → Send
  │
  ├── DynamoDB (state + metrics)
  ├── Anthropic API (Claude)
  └── S3 (assets)
  │
  │ Callback Lambda → WebSocket
  ▼
User (ggui Frontend - @ggui-ai/react)

Core Models

GguiApp

A GguiApp is the core entity owned by an individual or organization:

• Agents - Agent connectors, each with a unique API key
• Styling - Prompt guidelines and style files for the UI builder
• Adapters - Enabled adapters (camera, audio, etc.)
• Predesigned Components - Custom components with descriptions
• User Auth Settings - Mode: anonymous, optional, pass-through, or platform-managed

Session and Stack Model

End-users interact through sessions containing a stack of UI panels:

Session
└── Stack (array of UI panels)
    ├── Stack Item 0 (generated UI)
    ├── Stack Item 1 (generated UI)
    ├── Stack Item 2 (generated UI) ← current view
    └── ...

Navigation uses a MacOS Preview-style thumbnail toggle with slide animations between panels.

Components

API Gateway WebSocket

Handles persistent connections between users and the backend:

• Scales to millions of concurrent connections
• Routes messages to Lambda by session ID
• Cognito JWT authorizer for authentication
• 2-hour connection limit with auto-reconnect

UI Generator Service (ECS Fargate)

Runs the UI Builder Agent with Claude API and compiles UI code:

1. Receive generation requests via SQS queue
2. Load session state from DynamoDB
3. Execute generation strategy (simple/balanced/advanced)
4. Compile with esbuild (~20-50ms)
5. Track metrics (tokens, cost, time)
6. Handle errors with recovery and fallbacks
7. Send compiled UI back via callback Lambda

Strategy	Model	Use Case	Cost
simple	Haiku	Quick prototypes	~$0.005
balanced	Sonnet	Production (default)	~$0.02
advanced	Sonnet + review	Complex UIs	~$0.04

DynamoDB Tables

• GguiApp - App configuration, styling, auth settings (GSI: byOwner)
• AgentConnector - API keys and permissions per agent (GSI: byApp)
• Session - Session state, stack, connection info (GSI: byApp, byConnection)
• Users - User profiles, plans, API keys

Infrastructure (AWS Amplify)

The backend uses AWS Amplify Gen 2:

amplify/
├── backend.ts           # Main backend definition
├── auth/                # Cognito configuration
├── data/                # DynamoDB schema (via AppSync)
├── functions/           # Lambda functions
├── custom/              # CDK stacks (WebSocket API, ECS)
└── storage/             # S3 configuration

Scaling

Component	Scaling	Limit
API Gateway WebSocket	Automatic	Millions of connections
Lambda	Automatic	1000 concurrent (can increase)
DynamoDB	On-demand	Unlimited

Authorization

Agent Authorization

Each agent has its own API key with explicit App ID:

X-Ggui-App-Id: app_123
Authorization: Bearer ggui_sk_abc...

End-User Authorization

Four modes configured per-app:

Mode	Experience	Builder Responsibility
Anonymous	Just uses the UI	None - session ID only
Optional	Can sign in for persistence	Handle auth in their app
Pass-through	Already signed into builder’s app	Pass user token/ID to ggui SDK
Ggui-managed	Signs into ggui (Cognito)	None - ggui handles it