Architecture — Mimic Docs

System Overview

textarchitecture

┌──────────────────────────────────────────────────────────┐
│                        CLI Layer                          │
│   mimic init │ mimic run │ mimic seed │ mimic host        │
└─────────────────────────┬────────────────────────────────┘
                          │
             ┌────────────┼────────────┐
             │            │            │
             v            v            v
  ┌──────────────┐ ┌────────────┐ ┌────────────┐
  │  Blueprint   │ │ Mock Server│ │  Database  │
  │              │ │            │ │  Adapters  │
  │ Persona load │ │ Fastify    │ │            │
  │ LLM Engine   │ │ Adapters   │ │ Postgres   │
  │ Expander     │ │ State store│ │ MySQL      │
  └──────────────┘ └──────┬─────┘ │ MongoDB    │
                    ┌─────┴─────┐  │ SQLite     │
                    │           │  └─────┬──────┘
                    v           v        v
             ┌────────────┐ ┌────────┐  Real databases
             │  API Mock  │ │  MCP   │
             │  Adapters  │ │Servers │
             │            │ │        │
             │ OpenAPI    │ │per-    │
             │ spec →     │ │adapter │
             │ codegen →  │ │(stdio/ │
             │ CRUD +     │ │ HTTP)  │
             │ overrides  │ │        │
             └────────────┘ └────────┘

Data Flow

Seeding flow

text

mimic seed
  │
  ├─ Load persona blueprint from .mimic/blueprints/{persona}.json
  │
  ├─ For each configured database adapter:
  │   ├─ Connect to database
  │   ├─ Map blueprint data to table schemas
  │   ├─ INSERT/COPY rows (FK-aware ordering)
  │   └─ Report: "Seeded 42 rows across 5 tables"
  │
  └─ Done (API mocks seed lazily on first request)

Request flow (API mock)

text

Agent sends: GET /stripe/v1/customers?email=alex@example.com

Mock Server (Fastify, port 4101)
  ├─ Route matched: /stripe/* → StripeAdapter (OpenApiMockAdapter)
  ├─ Generated CRUD scaffolding (617 routes from OpenAPI spec)
  │   ├─ Seed ExpandedData into StateStore on first request
  │   ├─ Check override map — use custom handler if registered
  │   ├─ Otherwise auto-handle: list (cursor pagination), create,
  │   │   retrieve, update, delete
  │   ├─ Default factories enrich responses with spec-faithful defaults
  │   └─ reply.send({ object: "list", data: [...], has_more: false })
  └─ Response returned to agent

MCP flow

text

Agent calls MCP tool: list_customers({ email: "alex@example.com" })

MCP Server (@mimicai/adapter-stripe, port 4201/mcp)
  ├─ Validate params with Zod schema
  ├─ Translate to HTTP:
  │   GET http://localhost:4101/stripe/v1/customers?email=alex@example.com
  ├─ Parse response
  ├─ Format for agent: "Customers (1):\n• cus_abc — Alex (alex@example.com)"
  └─ Return MCP response

Cross-Surface Consistency

The Blueprint Engine’s core differentiator. When it generates data for persona “Alex”, the same Alex appears across all surfaces:

PostgreSQL users table has Alex with ID user_001
Plaid API returns bank accounts owned by user_001
Stripe API returns payment history for user_001’s card
Chargebee API shows Alex’s subscription and invoices

Achieved through a two-phase process:

Phase 1: Persona Generation — LLM creates a detailed persona with relationships, financial profile, work context
Phase 2: Deterministic Expansion — Rules engine expands into concrete data with shared identifiers, consistent timestamps, and correlated values

Package Dependency Graph

text

@mimicai/cli
  ├── @mimicai/core
  │     ├── adapter system, state store, mock server
  │     ├── blueprint engine, persona generation, expander
  │     └── schema parsing (prisma-ast, pgsql-parser)
  ├── @mimicai/adapter-sdk
  │     ├── BaseApiMockAdapter, OpenApiMockAdapter
  │     └── StateStore, buildTestServer, generateId
  ├── @mimicai/blueprints
  │     └── pre-built persona blueprints (JSON)
  │
  ├── Database adapters (shipped)
  │     ├── @mimicai/adapter-postgres
  │     ├── @mimicai/adapter-mongodb
  │     ├── @mimicai/adapter-mysql
  │     └── @mimicai/adapter-sqlite
  │
  └── API mock adapters (shipped, each includes MCP server)
        ├── @mimicai/adapter-stripe
        ├── @mimicai/adapter-plaid
        ├── @mimicai/adapter-paddle
        ├── @mimicai/adapter-chargebee
        ├── @mimicai/adapter-gocardless
        ├── @mimicai/adapter-lemonsqueezy
        ├── @mimicai/adapter-recurly
        ├── @mimicai/adapter-revenuecat
        └── @mimicai/adapter-zuora

Each API adapter contains:
  ├── adapter.json         — identity, basePath, versions, spec URL
  ├── scripts/*-codegen.ts — OpenAPI spec → generated TypeScript
  ├── src/generated/       — routes.ts, schemas.ts, resource-specs.ts, meta.ts
  ├── src/overrides/       — state-machine handlers (confirm, capture, etc.)
  ├── src/*-adapter.ts     — OpenApiMockAdapter implementation
  ├── src/mcp.ts           — registerTools() + startMcpServer()
  └── src/bin/mcp.ts       — standalone binary entry point

Shared peer deps across adapters:
  ├── @mimicai/adapter-sdk
  ├── @modelcontextprotocol/sdk
  ├── fastify
  └── zod