Architecture

Mushi Mushi is intentionally boring at the seams: a Hono gateway in front of Supabase, more than 70 edge functions behind it (pnpm docs-stats prints the current count), and three data substrates (relational + vector + graph) that mirror each other for their respective query shapes. Everything an SDK does is one POST to the gateway; everything a contributor adds is either a route or a function.

Wire-level flow

The four columns below correspond to the four “layers” of the stack — left-to-right is the path a single bug report takes from a user’s device to a merged PR.

Edges that matter (everything else flows top-to-bottom inside a column):

• Every SDK posts to api — there is no client-direct DB write.
• api → fast-filter → classify-report is the canonical ingest path.
• classify-report → pgvector + Apache AGE + plugins happens in parallel.
• judge-batch reads from and writes back into classify-report’s prompts.
• fix-worker → GitHub dispatches automatically when autofix is enabled and the estimated cost is under the project’s budget; it pauses for a console approval only when that cost exceeds autofix_approval_cost_threshold_usd.
• pdca-runner orchestrates fix-worker autonomously — one PDCA run may spawn multiple fix-worker calls.
• drift-walker → contract-graph-builder compares a fresh crawl against the stored contract_snapshots baseline.
• api → Supabase Vault resolves BYOK secrets per-request, never cached.
• All LLM-touching functions stream traces to Langfuse.

Component summary

• Edge gateway (api, Hono on Supabase Edge Functions) authenticates with API keys (public SDK reports) or JWT (admin console), enforces rate limits, and routes to specialised functions. All admin routes live under /v1/admin/*.
• fast-filter triages high-volume garbage (form spam, duplicate one-liners) with the cheapest model the project’s BYOK plan permits.
• classify-report is stage 2 of the classifier. Stage 1 (fast-filter) reads the scrubbed report and extracts structured symptoms; stage 2 sees only that structured output (an air gap against prompt injection) and writes the root cause, repro steps and fix direction. When a screenshot is present, a separate image-only vision call runs afterwards and can annotate the report but not change its diagnosis.
• judge-batch is a nightly cron that scores classifier accuracy with a separate judge call, feeding the prompt-A/B framework that promotes a candidate prompt after 30 evaluations when its mean score is more than 5% higher.
• fix-worker dispatches approved triage decisions to a sandboxed LLM agent (Anthropic / OpenAI BYOK) that generates code patches, validates them against a Zod schema, and opens a draft PR via the GitHub App, or dispatches a Cursor or GitHub cloud agent that opens the PR itself. Validation failures include Zod issue detail in fix_attempts.error for debugging.
• agent-pr-review reviews each fix PR with Claude Opus on the project’s own Anthropic key and stores a merge / fix_first / hold verdict. A merge verdict on the PR’s current commit marks the draft ready so your CI runs; with no review possible, a fix-worker draft falls back to its own self-check.
• review-followup sends a “fix first” verdict’s findings back to a new cloud agent on the same PR (off by default), and asks it to repair CI when an approved PR fails on its own code.
• fix-verifier checks the merge gates for a PR’s head (review, CI, the Mushi Mushi verify check, no weakened tests, diff size, a second-model review) and, only when the project turns on verified auto-merge, merges it.
• merge-queue merges PRs a person queued with “Merge when ready”, one per repo at a time, or batches approved PRs into a release-train PR.
• Local workers (mushi work --daemon) let your own machine claim reports, follow-ups, merge conflicts or audits under a lease, so the cloud and your machine never work on the same report at once.
• pdca-runner orchestrates autonomous Plan → Do → Check → Act cycles: crawls a target URL, identifies issues, calls fix-worker for each, verifies the result, and writes per-run + per-iteration records to pdca_runs.
• drift-walker fetches the live app (using contract-graph-builder) and diffs the result against the stored contract_snapshots baseline, writing drift_findings. Errors (builder failed or unreachable, snapshot not found) come back with a plain message and show in the Drift scanner UI.
• contract-graph-builder builds a contract snapshot from three sources: the project’s OpenAPI spec URL, the inventory’s API dependencies, and the latest Supabase schema snapshot from backend-drift-scanner. It stores the result in contract_snapshots and is called by drift-walker before every walk.
• qa-story-runner executes qa_stories records on schedule (pg_cron, every minute) using Firecrawl, Browserbase, or local Playwright. Writes results to qa_story_runs and qa_story_evidence with screenshots.
• intelligence-report generates weekly bug-intelligence digests with optional cross-customer benchmarking (k-anonymity enforced via materialized view). Runs with verify_jwt = false; authenticated via service-role header internally.
• soc2-evidence snapshots five controls nightly as evidence toward SOC 2 (not a certification).
• sdk-upgrade-worker reads a linked GitHub repo’s package.json(s), computes a semver-only bump plan (computeBumpPlan), opens a draft PR via shared createPrFromFiles, and writes status to sdk_upgrade_jobs. Triggered from Connect & Update → Create Upgrade PR or POST /v1/admin/projects/:pid/sdk-upgrade.
• sdk-versions-cron upserts latest stable @mushi-mushi/* versions from npm (daily pg_cron + post-publish sync) into sdk_versions so freshness chips stay accurate between releases.
• skill-sync ingests allowlisted SKILL.md files (default: kensaurus/skills), embeds descriptions, and powers Skill Pipelines (/skills) — attach a skill chain to a report and stream step status over Realtime.

MCP surface (2026)

The same tool catalog ships on two transports:

Catalog source of truth: packages/mcp/src/catalog.ts, mirrored in apps/admin/src/lib/mcpCatalog.ts, guarded by pnpm check:catalog-sync. Destructive tools carry MCP annotations; scope enforcement is mcp:read vs mcp:write.

Connect & Update (console)

/connect consolidates onboarding paths that previously lived across Settings, Onboarding, and MCP:

1. GitHub — prerequisite for upgrade PRs and autofix.
2. SDK install — live snippet + trigger-mode preview (SdkInstallCard).
3. MCP — Add to Cursor deeplink + hosted/stdio snippets (ClientConnectButton).
4. CLI — npm i -g @mushi-mushi/cli@latest.
5. Update center — per-package freshness + Create Upgrade PR (SdkUpgradeCTA).

CLI mirror: mushi connect --wait writes the same artifacts locally (Cursor MCP is wired by default; pass --no-ide to skip).

Knowledge graph

Reports embed into pgvector for semantic dedup. The same edges are mirrored asynchronously into Apache AGE so customers who care about graph queries (e.g. “find all reports touching the same component within a release window”) get true Cypher.

A2A Agent Card

Public discovery endpoints at /.well-known/agent-card and /v1/agent-card expose the agent’s identity, skills, supported A2A version, MCP transport, and auth requirements. Other agents can negotiate with Mushi Mushi without out-of-band config.

Data residency

Each project pins to a region (us / eu / jp). The gateway has 307 Temporary Redirect middleware (regionRouter) for requests that reach the wrong cluster, and the Core SDK can resolve and cache a project’s endpoint in localStorage.

Today there is one production project, in Tokyo (ap-northeast-1). No other regional endpoint is configured, so the middleware never redirects and every region is served there. See Data residency.

Storage

Per-project storage settings (BYO Storage) let you keep screenshots and intelligence-report PDFs in your own S3 / R2 / GCS / MinIO bucket. Supabase Storage is the default.