{"slug": "viaduct-clickable-integration-flows-on-top-of-a-c4-model", "title": "Viaduct – clickable integration flows on top of a C4 model", "summary": "Viaduct, a free, self-hosted C4 modelling tool, lets teams draw system context, containers, components, and code, attach docs and API contracts to elements, and serve the model to Cursor or Claude Code over MCP. The tool supports four levels, technology-based colouring, Magic flows for request playback, OpenAPI contract storage, and an MCP server with change sets for agent-driven work.", "body_md": "C4 modelling · MCP server · self-hosted\n\n# A C4 model your team maintains and your agents can read\n\nDraw system context, containers, components and code. Attach the docs, sequence diagrams and API contracts to the elements they belong to. Serve the whole thing to Cursor or Claude Code over MCP.\n\nfree · no account · runs in this browser · export any time\n\n01\n\nLevels\n\n## Four levels, one model\n\nOpen a system to see its containers, a container to see its components. Every level is a view of the same model, so a rename or a new dependency shows up everywhere it belongs.\n\n02\n\nNotation\n\n## The technology picks the colour\n\nPick a technology and the element takes its colour and logo. Datastores are drawn as cylinders, people as actors — so a diagram is scannable before anyone reads a label.\n\n03\n\nWhat an element carries\n\n## Docs, diagrams and schemas live on the element\n\nEvery element carries its own Markdown pages — a design note on a service, a runbook on a worker, an ADR on a system. Write in the editor with a live preview, insert a stored sequence diagram or an API endpoint as a block, and the page keeps rendering the current version instead of a screenshot that rotted last quarter.\n\n04\n\nTestimonials\n\n## What teams say once the model is theirs\n\nThe tool earns its place when the diagram stops being a screenshot someone has to remember to update.\n\n05\n\nMagic flows\n\n## A request, played back across the canvas\n\nA Magic flow is an ordered walk through the model: each step names a hop, the elements it goes from and to, and the connection it uses. Steps that happen at the same time share a stage, so a fan-out reads as a fan-out.\n\n- Build a flow from the elements you already modelled — no second diagram to maintain.\n- Play it on the canvas: everything dims except the current hop, and the camera follows the request.\n- Generate a sequence diagram from the flow, and attach the docs and diagrams that explain each step.\n\nPlaying “Payment leaves the bank”, step by step.\n\n06\n\nContracts\n\n## Endpoints are stored as OpenAPI\n\nDescribe an endpoint in the editor — typed parameters, request body, a card per status — and the container holds the OpenAPI document for the whole service. Import a spec to fill the canvas from it; export it back as a file.\n\n```\n{\n  \"openapi\": \"3.1.0\",\n  \"info\": { \"title\": \"Accounts API\", \"version\": \"1.4.0\" },\n  \"paths\": {\n    \"/api/accounts/{id}\": {\n      \"get\": {\n        \"operationId\": \"getAccount\",\n        \"summary\": \"Get account\",\n        \"parameters\": [\n          { \"name\": \"id\", \"in\": \"path\", \"required\": true,\n            \"schema\": { \"type\": \"string\" }, \"example\": \"acc_42\" }\n        ],\n        \"responses\": {\n          \"200\": { \"description\": \"OK\", \"content\": { \"application/json\": {\n            \"example\": { \"id\": \"acc_42\", \"currency\": \"EUR\" } } } },\n          \"404\": { \"description\": \"No account with that id\" }\n        }\n      }\n    }\n  }\n}\n```\n\naccounts-api-openapi.json — exported from a container\n\n07\n\nMCP\n\n## One server, one token, the whole architecture\n\nCursor, Claude Code, Claude Desktop and any other MCP client can read the architecture straight from Viaduct: systems and services, API endpoints with their contracts, WebSocket channels, documentation and sequence diagrams. One hosted MCP server, one personal token, no repository to clone.\n\n- Your agent answers “what talks to what, and over which contract?” from the model instead of guessing from the codebase.\n- It can write back too — new services, endpoints, connections and docs land in the same model your team reads.\n- Hand it a change set: a piece of work pinned to a fixed version, with the constraints and acceptance criteria it has to prove.\n\n[How the MCP server and change sets work](/docs#mcp-cursor)\n\n### Work an agent can finish, and you can verify\n\nA change set is scoped to one pinned version, so nothing shifts under the agent while it builds. It reports each finished piece with the criterion it proves and the commit that proves it — the status moves itself from draft to done, live on your screen.\n\n08\n\nAssistant\n\n## The boring half of documenting, done for you\n\nNot every team keeps an agent of their own, and the parts of a model that go undocumented are the dull ones: descriptions nobody wrote, flow steps still called \"Step 4\". Viaduct's built-in assistant writes those. It is in the editor, it needs no key and no setup, and it never changes your model on its own — every suggestion is shown, and applying it is a button you press.\n\n- A description for any element that lacks one — one at a time, or every blank in a system at once.\n- A review of the whole model: what is undescribed, what nothing talks to, what looks like the same job done twice. Every finding names a real element, and clicking it takes you there.\n- Names for the steps of a Magic flow that nobody got round to naming — written into the draft, so saving is accepting.\n\nIncluded with an account, with a monthly allowance per person. Guests draw; the assistant needs a sign-in.\n\nA review, as it comes back\n\nOrder Service\n\nNo description — nothing says what it is responsible for, and three services depend on it.\n\nNotification Worker\n\nNothing connects to it and it connects to nothing; either the flow is missing or the service is.\n\nLegacy Billing\n\nAppears to do the same job as Billing Service — one of the two is probably the old one.\n\n09\n\nYour data\n\n## Your architecture, on terms you can check\n\nAn architecture model is a map of everything you run, which makes “where does it live?” the first fair question about a tool like this. Three answers, all of them verifiable.\n\n### It stays where you put it\n\nWithout an account the model never leaves your browser. With one it lives on servers in the Netherlands, inside the EU, and so do the backups.\n\n### You can take it with you\n\nThe whole model exports as JSON, and a container’s endpoints as an OpenAPI document — any time, without asking us. Nothing here is a one-way door.\n\n### The agent gets in only if you let it\n\nMCP access needs a personal token you issue yourself, scoped to your projects. Revoke it and the access ends that moment.\n\n10\n\nQuestions\n\n## Answered before you have to ask\n\n### What does it cost?\n\nNothing. Viaduct is free — every level, the MCP server, collaboration and change sets included. There is no trial that ends and no feature held back behind a plan. If you want the work to continue you can donate, and that buys nothing but the work continuing.\n\n### What is the AI assistant, and what does it cost me?\n\nIt writes the parts of a model people leave blank: descriptions for elements that have none, names for unnamed flow steps, and a review of the whole model that points at real elements rather than giving generic advice. It runs on our provider, so there is no key to obtain and nothing to configure, and every account gets a monthly allowance of it. Nothing it suggests is applied on its own — you see the text and press a button, or you do not.\n\n### Do I need an account?\n\nNot to draw. The editor opens with a sample model and works entirely in your browser, where the model stays on your machine and never reaches our servers. An account is for the things a browser cannot do alone: keeping a project across devices, sharing it with your team, and serving it over MCP.\n\n### Where does my architecture live?\n\nOn servers inside the EU, along with the backups. Without an account it lives in your browser and nowhere else. Either way you can export the whole model as JSON, and any container’s contracts as an OpenAPI document, whenever you like.\n\n### What can an AI agent do with it?\n\nRead the model and write to it: Cursor, Claude Code, Claude Desktop or any other MCP client can ask what talks to what and over which contract, and can add services, endpoints, connections and documentation back. Access needs a personal token you issue yourself, scoped to your projects, and revoking it ends the access immediately.\n\n### How is this different from a diagramming tool?\n\nA diagram is a picture; this is a model. An element exists once and appears on every level it belongs to, so a rename or a new dependency shows up everywhere at once. The endpoints on a container are a real OpenAPI document, not labels on a box — which is what makes the whole thing readable by something other than a person.\n\n### Can I bring what I already have?\n\nImport an OpenAPI specification and the endpoints land on the container with their parameters, request bodies and responses. Models export and import as JSON, so moving a workspace — or keeping a copy outside this service — is a file.\n\n11\n\nStart here\n\n## The sample model is already loaded\n\nOpen the editor and an Internet Banking system is waiting, modelled across every level, with docs, flows and contracts attached. Clear it when you want to start your own.", "url": "https://wpnews.pro/news/viaduct-clickable-integration-flows-on-top-of-a-c4-model", "canonical_source": "https://c4.quietgridlabs.com/", "published_at": "2026-09-07 20:17:37+00:00", "updated_at": "2026-09-07 20:32:02.441921+00:00", "lang": "en", "topics": ["developer-tools", "ai-tools", "ai-agents"], "entities": ["Viaduct", "Cursor", "Claude Code", "Claude Desktop", "MCP"], "alternates": {"html": "https://wpnews.pro/news/viaduct-clickable-integration-flows-on-top-of-a-c4-model", "markdown": "https://wpnews.pro/news/viaduct-clickable-integration-flows-on-top-of-a-c4-model.md", "text": "https://wpnews.pro/news/viaduct-clickable-integration-flows-on-top-of-a-c4-model.txt", "jsonld": "https://wpnews.pro/news/viaduct-clickable-integration-flows-on-top-of-a-c4-model.jsonld"}}