Architecture Overview
Relevant source files
The following files were used as context for generating this wiki page:
e-zer0 is a self-hosted bridge that connects AI agents to email providers like Gmail and Outlook using the Model Context Protocol (MCP). The system centralizes email management, security redaction, and audit logging within a user-owned Cloudflare environment.
The architecture eliminates third-party hosting risks by running entirely on the Cloudflare Developer Platform. It provides a web dashboard for administrative tasks and an MCP server for AI tool interaction.
Sources: AGENTS.md:7-12, README.md:12-25
Core Technology Stack
The application utilizes a serverless, edge-first approach. It relies on the following Cloudflare services and frameworks:
- Compute: Cloudflare Workers (V8 isolates) running TypeScript.
- Web Framework: Hono for routing, middleware, and JSX-based Server-Side Rendering (SSR).
- Database: Cloudflare D1 (SQLite) for storing settings, accounts, and audit logs.
- Vector Search: Cloudflare Vectorize for semantic email search.
- AI Models: Cloudflare Workers AI (
bge-base-en-v1.5) for generating embeddings. - Storage: Cloudflare KV for rate limiting and session management.
Sources: AGENTS.md:14-20, wrangler.toml:1-40, README.md:143-150
System Components and Data Flow
The system consists of three primary interaction layers: the Web UI for human administrators, the MCP Server for AI agents, and the Background Tasks for maintenance.
High-Level Architecture
The following diagram illustrates the relationship between the user, AI agents, the Cloudflare Worker, and external providers.
The diagram shows the Cloudflare Worker as the central orchestrator, managing data flow between users, storage, and external APIs.
Sources: AGENTS.md:22-33, src/app.ts:40-60
Component Responsibilities
| Component | Responsibility | Relevant Files |
|---|---|---|
| Hono App | Manages HTTP routing, security headers, and SSR views. | src/app.ts, src/views/layout.tsx |
| MCP Server | Implements the protocol for AI agents to call tools. | src/mcp/server.ts, src/mcp/tools.ts |
| Sanitizer | Redacts PII and detects prompt injection attempts. | src/lib/sanitizer.ts |
| Crypto Lib | Handles AES-256-GCM encryption for OAuth tokens. | src/lib/crypto.ts |
| Setup Script | Provisions D1, Vectorize, and KV via Wrangler. | scripts/setup-cf.js |
Sources: AGENTS.md:24-34, README.md:112-120, src/app.ts:1-30
Security Architecture
e-zer0 implements a "Security First" model to protect sensitive email data.
- Zero Trust & JWT: AI agents authenticate via short-lived JSON Web Tokens (JWT).
- Encryption at Rest: OAuth access and refresh tokens are encrypted using AES-256-GCM before storage in D1. The
ENCRYPTION_KEYis stored as a Cloudflare Secret. - PII Redaction: The system scans email content for credit cards, passwords, SSNs, and API keys, redacting them before the AI agent receives the data.
- Audit Logging: Every tool execution (e.g.,
read_email,organize_email) is logged in theaudit_logstable, recording the actor, action, and outcome. - Rate Limiting: A KV-based rate limiter protects the login and token endpoints from brute-force attacks.
Sources: AGENTS.md:46-62, README.md:37-55, src/app.ts:38-42
MCP Request Lifecycle
This sequence diagram shows the steps taken when an AI agent requests email content.
The flow ensures that raw, sensitive data is never exposed directly to the AI model.
Sources: AGENTS.md:90-100, README.md:37-55
Provisioning and Deployment
The environment setup is automated via scripts/setup-cf.js. This script performs two primary functions:
- Local: Generates
ENCRYPTION_KEYandJWT_SECRETinto a.dev.varsfile for local development. - Remote: Provisions the D1 Database, Vectorize Index, and KV Namespaces on Cloudflare. It also generates the
wrangler.tomlfile with the correct resource IDs.
Sources: scripts/setup-cf.js:10-40, wrangler.toml:1-35
Infrastructure Bindings
The Worker interacts with resources through specific bindings defined in the configuration.
| Binding | Type | Purpose |
|---|---|---|
DB | D1 Database | Storage for accounts, agents, and logs. |
VECTOR_INDEX | Vectorize | Storage for email embeddings. |
AI | Workers AI | Embedding generation. |
RATE_LIMITER | KV | Brute-force protection. |
Sources: wrangler.toml:14-36, src/app.ts:36-43
Summary
The e-zer0 architecture leverages the Cloudflare Edge to provide a secure, low-latency bridge for AI agents. By combining serverless compute with integrated sanitization and audit trails, it allows users to utilize AI email management while maintaining full control over their credentials and sensitive data.