Architecture Overview

Go Bananas! is built as an edge-deployed, multi-tenant MCP server on Cloudflare's global network.

High-Level Architecture

MCP clients, the REST API, and the Web Console all hit the same Cloudflare Edge Worker, which routes through the model registry to whichever provider the tenant chose for that request.

Key Design Principles

1. Edge-First Architecture

Deployed to 300+ Cloudflare data centers worldwide:

• Sub-10ms routing to nearest edge
• Automatic scaling with no cold starts
• Global data via Durable Objects

2. Multi-Tenant Isolation

Complete data separation between tenants:

• Database: All rows filtered by tenant_id
• Storage: R2 keys prefixed with {tenant_id}/
• API Keys: Multiple keys per tenant

3. Stateful Sessions

Durable Objects maintain conversation context:

• Session tracking: last_image_id for conversational editing
• Request-scoped: Context lives for request duration
• Persistent state: Session data saved to D1

4. Hybrid Storage

Optimized for different data types:

• R2: Binary image data (cost-effective, CDN-backed)
• D1: Metadata, relationships, search indexes
• KV: Fast lookups for config and keys

Component Overview

Worker entry point, MCP Agent, services layer, and storage

Component	Technology	Purpose
Entry Point	Cloudflare Worker	Request routing, auth
MCP Agent	Durable Object	Stateful MCP handling
Database	D1 (SQLite)	Metadata, relationships
Object Storage	R2	Image files
Cache	KV	API keys, config
AI Backend	Gemini API + OpenAI API	Image generation (per-tenant model registry)

Request Lifecycle

Every request follows this path:

1. Ingress → Worker receives HTTP request
2. Authentication → OAuth bearer token or API key validated
3. Routing → Request forwarded to Durable Object
4. Execution → MCP tool processes request
5. Storage → Results saved to R2/D1
6. Response → Results returned to client

Documentation Structure

Explore each architectural component:

Section	Coverage
System Overview	Complete system diagram
Request Flow	Request processing sequence
Multi-Tenancy	Tenant isolation patterns
Data Flow	How data moves through the system
Storage Architecture	R2, D1, and KV patterns
Session Management	Stateful conversation handling
Character System	Character reference architecture
Security	Encryption and access control

Technology Stack

Runtime

• Cloudflare Workers - V8 isolate runtime
• Durable Objects - Stateful edge compute
• TypeScript - Type-safe development

Storage

• D1 - Serverless SQLite database
• R2 - S3-compatible object storage
• KV - Key-value store

Frontend

• React 18 - UI framework
• Vite - Build tool
• TailwindCSS - Styling

External

• Gemini API (Flash Lite, Flash, Pro) - Image generation
• OpenAI API (GPT Image 2, GPT Image 2.5 Flare and Sunburst) - Alternative image provider, tenant-selectable
• MCP Protocol - AI integration standard

Performance Characteristics

Metric	Target	Typical
Auth latency	<5ms	2-3ms
D1 query	<10ms	3-5ms
R2 read	<50ms	20-30ms
Provider call (Flash)	<10s	3-5s
Provider call (Pro / OpenAI)	<30s	8-25s
E2E generation	<15s	5-8s

Scaling Model

Deployed to 300+ edge locations worldwide

• Workers: Unlimited parallel execution
• Durable Objects: One per session ID
• D1: Shared with concurrent access
• R2: Unlimited parallel reads/writes

Next Steps

• System Overview →
• Request Flow →
• Multi-Tenancy →