Viaduct: A Living C4 Model for Teams and AI Agents

Introduction

Viaduct is a self-hosted, browser-based tool designed to maintain a living C4 model of your software architecture. Unlike static diagramming tools that result in stale screenshots, Viaduct creates a single source of truth where systems, services, and API contracts are modeled dynamically. This model is accessible to human teams and AI agents via an MCP server, enabling real-time architectural queries and automated workflows.

Benefits

Viaduct offers several key advantages for teams managing complex software systems. First, it provides four levels of abstraction in one model. These levels include System Context, Containers, Components, and Code. They are not separate diagrams but views of the same underlying model. This ensures consistency. Renaming a service or adding a dependency automatically updates it across all levels. This eliminates the need to synchronize multiple static images.

Second, the tool uses intelligent notation. It automatically assigns colors and logos to elements based on the technology stack they represent. Datastores are rendered as cylinders, people as actors, and so on. This visual consistency allows diagrams to be scannable before anyone reads the labels, providing immediate context.

Third, every element in the model carries its own Markdown pages. Users can attach design notes, runbooks, and Architecture Decision Records directly to services or workers. The editor supports live previews, allowing users to insert stored sequence diagrams or API endpoints as blocks. This ensures documentation remains current, avoiding the issue of screenshots that become outdated over time.

Fourth, Magic Flows allow users to visualize request paths across the modeled architecture. Flows are built from existing model elements, requiring no second diagram to maintain. Users can play the flow on the canvas, where the camera follows the request hop-by-hop, dimming inactive elements. Sequence diagrams can be generated directly from these flows and attached to the relevant documentation.

Fifth, endpoints are stored as real OpenAPI specifications rather than static labels. Users can describe endpoints in the editor with typed parameters, request bodies, and status cards. The tool supports importing OpenAPI specs to populate the canvas and exporting them back as JSON files. This ensures that the architecture model is readable by machines, not just humans.

Sixth, Viaduct integrates with Figma to bring design systems into the architecture model. Frames drawn in Figma become part of the architecture, with components pointing to real nodes. Design values like colors, spacing, and type are read from the Figma file rather than being retyped. The tool alerts users when design frames are edited, indicating which components are now behind version mismatches. AI agents can read these design constraints to build loading and error states accurately.

Seventh, a built-in assistant helps teams without dedicated agents handle documentation gaps. It suggests descriptions for elements lacking them. It reviews the whole model to identify undescribed elements, unused connections, or duplicate services. It suggests names for unnamed steps in Magic Flows. Suggestions are never applied automatically. Users must review and accept changes via a button.

Eighth, change sets allow teams to review architecture modifications similarly to code reviews. A change set is scoped to a pinned version, ensuring nothing shifts while an agent works on it. It reports finished pieces with the criteria they prove and the commit that validates them, moving status from draft to done automatically.

Use Cases

Viaduct is ideal for software teams that need to keep their architecture documentation accurate and up to date. It is useful for teams that want to integrate AI agents into their development workflow. Agents can query the model to answer questions about what systems talk to each other and over which contracts. Agents can also write back to the model, adding new services, endpoints, connections, and documentation.

Teams can use Viaduct to visualize request paths and understand how different parts of their system interact. This is helpful during planning sessions or when debugging complex issues. The tool is also great for maintaining design consistency. By linking Figma frames to the architecture model, teams ensure that their UI designs match their backend structures. This reduces errors and saves time on manual updates.

Developers can use the embedded documentation to access runbooks and design notes directly from the diagram. This makes it easier to onboard new team members or understand the rationale behind specific architectural decisions. The ability to export models as JSON and endpoints as OpenAPI documents makes it easy to share data with other tools or teams.

Pricing

Viaduct is free to use. There are no trials that expire or features held back behind a paywall. While users can donate to support the project, no features are gated by payment. The AI assistant is included with an account, providing a monthly allowance per person, with no keys to obtain or configuration required.

Vibes

The tool prioritizes user control over architectural data. Without an account, the model never leaves the user's browser. With an account, models live on servers in the Netherlands, with backups stored in the same region. The entire model can be exported as JSON, and container endpoints as OpenAPI documents at any time. There are no one-way locks. Users can draw and use the tool entirely offline in their browser. An account is only required for collaboration, cross-device persistence, and MCP serving.

Additional Information

Viaduct transforms architecture documentation from a static, often neglected task into a dynamic, living model. By combining C4 modeling with modern AI integration and strict data privacy controls, it enables teams to maintain accurate architectural maps that serve both human collaboration and automated agent workflows.