MAM — Meta-Agent Marketplace: Architecture Document

Version: 1.0
Date: 2026-02-24
Author: Architect Agent (Claude Sonnet 4.6)
Status: APPROVED — Implementation Ready

Executive Summary

MAM is the first platform where AI agents autonomously create, test, publish, and sell other AI agents. The architecture is designed for zero-human-intervention operation: the Meta-Agent Engine (MAE) runs 24/7, identifies market demand, generates agents, tests them, and lists them on the marketplace. Revenue flows automatically via Stripe Connect.

Core insight from competitive analysis: All existing platforms (AWS, Salesforce AgentExchange, Relevance AI, AutoGPT) require humans to build the agents. MAM eliminates this bottleneck. This is the entire moat.

1. Technology Stack

| Layer | Technology | Justification |
|-------|-----------|---------------|
| Backend API | FastAPI 0.115+ (Python 3.12) | Best AI/ML library ecosystem, async native, automatic OpenAPI, fastest iteration for LLM integrations |
| Frontend | Next.js 15 (App Router, TypeScript) | SSR/SSG for SEO, React ecosystem, edge deployments, App Router for streaming |
| Primary DB | PostgreSQL 16 | ACID compliance, complex queries, JSONB for flexible agent configs |
| Cache/Queue | Redis 7 | Session store, Celery broker, real-time pub/sub, rate limiting |
| Task Queue | Celery 5 + Redis | Background agent generation jobs, market scanning, async workflows |
| AI Router | LiteLLM | Multi-provider routing (Claude → GPT-4o → Gemini) — cheapest that meets quality bar |
| Payments | Stripe Connect | Marketplace splits, subscription management, SCA-compliant |
| Storage | MinIO (S3-compatible) | Agent files, logs, outputs — self-hosted on Paweł's servers |
| Containerization | Docker + Compose → K8s | Agent sandboxing requires containers; scale to K8s when needed |
| Monitoring | Prometheus + Grafana | System metrics, agent performance, revenue dashboards |
| Reverse Proxy | Nginx | TLS termination, rate limiting, static file serving |
| Search | Meilisearch | Agent discovery, full-text search, faceted filtering |

AI Model Strategy (LiteLLM routing rules):
- Market scanning/NLP: gemini-flash (~$0.0001/1k tokens — cheapest)
- Agent specification generation: claude-sonnet-4-6 (best structured output)
- Code generation: gpt-4o or claude-sonnet-4-6 (A/B tested)
- Marketing copy generation: claude-haiku-4-5 (fast, cheap)
- Quality evaluation: claude-sonnet-4-6 (most reliable judgment)

2. System Architecture — Component Overview

``
┌─────────────────────────────────────────────────────────────┐
│ EXTERNAL WORLD │
│ Reddit Twitter HN ProductHunt Google Trends Forums │
└──────────────────┬──────────────────────────────────────────┘
│ scraping
▼
┌─────────────────────────────────────────────────────────────┐
│ MARKET INTELLIGENCE LAYER (MIL) │
│ Scrapers → NLP Clustering → Opportunity Scoring → Queue │
└──────────────────┬──────────────────────────────────────────┘
│ opportunities
▼
┌─────────────────────────────────────────────────────────────┐
│ META-AGENT ENGINE (MAE) │
│ Spec Generator → Code Generator → Tester → Quality Scorer │
└──────────────────┬──────────────────────────────────────────┘
│ validated agents
▼
┌─────────────────────────────────────────────────────────────┐
│ AGENT RUNTIME ENVIRONMENT (ARE) │
│ Docker Sandbox → API Wrapper → Usage Metering → Health │
└──────────────────┬──────────────────────────────────────────┘
│ live agents
▼
┌─────────────────────────────────────────────────────────────┐
│ MARKETPLACE │
│ Listings → Search → Reviews → Pricing → Purchase Flow │
└──────────────────┬──────────────────────────────────────────┘
│ transactions
▼
┌─────────────────────────────────────────────────────────────┐
│ PAYMENT SYSTEM │
│ Stripe Connect → Rev-Share (80/20) → Subscriptions │
└──────────────────┬──────────────────────────────────────────┘
│ performance data
▼
┌─────────────────────────────────────────────────────────────┐
│ ANALYTICS & OPTIMIZATION │
│ Revenue Tracking → Agent Performance → MAE Feedback Loop │
└─────────────────────────────────────────────────────────────┘
`

3. Component Deep-Dives

3.1 Market Intelligence Layer (MIL)

Purpose: Identify what agents people need before they know they need them.

Data Sources:
- Reddit: /r/entrepreneur, /r/smallbusiness, /r/automation, /r/SaaS, /r/MachineLearning
- Twitter/X: AI agent discussions, tool requests, frustration tweets
- Hacker News: "Ask HN" posts, Show HN failures, comment sections
- ProductHunt: New launches, upvotes, comment questions
- Google Trends: Rising queries in "AI", "automation", "agent" clusters
- Indie Hackers: Problem threads, failed products (identify gaps)

Processing Pipeline:
`
Raw text → Clean/normalize → Extract problem statements (LLM) →
Cluster similar problems → Score by: frequency + urgency + monetization potential →
Generate "Agent Opportunity Card" → Push to MAE queue
`

Agent Opportunity Card (JSON):
`json
{
"opportunity_id": "uuid",
"problem": "SaaS founders need to manually track competitor pricing daily",
"target_market": "B2B SaaS founders",
"willingness_to_pay_signal": "high (saves 2h/day)",
"estimated_market_size": "50k potential customers",
"agent_type": "monitoring",
"suggested_features": ["competitor tracking", "price change alerts", "weekly reports"],
"sources": ["reddit post urls", "twitter threads"],
"opportunity_score": 8.4,
"created_at": "2026-02-24T12:00:00Z"
}
`

Scanning Schedule: Every 4 hours. Redis job queue prevents duplicate scanning.

3.2 Meta-Agent Engine (MAE)

Purpose: Convert Opportunity Cards into production-ready, marketplace-listed agents. Zero human involvement.

Pipeline (5 stages):

Stage 1: Specification Generation

`yaml


Example AgentSpec

Pricing Algorithm:
`python
base_price = 29 # $29/month baseline
multipliers = {
"b2b": 1.5, # businesses pay more
"saves_time": 1.3,
"niche": 0.8, # smaller market = lower price
"competitive": 0.9 # if similar agents exist
}
final_price = base_price * product(applicable_multipliers)


Range: $9 - $199/month

Architecture:
- Each agent runs in its own Docker container
- Resource limits: 512MB RAM, 0.5 CPU cores, 30s timeout (configurable)
- Network policy: egress allowed to approved APIs only (no arbitrary internet access by default)
- Each agent gets a unique subdomain: {agent-slug}.agents.mam.io
- Execution via Kubernetes Jobs (ephemeral) or Deployments (always-on)

API Contract (every agent must implement):
`
POST /run → execute agent, returns job_id
GET /status/{id} → check job status + result
GET /schema → agent input/output schema (OpenAPI)
GET /health → liveness check
GET /metrics → usage stats (Prometheus format)
`

Usage Metering:
- Every /run call logged: user_id, agent_id, tokens_used, duration, timestamp
- Metering data → Redis → PostgreSQL (async flush every 60s)
- Billing triggers on metered usage or subscription

Security Model:
- JWT authentication on every endpoint
- Rate limiting: 100 req/min per user (Redis sliding window)
- Container network isolation (separate Docker network per agent)
- Secrets management: Vault or environment injection (never in code)
- Input sanitization before LLM calls (prompt injection prevention)

3.4 Marketplace Platform

Discovery & Search:
- Meilisearch for fast full-text + faceted search
- Facets: category, price range, rating, AI model used, tags
- Ranking: relevance × quality_score × sales_volume × recency
- Featured/trending sections (auto-updated by analytics)

Agent Listing Page includes:
- Name, description, use cases (3-5 bullet points)
- Live demo widget (runs agent with sample input, no auth required)
- Pricing (monthly subscription or one-time)
- Quality score badge
- User reviews and ratings (1-5 stars)
- API documentation (auto-generated from schema)
- "Created by AI" badge (transparency — competitive differentiator)
- Version history

Purchase Flow:
`
Browse → Demo → Select plan → Stripe Checkout →
Payment success → API key issued → Agent deployed to user namespace →
Onboarding email → Dashboard access
`

3.5 Payment System

Stripe Connect (Express accounts model):
- Platform account: MAM Ltd (Gibraltar)
- Revenue split per transaction: 80% → Agent Creator Pool, 20% → MAM
- For AI-created agents: 100% → MAM (no human creator)
- For human-created agents: 80% → human creator Stripe account

Subscription Plans:

| Tier | Price | Agents | Runs/month | Support |
|------|-------|--------|------------|---------|
| Starter | $29/mo | 1 agent | 500 runs | Community |
| Pro | $79/mo | 5 agents | 5,000 runs | Email |
| Business | $249/mo | 20 agents | 50,000 runs | Slack |
| Enterprise | Custom | Unlimited | Unlimited | Dedicated |

Platform Revenue Model:
1. 20% commission on all agent sales (primary)
2. Subscription overage fees ($0.10/run beyond plan limits)
3. Premium listing / featured placement ($99-499/month for human creators)
4. Enterprise private marketplace ($999-9,999/month)
5. Meta-Agent-as-a-Service (run your own meta-agent: $199/month)

3.6 Analytics & Optimization

Dashboards (Grafana):
- Revenue: MRR, ARR, churn, LTV, CAC
- Agent performance: success rate, avg response time, user retention per agent
- Market intelligence: opportunities identified, agents generated, success rate
- Infrastructure: CPU, memory, API latency, error rates

Feedback Loops:
`
Agent performance data → MAE optimization →
Better specs → Better agents → Higher quality scores →
Higher conversion → More revenue → More data → loop
`

A/B Testing:
- Pricing strategies (per agent)
- Agent descriptions
- Demo inputs (what shows best value)
- Email sequences

4. Database Schema

`sql
-- Users
CREATE TABLE users (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
email VARCHAR(255) UNIQUE NOT NULL,
password_hash VARCHAR(255),
role VARCHAR(50) DEFAULT 'buyer', -- buyer, creator, admin
stripe_customer_id VARCHAR(255),
stripe_account_id VARCHAR(255), -- for creators
created_at TIMESTAMPTZ DEFAULT NOW(),
last_seen_at TIMESTAMPTZ
);

-- Agents (marketplace listings)
CREATE TABLE agents (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
creator_id UUID REFERENCES users(id), -- NULL if AI-created
name VARCHAR(255) NOT NULL,
slug VARCHAR(255) UNIQUE NOT NULL,
description TEXT,
short_description VARCHAR(500),
category VARCHAR(100),
tags TEXT[],
price_monthly DECIMAL(10,2),
price_one_time DECIMAL(10,2),
status VARCHAR(50) DEFAULT 'draft', -- draft, testing, published, deprecated
quality_score DECIMAL(3,1),
docker_image VARCHAR(500),
agent_spec JSONB,
version VARCHAR(20) DEFAULT '1.0.0',
is_ai_created BOOLEAN DEFAULT TRUE,
total_sales INTEGER DEFAULT 0,
avg_rating DECIMAL(3,2),
created_at TIMESTAMPTZ DEFAULT NOW(),
published_at TIMESTAMPTZ,
updated_at TIMESTAMPTZ DEFAULT NOW()
);

-- Agent Versions (immutable history)
CREATE TABLE agent_versions (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
agent_id UUID REFERENCES agents(id),
version VARCHAR(20) NOT NULL,
docker_image VARCHAR(500),
agent_spec JSONB,
changelog TEXT,
created_at TIMESTAMPTZ DEFAULT NOW()
);

-- Subscriptions
CREATE TABLE subscriptions (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
user_id UUID REFERENCES users(id),
agent_id UUID REFERENCES agents(id),
stripe_subscription_id VARCHAR(255) UNIQUE,
plan VARCHAR(50),
status VARCHAR(50), -- active, canceled, past_due
current_period_start TIMESTAMPTZ,
current_period_end TIMESTAMPTZ,
created_at TIMESTAMPTZ DEFAULT NOW(),
canceled_at TIMESTAMPTZ
);

-- Agent Runs (usage metering) — partitioned by month
CREATE TABLE agent_runs (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
agent_id UUID REFERENCES agents(id),
user_id UUID REFERENCES users(id),
subscription_id UUID REFERENCES subscriptions(id),
status VARCHAR(50),
input JSONB,
output JSONB,
error TEXT,
tokens_used INTEGER,
duration_ms INTEGER,
cost_usd DECIMAL(10,6),
created_at TIMESTAMPTZ DEFAULT NOW(),
completed_at TIMESTAMPTZ
) PARTITION BY RANGE (created_at);

-- Market Intelligence
CREATE TABLE market_opportunities (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
problem TEXT NOT NULL,
target_market VARCHAR(255),
opportunity_score DECIMAL(3,1),
sources JSONB,
status VARCHAR(50) DEFAULT 'pending',
agent_id UUID REFERENCES agents(id),
created_at TIMESTAMPTZ DEFAULT NOW()
);

-- Generation Jobs
CREATE TABLE generation_jobs (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
opportunity_id UUID REFERENCES market_opportunities(id),
status VARCHAR(50) DEFAULT 'queued',
agent_spec JSONB,
test_results JSONB,
quality_score DECIMAL(3,1),
attempts INTEGER DEFAULT 0,
error TEXT,
agent_id UUID REFERENCES agents(id),
started_at TIMESTAMPTZ,
completed_at TIMESTAMPTZ,
created_at TIMESTAMPTZ DEFAULT NOW()
);

-- Reviews
CREATE TABLE reviews (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
agent_id UUID REFERENCES agents(id),
user_id UUID REFERENCES users(id),
rating INTEGER CHECK (rating BETWEEN 1 AND 5),
review_text TEXT,
is_verified_purchase BOOLEAN DEFAULT FALSE,
created_at TIMESTAMPTZ DEFAULT NOW()
);

-- Revenue Events
CREATE TABLE revenue_events (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
type VARCHAR(100),
user_id UUID REFERENCES users(id),
agent_id UUID REFERENCES agents(id),
amount_usd DECIMAL(10,2),
platform_revenue_usd DECIMAL(10,2),
creator_revenue_usd DECIMAL(10,2),
stripe_event_id VARCHAR(255) UNIQUE,
created_at TIMESTAMPTZ DEFAULT NOW()
);
`

5. API Endpoints

Public Endpoints

prometheus:
image: prom/prometheus:latest
``

8. Security Architecture

Authentication

API Security

Agent Execution Security

Data Security

9. Monitoring & Alerting

Key Metrics

Business Metrics:
- MRR / ARR (real-time)
- New subscriptions today
- Churn rate (7-day, 30-day)
- Agent generation success rate
- Marketplace conversion rate

Technical Metrics:
- API p50/p95/p99 latency
- Agent execution success rate
- LLM API costs per day
- Container resource utilization
- PostgreSQL query performance

Alerts:
- API error rate > 5% → immediate
- Agent execution failure rate > 20% → immediate
- Stripe webhook failures → immediate
- LLM API cost anomaly (> 2x daily avg) → warning
- DB connection pool exhausted → immediate

10. MVP Scope (Phase 1 — Weeks 1-4)

Must Have

Not In MVP (Phase 2+)

11. Key Architectural Decisions

| Decision | Choice | Rationale |
|----------|--------|-----------|
| Backend language | Python | LLM library ecosystem; faster MAE development |
| Agent code generation | Template-first + LLM gaps | Reliability > novelty; reduces hallucination risk |
| Pricing model | Revenue share 20% | Industry standard; aligns incentives |
| Agent execution | Docker containers | Isolation, portability, existing tooling |
| Human creators | Phase 2 | Avoids cold-start problem; AI agents fill catalog first |
| Crypto payments | Phase 2 | Stripe covers 95% of market; complexity not worth it now |
| Vertical focus | Customer support first | Proven demand, clear success criteria, containable scope |
| AI transparency | "Created by AI" badge | Differentiator, not liability; builds trust |
| Decentralized model | No | Adds crypto complexity; regular SaaS faster to $100M |

12. Timeline to Revenue

| Week | Milestone |
|------|-----------|
| 1 | Backend skeleton: FastAPI + DB + auth |
| 2 | MAE pipeline: first AI-generated agent deployed |
| 3 | Frontend: marketplace listing + demo widget |
| 4 | Payments: Stripe integration + subscription flow |
| 5 | End-to-end: customer subscribes, uses agent |
| 6 | Landing page + waitlist → Beta launch |
| 7-8 | First 10 paying customers, iterate |
| 9-12 | Scale MAE to 50+ agents, growth marketing |

Path to $100M ARR:
- 20% margin on agent sales → need $500M GMV
- Network effects + meta-agent flywheel drive growth
- Q4 2026 target: 50,000 users × $167/mo avg = $100M ARR

Architecture designed for fully autonomous operation. No human intervention required after initial deployment. The meta-agent flywheel is the moat.