Technical Architecture

Technical Architecture (Revised for Agent-Human Collaboration)

System Overview

┌─────────────────────────────────────────────────────────┐
│                    Agent Clients                          │
│  (LangChain, CrewAI, AutoGen, Claude, GPT, custom)       │
└──────────────┬──────────────────┬────────────────────────┘
               │ MCP              │ REST API
               ▼                  ▼
┌─────────────────────────────────────────────────────────┐
│              API Gateway (Hono on CF Workers)             │
│          (Auth, Rate Limiting, Routing)                   │
├─────────────────────────────────────────────────────────┤
│                  Identity Service                        │
│   (Agent auth + Human auth, capability tokens, org mgmt) │
├─────────────────────────────────────────────────────────┤
│                 Core File Service                        │
│       (CRUD, versioning, sharing, search)                │
├─────────────────────────────────────────────────────────┤
│           ★ Collaboration Layer (NEW) ★                  │
│   (Comments, activity feed, notifications, real-time)    │
├──────────┬──────────┬──────────┬────────────────────────┤
│ Storage  │ Metadata │ Search   │ Audit                   │
│ (R2)     │ (Neon PG)│(Meili)   │ (Append-only)           │
└──────────┴──────────┴──────────┴────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────┐
│              Human Dashboard (Web App)                    │
│  (File browser, activity feed, comments, agent status)   │
└─────────────────────────────────────────────────────────┘

Cloudflare R2: Storage Backend

Why R2

Feature	R2	S3	Why It Matters
Storage	$0.015/GB/mo	$0.023/GB/mo	35% cheaper
Egress	$0.00	$0.09/GB	Agents read/write frequently — $0 egress is critical
Class A ops	$4.50/M	$5.00/M	Comparable
Class B ops	$0.36/M	$0.40/M	Comparable
Free included	10 GB + 1M writes + 10M reads/mo	None	First ~10GB of platform storage is free
S3-compatible	Yes	N/A	Easy migration path

Per-Agent Cost Model

Moderate activity agent (50K writes, 500K reads/month):

Storage	Storage Cost	Ops Cost	Total COGS
1 GB	$0.015	$0.405	$0.42
5 GB	$0.075	$0.405	$0.48
10 GB	$0.15	$0.405	$0.56
100 GB	$1.50	$0.405	$1.91

Key insight: Operations cost dominates at low storage tiers. A 1GB agent costs $0.42/month, of which only $0.015 is storage.

Low activity agent (10K writes, 100K reads/month):

Storage	Total COGS
1 GB	$0.10
5 GB	$0.16
10 GB	$0.23

Per-Organization Cost Model (NEW — With Human Seats)

Human dashboard users generate additional read operations (browsing files, viewing activity) but minimal write operations. Estimated human dashboard usage: ~50K reads/month per active human user.

Org Size	Agents	Humans	Est. Monthly COGS
Starter (3 agents, 2 humans)	$1.26	$0.04	$1.30
Team (5 agents, 5 humans)	$2.10	$0.09	$2.19
Pro (10 agents, 10 humans)	$4.20	$0.18	$4.38

Margin at $15/month (Team): ~85%. Human seats add minimal COGS but significant revenue.

Object Layout in R2

r2://prod-storage/
├── {org_id}/
│   ├── {agent_id}/
│   │   ├── workspace/{file_hash}
│   │   ├── outputs/{file_hash}
│   │   └── shared/{file_hash}
│   ├── {agent_id_2}/...
│   └── shared/                    # NEW: Org-wide shared workspace
│       └── {file_hash}

Content-addressable storage (SHA-256):

• Files stored by content hash → automatic deduplication
• Versioning = new metadata record pointing to new hash
• Only changed content is stored

MCP Server (Agent Interface)

Runtime: TypeScript/Node.js (MCP SDK is TypeScript-first) Transport: stdio (local) and SSE (remote)

const server = new McpServer({
  name: "agentvault",
  version: "1.0.0",
});

// Core file operations
server.tool("vault_write", writeSchema, handleWrite);
server.tool("vault_read", readSchema, handleRead);
server.tool("vault_list", listSchema, handleList);
server.tool("vault_share", shareSchema, handleShare);
server.tool("vault_search", searchSchema, handleSearch);
server.tool("vault_delete", deleteSchema, handleDelete);
server.tool("vault_versions", versionsSchema, handleVersions);

// NEW: Agent-Human Collaboration tools
server.tool("vault_comment", commentSchema, handleComment);
server.tool("vault_feedback", feedbackSchema, handleFeedback);
server.tool("vault_watch", watchSchema, handleWatch);
server.tool("vault_activity", activitySchema, handleActivity);

server.resource("workspace", workspaceTemplate, handleWorkspace);
server.resource("shared", sharedTemplate, handleShared);

Collaboration MCP Tools (NEW)

Tool	Purpose	Used By
vault_comment	Add a comment to a file or directory	Agents and humans (via API)
vault_feedback	Read feedback/comments on a file (so agents can respond to human input)	Agents
vault_watch	Subscribe to changes on a path (webhook or poll)	Agents
vault_activity	Get recent activity in workspace (who did what)	Agents

Example: Agent reads human feedback

// Agent checks for human comments on its draft
const feedback = await vault_feedback({
  path: "/campaigns/q1-launch/draft-v1.md",
  since: "2026-02-24T00:00:00Z"
});
// Returns: [{ author: "rakesh@company.com", type: "human",
//   comment: "Tone is too formal, make it conversational", timestamp: "..." }]

// Agent revises based on feedback
const revised = await generateRevision(draft, feedback);
await vault_write({
  path: "/campaigns/q1-launch/draft-v2.md",
  content: revised,
  metadata: { revision_reason: "Human feedback: tone adjustment" }
});

Open-source: The MCP server and core SDK are open-source (MIT). Anyone can self-host with local filesystem or their own R2/S3 bucket. Managed service adds: identity management, cross-agent sharing, human dashboard, collaboration features, audit trails, enterprise features.

REST API (Human Dashboard + Non-MCP Clients)

For the human dashboard, admin tools, and non-MCP clients.

# Core file operations
POST   /v1/files                 # Write file
GET    /v1/files/:path           # Read file
PUT    /v1/files/:path           # Update file
DELETE /v1/files/:path           # Delete file
GET    /v1/files/:path/versions  # List versions
GET    /v1/files?q=              # Search files
POST   /v1/share                 # Share with agent/human

# NEW: Collaboration endpoints
POST   /v1/files/:path/comments  # Add comment (human or agent)
GET    /v1/files/:path/comments  # Get comments on a file
GET    /v1/activity              # Activity feed (org-wide)
GET    /v1/activity/:agent_id    # Activity for a specific agent
POST   /v1/notifications/subscribe  # Subscribe to events
GET    /v1/agents/status         # Agent status dashboard data

# Admin
GET    /v1/audit                 # Audit log
GET    /v1/org/members           # List agents + humans in org
POST   /v1/org/invite            # Invite human to org

Collaboration Layer (NEW)

The collaboration layer is the primary differentiator. It enables agents and humans to work on shared files with real-time awareness.

Architecture

┌──────────────────────────────────┐
│          Collaboration Layer      │
├──────────────────────────────────┤
│  Comment Engine                   │
│  ├── File-level comments          │
│  ├── Inline annotations           │
│  ├── Thread replies               │
│  └── Author attribution (agent/   │
│      human)                       │
├──────────────────────────────────┤
│  Activity Feed                    │
│  ├── File events (created,        │
│  │   updated, deleted)            │
│  ├── Comment events               │
│  ├── Agent status (active/idle)   │
│  └── Filterable by agent/human/   │
│      path                         │
├──────────────────────────────────┤
│  Notification System              │
│  ├── Webhook delivery             │
│  │   (Cloudflare Queues)          │
│  ├── Email digests (via Mailmolt) │
│  ├── Slack integration (webhook)  │
│  └── Dashboard push (SSE/WS)     │
├──────────────────────────────────┤
│  Real-Time Sync                   │
│  ├── Cloudflare Durable Objects   │
│  │   (per-workspace state)        │
│  ├── SSE for dashboard updates    │
│  └── Presence (who's viewing)     │
└──────────────────────────────────┘

Real-Time Sync with Durable Objects

Each shared workspace gets a Durable Object that manages real-time state:

// Durable Object: WorkspaceSync
export class WorkspaceSync {
  state: DurableObjectState;
  connections: Map<string, WebSocket>; // connected dashboard clients

  async handleFileEvent(event: FileEvent) {
    // 1. Persist event to activity log
    await this.state.storage.put(`event:${event.id}`, event);

    // 2. Broadcast to all connected dashboard clients
    for (const [id, ws] of this.connections) {
      ws.send(JSON.stringify({
        type: "file_event",
        data: {
          agent: event.agent_id,
          action: event.action,   // "wrote", "updated", "deleted"
          path: event.path,
          timestamp: event.timestamp
        }
      }));
    }

    // 3. Queue notifications (email, Slack, webhooks)
    await this.env.NOTIFICATION_QUEUE.send(event);
  }

  async handleComment(comment: Comment) {
    // Persist + broadcast + notify watchers
  }
}

Notification Pipeline

File event → Durable Object → Cloudflare Queue → Notification Worker
                                                    ├── Webhook delivery
                                                    ├── Email digest (Mailmolt)
                                                    ├── Slack webhook
                                                    └── Dashboard SSE push

Humans receive notifications when:

• An agent writes or updates a file they’re watching
• An agent completes a task (status change)
• Another human comments on a shared file
• An agent reads their feedback (confirmation)

Agents receive notifications when:

• A human comments on their output
• A human drops a new file in a watched directory
• Permissions change

Human Dashboard (Web Application)

Tech Stack

Component	Technology	Why
Frontend	Next.js (App Router) or Astro + React islands	SSR for SEO + client interactivity
Styling	Tailwind CSS + shadcn/ui	Consistent, Google Drive-like UX
Real-time	SSE via Cloudflare Workers	Lightweight, no WebSocket server needed
Auth	Clerk or Auth0	OAuth 2.0 (Google, GitHub SSO) for humans
Hosting	Cloudflare Pages	Integrated with Workers

Dashboard Views

1. File Browser (Primary View)

• Familiar Google Drive-like interface
• Tree view: org → workspaces → agent folders
• File preview (markdown rendered, JSON formatted, images inline)
• “Created by” badge (agent name + icon or human avatar)
• Version history per file
• Drag-and-drop upload (human → workspace)

2. Activity Feed

• Real-time stream of all actions in the organization
• Filter by: agent, human, workspace, file type, action type
• Each entry: [timestamp] [agent/human avatar] [action] [file path]
• Example: 2 min ago | agent-content | wrote | /campaigns/q1/draft-v2.md

3. Agent Status Dashboard

• Card per agent: name, status (active/idle/error), last activity, files written today
• Click to drill into agent’s workspace
• Health indicators (error rate, response time)

4. Comments Panel

• Slide-out panel on file view
• Threaded comments with agent/human attribution
• Markdown support in comments
• @mention agents or humans

5. Settings / Admin

• Agent management (create, revoke, permissions)
• Human member management (invite, roles)
• Billing and plan management
• Audit log viewer

UX Principle: Feel Like Google Drive

The dashboard MUST feel familiar to non-technical users. Product managers, content reviewers, and compliance officers should be able to:

• View agent-created files without any setup
• Add comments without understanding MCP
• Browse activity feed without knowing what “agents” are in a technical sense
• Zero learning curve for basic viewing and commenting

Identity Service (Revised — Agents + Humans)

Agent Registration Flow (Unchanged)

1. Developer creates account → gets org_id + API key
2. Developer registers agent → gets agent_id + agent_secret
3. Agent authenticates with agent_secret → receives capability token (JWT, 15-min expiry)
4. Capability token is scoped: paths, operations, expiry
5. Every API call includes capability token → validated on every request
6. Token refresh via agent_secret (never stored after initial display)

Human Registration Flow (NEW)

1. Developer invites human via email → human receives invite link
2. Human signs up via OAuth (Google, GitHub, email+password)
3. Human gets dashboard access scoped to their organization
4. Human role determines permissions:
   - Viewer: read files, view activity
   - Commenter: view + add comments
   - Editor: view + comment + upload files + manage agents
   - Admin: full org management

Capability Token (JWT) — Revised for Both Actors

{
  "sub": "agent-7x9k2",
  "iss": "agentvault.dev",
  "aud": "agentvault",
  "iat": 1709251200,
  "exp": 1709252100,
  "actor_type": "agent",
  "scope": {
    "paths": ["/workspace/*", "/outputs/*", "/shared/*"],
    "ops": ["read", "write", "list", "comment"],
    "max_file_size": 10485760
  },
  "org": "org-abc123",
  "owner": "user:rakesh@company.com"
}

Human tokens:

{
  "sub": "user-rakesh",
  "iss": "agentvault.dev",
  "aud": "agentvault",
  "actor_type": "human",
  "role": "editor",
  "scope": {
    "paths": ["/*"],
    "ops": ["read", "write", "list", "comment", "manage_agents"]
  },
  "org": "org-abc123"
}

Cross-Product Identity (Suite Integration)

If agent already has a Mailmolt identity, the storage service accepts the same credentials. Unified identity layer shared across Mailmolt, Storage, and Findable.

Metadata Database (PostgreSQL via Neon)

Core Schema (Revised — With Collaboration Tables)

CREATE TABLE organizations (
  id TEXT PRIMARY KEY,
  name TEXT,
  plan TEXT DEFAULT 'trial',
  created_at TIMESTAMPTZ DEFAULT NOW()
);

CREATE TABLE agents (
  id TEXT PRIMARY KEY,
  org_id TEXT REFERENCES organizations(id),
  name TEXT,
  created_at TIMESTAMPTZ,
  trust_level TEXT DEFAULT 'new',  -- new, silver, gold
  status TEXT DEFAULT 'idle',      -- NEW: idle, active, error
  last_active TIMESTAMPTZ,         -- NEW: for dashboard status
  metadata JSONB
);

-- NEW: Human users table
CREATE TABLE users (
  id TEXT PRIMARY KEY,
  org_id TEXT REFERENCES organizations(id),
  email TEXT UNIQUE NOT NULL,
  name TEXT,
  role TEXT DEFAULT 'viewer',  -- viewer, commenter, editor, admin
  avatar_url TEXT,
  created_at TIMESTAMPTZ DEFAULT NOW(),
  last_active TIMESTAMPTZ
);

CREATE TABLE files (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  agent_id TEXT REFERENCES agents(id),
  org_id TEXT REFERENCES organizations(id),
  path TEXT NOT NULL,
  content_hash TEXT NOT NULL,      -- SHA-256, points to R2 object
  content_type TEXT,
  size_bytes BIGINT,
  metadata JSONB,
  created_at TIMESTAMPTZ DEFAULT NOW(),
  updated_at TIMESTAMPTZ DEFAULT NOW(),
  version INT DEFAULT 1,
  created_by_type TEXT DEFAULT 'agent',  -- NEW: 'agent' or 'human'
  created_by_id TEXT,                     -- NEW: agent_id or user_id
  UNIQUE(org_id, path)                    -- CHANGED: unique per org, not per agent
);

CREATE TABLE file_versions (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  file_id UUID REFERENCES files(id),
  version INT,
  content_hash TEXT NOT NULL,
  actor_type TEXT,    -- NEW: 'agent' or 'human'
  actor_id TEXT,      -- NEW: agent_id or user_id
  change_reason TEXT,
  created_at TIMESTAMPTZ DEFAULT NOW()
);

CREATE TABLE shares (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  file_id UUID REFERENCES files(id),
  source_agent TEXT REFERENCES agents(id),
  target_type TEXT,  -- NEW: 'agent' or 'human'
  target_id TEXT,    -- NEW: agent_id or user_id
  permissions TEXT[],
  expires_at TIMESTAMPTZ,
  created_at TIMESTAMPTZ DEFAULT NOW()
);

-- NEW: Comments table
CREATE TABLE comments (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  file_id UUID REFERENCES files(id),
  parent_id UUID REFERENCES comments(id),  -- threading
  author_type TEXT NOT NULL,    -- 'agent' or 'human'
  author_id TEXT NOT NULL,
  body TEXT NOT NULL,
  resolved BOOLEAN DEFAULT false,
  created_at TIMESTAMPTZ DEFAULT NOW(),
  updated_at TIMESTAMPTZ DEFAULT NOW()
);

-- NEW: Activity events table (for activity feed)
CREATE TABLE activity_events (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  org_id TEXT REFERENCES organizations(id),
  actor_type TEXT NOT NULL,     -- 'agent' or 'human'
  actor_id TEXT NOT NULL,
  event_type TEXT NOT NULL,     -- 'file_created', 'file_updated', 'comment_added', 'agent_status_change'
  resource_path TEXT,
  metadata JSONB,
  created_at TIMESTAMPTZ DEFAULT NOW()
);

-- NEW: Watch subscriptions (for notifications)
CREATE TABLE watches (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  watcher_type TEXT NOT NULL,   -- 'agent' or 'human'
  watcher_id TEXT NOT NULL,
  path_pattern TEXT NOT NULL,   -- glob pattern: "/campaigns/*"
  notification_channel TEXT,    -- 'webhook', 'email', 'slack', 'dashboard'
  webhook_url TEXT,
  created_at TIMESTAMPTZ DEFAULT NOW()
);

CREATE TABLE audit_log (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  org_id TEXT,
  actor_type TEXT,  -- NEW: 'agent' or 'human'
  actor_id TEXT,    -- NEW: replaces agent_id
  operation TEXT,
  file_path TEXT,
  metadata JSONB,
  ip_address INET,
  timestamp TIMESTAMPTZ DEFAULT NOW()
);

-- Indexes
CREATE INDEX idx_files_org_path ON files(org_id, path);
CREATE INDEX idx_files_created_by ON files(created_by_type, created_by_id);
CREATE INDEX idx_comments_file ON comments(file_id, created_at);
CREATE INDEX idx_activity_org ON activity_events(org_id, created_at DESC);
CREATE INDEX idx_activity_actor ON activity_events(actor_type, actor_id, created_at DESC);
CREATE INDEX idx_watches_path ON watches(path_pattern);
CREATE INDEX idx_audit_org ON audit_log(org_id, timestamp);
CREATE INDEX idx_audit_actor ON audit_log(actor_type, actor_id, timestamp);

Security Architecture

Authentication

Method	Use Case	Details
API keys	Agent authentication	vault_live_<random>, hashed (SHA-256) before storage
JWT capability tokens	Per-request auth (agents)	15-min expiry, scoped by paths/ops
OAuth 2.0	Human dashboard login	GitHub/Google SSO via Clerk/Auth0
Session cookies	Human dashboard sessions	Httponly, secure, SameSite=Strict
mTLS (Enterprise)	High-security agents	Client certificate verification

Authorization

Path-based permissions with glob patterns, extended for agent + human actors:

Agent A (agent-content):
  /workspace/*       → read, write, delete
  /shared/campaigns/* → read, write
  /shared/finance/*   → no access

Agent B (agent-analytics):
  /workspace/*       → read, write, delete
  /shared/campaigns/* → read only
  /shared/analytics/* → read, write

Human (rakesh@company.com, role: editor):
  /*                 → read, comment
  /shared/*          → read, write, comment
  Agent management   → create, revoke, modify permissions

Human (priya@company.com, role: commenter):
  /*                 → read, comment
  Agent management   → no access

Encryption

Layer	Method
In transit	TLS 1.3 mandatory (Cloudflare)
At rest	R2 AES-256 (default)
Enterprise	Customer-managed keys (CMEK) via Cloudflare KMS or external

Multi-Tenant Isolation

Plan	Isolation Level
Trial / Starter	Logical isolation (path-based in shared R2 bucket)
Team / Pro	Bucket-per-organization
Enterprise	Dedicated infrastructure (account-per-customer optional)

Compliance Path

Standard	Timeline	Cost	Collaboration Relevance
GDPR	Month 6 (data residency via R2 location hints)	Minimal	Human PII in comments/profiles
EU AI Act	Month 8 (Aug 2026 enforcement)	Minimal	Human oversight = our product
SOC 2 Type I	Month 12	~$30-80K	Required for enterprise dashboard access
SOC 2 Type II	Month 18	~$20-50K/year	Ongoing
HIPAA	Month 24+ (enterprise demand only)	BAA with Cloudflare

EU AI Act opportunity: The EU AI Act (August 2026 enforcement) requires human oversight of high-risk AI systems. Our human dashboard with audit trails and approval workflows directly addresses this regulatory requirement.

Infrastructure Phasing

Phase 1: MVP (~$100-200/month)

Cloudflare Workers       → API gateway, MCP server (SSE)
Cloudflare R2            → File storage
Neon (Postgres)          → Metadata, auth, audit, comments
Cloudflare Pages         → Human dashboard (static + client)

Phase 2: Growth (~$500-2000/month)

+ Upstash Redis          → Caching, rate limiting, presence
+ Cloudflare Queues      → Async processing (notifications, webhooks)
+ Meilisearch Cloud      → File search
+ Cloudflare Durable Objects → Real-time workspace sync

Phase 3: Scale (~$2000+/month)

+ Multi-region R2        → Global storage
+ Postgres read replicas → Read scaling (dashboard queries)
+ Dedicated Meilisearch  → Scale search
+ Durable Objects (scaled) → Per-workspace real-time state

API Design Principles

1. MCP-first: MCP server is the primary agent interface, REST is for humans and admin
2. Content-addressable: Files stored by hash — dedup + efficient versioning
3. Idempotent writes: Same content + same path = no duplicate storage
4. Streaming: Large files via streaming (not buffered in memory)
5. Pagination: All list operations cursor-based
6. Webhooks: Subscribe to file events (created, updated, shared, deleted, commented)
7. Batch operations: Bulk read/write for multi-file workflows
8. Actor attribution: Every operation records whether the actor is an agent or human
9. Real-time events: Dashboard receives live updates via SSE/Durable Objects