Home/Docs/Architecture

Architecture

mendapi is three independently useful layers connected by one SQLite database and plain JSON files. Each layer is independently verifiable, and the whole stack runs on Node.js built-ins alone — zero npm dependencies, zero network by default, mechanically enforced by the test suite.

The three layers

shell

  upstream providers (SDK release feeds / changelogs / OpenAPI specs)
        |
        v
  +---------------------------------------------------------+
  | 1. CHANGE INTELLIGENCE                                    |
  |    watcher / specdiff / specingest  ->  SQLite change DB  |
  |    (the only layer that ever touches the network,         |
  |     and only when you run 'mendapi sync')                 |
  +---------------------------------------------------------+
        |  local SQLite database (app/data)
        v
  +---------------------------------------------------------+
  | 2. SCANNER                                                |
  |    scan: change DB x your repo -> impact.json             |
  |    deps: repo -> provider x API-surface inventory         |
  |    review: verdicts on medium-confidence findings         |
  |    (local, read-only, zero network code)                  |
  +---------------------------------------------------------+
        |  impact.json (versioned schema)
        v
  +---------------------------------------------------------+
  | 3. FIXER                                                  |
  |    fix: deterministic migration packs -> unified diff     |
  |    llmfix: BYO-LLM draft patches for the long tail        |
  |    revalidate: pack staleness audit                       |
  |    pr: local branch + PR description (push is opt-in)     |
  +---------------------------------------------------------+

Layer 1 — Change Intelligence

The watcher pulls provider SDK release feeds and official changelog feeds into a local SQLite database; the spec-diff engine compares two versions of a provider's OpenAPI document directly and records endpoint-level breaking changes even when the vendor's prose changelog omits them. Every change row carries a provider, a classified change type, and the source URL it was observed at. Classification is deterministic (rule-based) — anything that cannot be classified stays unknown rather than being guessed.

Layer 2 — Scanner

The scanner joins the change database against your repository: static analysis only, evidence-gated findings with file-and-line usage sites, and a confidence tier per finding. deps inverts the question — instead of "which changes hit me" it inventories "which provider API surfaces does this repo touch", which is what makes precise change subscription possible. Neither module contains network code; the test suite fails if a network primitive ever appears in them.

Layer 3 — Fixer

Deterministic migration packs rewrite known breaking-change patterns and emit a unified diff that git apply accepts cleanly; every pack is regression-locked against gold fixture repos (must apply, must be idempotent, must leave migrated and unrelated code byte-identical). Packs record the upstream state they assume, and revalidate refuses to let a pack rot silently when the same API surface changes again. The long tail beyond deterministic rules goes to llmfix with your own LLM key — drafts only, never auto-applied.

Data flow contracts

One database. All change intelligence lives in a single local SQLite file; every downstream command reads it, only sync writes to it from the network.
Versioned JSON between layers. scan → fix hand-off is a plain impact.json with a top-level schema_version; agents and CI pin to it. No layer parses another layer's terminal output.
Escalation ladder for trust. deterministic pack → LLM draft (BYO key, preview only) → human. Automation never crosses a trust boundary implicitly: fix is dry-run by default, pr never pushes without --push.
Single egress points. Exactly one module may perform LLM traffic and it loads only on the opt-in path; hosted reporting goes through one whitelist-constructed payload builder. See the security model.

Module map

Generated from the shipped app/ directory at docs build time — 17 modules, summaries taken from each file's own header comment.

Layer 1 — Change Intelligence

Module	Responsibility
`app/fixability.js`	mendapi fixability — applies LLM-reviewed fixability verdicts to the changes table. Zero npm dependencies: node:sqlite. Zero network.
`app/reclassify.js`	mendapi reclassify — applies LLM-reviewed classifications to the changes table. Zero npm dependencies: node:sqlite.
`app/specdiff.js`	mendapi specdiff — deterministic OpenAPI spec diff engine. Zero npm dependencies: node:fs only. Zero network — reads local files.
`app/specingest.js`	mendapi specingest — load OpenAPI spec-diff records into the changes DB.
`app/watcher.js`	mendapi watcher — collects upstream API change events into SQLite. Zero npm dependencies: node:sqlite + global fetch.

Layer 2 — Scanner

Module	Responsibility
`app/deps.js`	mendapi deps — per-repo API dependency inventory (provider x API surface x location). Zero npm dependencies, zero network. Answers: "which vendors' API surfaces does
`app/review.js`	mendapi review — LLM confidence review layer for impact reports. Zero npm dependencies, zero network calls (D3: no default egress).
`app/scanner.js`	mendapi scanner — scans a codebase for usage impacted by upstream API changes. Zero npm dependencies: node:sqlite + node:fs.

Layer 3 — Fixer

Module	Responsibility
`app/fixer.js`	mendapi fixer — applies migration rules for known upstream API breaking changes and emits a reviewable patch (unified diff) plus a fix report.
`app/llmfix.js`	mendapi llmfix — BYO-compute draft fix generator for long-tail changes. Zero npm dependencies. This command is the fixer-side counterpart of
`app/pr.js`	mendapi pr — turns a fixer migration into a reviewable git branch, commit, and PR-ready description. Zero npm dependencies: node:child_process
`app/revalidate.js`	mendapi revalidate — migration pack staleness audit. Zero npm dependencies, zero network (reads only the local change DB).

Entry points & shared infrastructure

Module	Responsibility
`app/cli.js`	mendapi — Dependabot, but for every API you depend on. Single entry point for npx: dispatches subcommands to the component CLIs.
`app/llmprovider.js`	llmprovider.js — Provider-agnostic LLM interface for BYO compute. Zero npm dependencies. This module BUILDS requests only — it performs no
`app/llmtransport.js`	llmtransport.js — the ONLY module in mendapi that may send LLM traffic. Zero npm dependencies. Explicitly opt-in: nothing in mendapi imports this
`app/mcp.js`	mendapi mcp — Model Context Protocol server over stdio (JSON-RPC 2.0, newline-delimited messages). Zero npm dependencies, zero network code:
`app/payload.js`	payload.js — Upload payload builder for hosted reporting (schema + sanitizer).

Why zero dependencies

A tool that audits your supply-chain exposure should not be supply-chain exposure. The entire runtime is Node.js built-ins (node:sqlite, node:fs, node:child_process); a security review of mendapi's dependency tree is the Node.js release notes. It also keeps npx mendapi scan honest: no install step, no postinstall scripts, nothing to typosquat.

PreviousSecurity model NextGlossary

Pre-release documentation, generated from the mendapi codebase. Command output and pack listings reflect the shipped CLI exactly.