Skip to content
Local-first · Docker Compose · work in progress

Flip an architecture decision. See what moves.

Your decisions are the plinth your architecture stands on. Point this at a repository: it reads your existing ADRs, RFCs, and design notes, extracts decisions with the passages behind them, and lets you switch a decision’s option to see what the architecture would become.

Try it locallyRead the docs
Architecture map for the event-transport decisionMESSAGINGORDER EVENTSORDER EVENTSPAYMENT RETRIESOrder ServiceSERVICEApache KafkaEVENT STREAMAmazon SQSQUEUEFulfillment ServiceSERVICEPayments ServiceSERVICE
  • Service
  • Event stream
  • Queue
  • Active route
  • Alternative route
  • Unchanged

Decision

Event delivery for food orders

“We chose Apache Kafka because replay and per-order ordering matter more than reducing broker operations.”
“Amazon SQS would reduce infrastructure work. … but replaying a selected range of historical order events would require additional application support.”

Selected option ·Alternative ·docs/decisions/event-transport.md

Simplified from the bundled food-delivery sample (deterministic mock extraction). Quotes are the sample's source text.

What it does

The decision is the domain object. Documents are evidence for it.

  • Reads the Markdown you have

    ADRs, RFCs, design notes, READMEs. No template, no required syntax. Your files stay untouched.

  • Evidence on every inference

    Each extracted claim cites an anchored source passage. Anchors relocate when a passage moves; ambiguous moves become reviewable.

  • Human review outranks the model

    Confirm, reject, or correct claims and aliases. Reviews append to a log you can undo, and survive re-extraction.

  • An architecture map

    Services, datastores, and technologies in a layered layout, with fullscreen. Select a component to read the rationale and open its source.

  • What-if scenarios

    Options are typed deltas over one base graph. Switch options to preview changed entities and edges, affected decisions, and assumptions.

  • Grounded “why” answers

    “Why are we using Kafka?” returns the claims and passages behind the answer, and says so when an answer is not fully grounded.

  • MCP for your agents

    Five read-only tools over HTTP on localhost or stdio: list, search, inspect, and diff scenarios with downstream impact. Results carry a receipt so an agent can tell when they go stale.

  • Portable YAML, disposable indexes

    Canonical data is one validated YAML file per record in .decision/, beside your Markdown. SQLite and Qdrant rebuild from it.

  • Your choice of modelHosted: up next

    Deterministic mock, a local OpenAI-compatible server, or a hosted provider. Hosted providers are not yet tested.

How it works

  1. Markdown

    Discovery reads the repository’s Markdown, skipping generated and hidden folders.

  2. Evidence

    Passages become evidence anchors: source path, heading path, passage hash, context.

  3. Decisions

    Extraction proposes decisions, options, entities, and claims, each citing evidence. You review them.

  4. Map

    The compiler applies the selected options to a base graph and draws the result.

  5. What-if

    Switch an option; the scenario shows what changed and which decisions it touches.

The full pipeline, stage by stage, with the code behind it

An option is a delta, not a copy

- id: option-sqs
  title: Amazon SQS
  evidence: [evidence-sqs-rationale]
  delta:
    base: architecture
    operations:
      - op: add_entity
        entity: {id: entity-sqs, kind: technology, name: Amazon SQS}
      - op: add_relationship
        relationship: {id: edge-events-sqs, from: service-orders,
                       to: entity-sqs, kind: publishes_to}

Inference stays inference

Model output is stored as inferred with evidence and confidence. A human confirmed, rejected, or asserted judgment appends a new record that supersedes it. Nothing is rewritten, so you can always see what the model proposed and what a person decided.

Markdown and .decision/ YAML are canonical. Delete the SQLite and Qdrant indexes and they rebuild from those files.

Works today. Up next.

What the current build does, and the next steps. No dates.

Works today

  • Setup wizard that registers the MCP server with your coding agent
  • One-command demo of the food-delivery sample
  • Markdown discovery with no template; portable .decision/ YAML; rebuildable indexes
  • Mock extraction, plus local OpenAI-compatible models (Qwen3.8, reasoning off, found all 7 sample decisions)
  • Review log with Undo on the Facts page
  • Layered map with fullscreen and What-if previews
  • Architecture log with rationale, why-not reasons, and consequences
  • Scenario diffs with downstream impact, and input receipts on results
  • Capability checks: a What-if switch flags a component left without a capability it requires
  • Grounded “why” answers and five MCP tools (HTTP and stdio)

Up next

  • Test hosted providers (OpenAI, Anthropic)
  • Measure extraction recall on more repositories
  • Extraction beyond the sample, which today uses fixture-tuned mock rules
  • Authentication for remote API and MCP access (loopback-only today)
  • More source formats beyond Markdown
  • Conflict detection beyond same-ID writes
  • Scenario rename, update, and delete

Where each next step stands today

Try it

git clone https://github.com/bcmyguest/switchplinth
cd switchplinth
./scripts/demo.sh

The script builds the images, copies the fictional food-delivery sample into a demo workspace, extracts it with deterministic mock extraction, starts the stack, rebuilds the search indexes, and prints http://localhost:3000. It needs Docker with Compose v2 and curl; no model, credentials, Python, or Node. Run it again with --down to stop, or --purge to remove the stack and the demo workspace.

To use your own repository and register the MCP server with Claude Code, Cursor, VS Code, or Claude Desktop, run uv run switchplinth setup from backend/.

Getting startedConnect a model