CN Diagrams: Architecture Diagrams That Scale With Your System

Every software organization eventually confronts the same uncomfortable question: where is the architecture diagram?

The answer is usually disappointing. There's a Lucidchart from three years ago that nobody updated after the microservices migration. There's a whiteboard photo in Confluence that predates half the current team. There's a Mermaid diagram in a README that shows four services when the system now has forty. The architecture exists in the heads of senior engineers who joined before the last reorg, and getting them in a room together is harder than shipping a feature.

This isn't a tooling problem in isolation – it's a workflow problem. Traditional diagramming tools force a choice between visual flexibility (drag boxes around) and maintainability (code that can be versioned). They impose rigid hierarchies that don't match how systems actually evolve. And they assume a single persona – either the engineer who thinks in code or the product manager who thinks in boxes – when real organizations need both¹.

CN is my attempt to solve this (try it out at CN Diagrams). It's a diagrams-as-code tool that renders interactive architecture diagrams with support for arbitrary levels of encapsulation, provides an intuitive domain specific language (DSL) that engineers can version control, and offers a GUI that non-technical stakeholders can actually use. The goal is a single source of truth that the entire organization can maintain.

The name is a nod to Simon Brown's C4 model, which popularized a hierarchical approach to architecture visualization. C4 stands for Context, Containers, Components, and Code – four levels of abstraction that let you zoom from a 10,000-foot view down to implementation details².

The C4 model was a revelation when I first encountered it. Finally, a structured way to think about architecture diagrams that acknowledged different audiences need different levels of detail! A CTO reviewing system boundaries doesn't need to see individual classes. A developer debugging a service doesn't need to see the marketing website.

But C4's fixed four-level hierarchy started to feel constraining. Real systems don't decompose neatly into exactly four layers. A Kubernetes deployment might have clusters containing namespaces containing deployments containing pods containing containers. An e-commerce platform might have domains containing bounded contexts containing aggregates containing entities. The abstraction depth varies by system, by team, and by what question you're trying to answer.

CN takes the core insight of C4 – hierarchical decomposition with zoom capabilities – and removes the artificial ceiling. The "N" represents arbitrary depth: as many levels of encapsulation as your system requires. Software is infinitely abstractable, and the diagramming tool shouldn't be the limiting factor.

Architecture diagrams are graphs. This sounds obvious, but the implications are profound.

A graph consists of nodes (components) and edges (relationships). When you modify a node, the only things that can possibly be affected are the edges connecting it to other nodes. This locality property is what makes graphs tractable for reasoning about complex systems.

Consider modifying a payment service in a large e-commerce platform. In a well-designed system with clear contracts, you don't need to understand the entire platform to make changes safely. You need to understand:

• The edges into your service (what calls you, with what data)
• The edges out of your service (what you call, with what data)

Everything else is irrelevant to your change. The recommendation engine, the inventory system, the customer support portal – they're all behind the graph's locality boundary. As long as you maintain your contracts (the edge definitions), changes stay contained.

This is why CN renders architectures as force-directed graphs using Cytoscape.js. The visual representation reinforces the mental model: nodes cluster naturally, edges reveal dependencies, and the structure emerges from relationships rather than arbitrary positioning³.

Of course, this only works when organizations invest time and elbow grease in defining, testing, and enforcing contracts between components – ESPECIALLY across bounded contexts…. Depending on the size of your existing system, this may be a significant cultural shift, and rather a lot of work.

But that's precisely the kind of discipline that architecture diagrams should encourage. When you can see that your service has fifteen incoming edges, you might think twice before making a breaking change. And luckily for the overwhelmed, there are ways to bootstrap out of the hardest parts of getting started (7).

The architecture diagramming space splits roughly into two camps, each with significant limitations.

CN provides several capabilities that address the challenges outlined above.

Adopting CN – or any architecture documentation discipline – provides concrete benefits to engineering organizations.

The hardest part of architecture documentation is the initial investment. Mapping an existing system is tedious work, and teams are usually too busy building features to spend hours, let alone weeks, drawing boxes.

This is where AI assistance becomes valuable. LLMs excel at understanding structured code, and CN's DSL is exactly that – structured code. An AI agent can crawl a codebase, identify services and their relationships, and generate an initial CN diagram as a starting point.

The workflow looks like this:

1. Point an agent at your GitHub repository (or local codebase)
2. The agent analyzes directory structure, imports, API calls, and configuration
3. It generates a CN DSL file representing the discovered architecture
4. Engineers review and refine the generated diagram
5. The refined diagram becomes the maintained source of truth

The generated diagram won't be perfect. AI agents make mistakes, and they can only discover relationships that are explicit in code. But a 70% accurate starting point that takes minutes to generate is more useful than a blank canvas that takes weeks to fill. This first-pass strategy lowers the barrier to getting started with architecture documentation.

This bootstrap approach leverages diagrams-as-code in a way that visual tools can't match. You can't ask an AI to drag boxes to the right positions in Lucidchart (at least, not yet). But you can absolutely ask it to generate structured YAML that describes your system's components and relationships. In fact, LLMs are phenomenally good at generating and understanding structured text, and YAML is a great candidate.

CN is open source under the MIT license. The source code is available at github.com/chiply/cn-diagrams.

Architecture diagrams shouldn't be artifacts that exist for compliance or decoration. They should be living documents that help teams understand, communicate about, and evolve their systems.

CN is an attempt to make that practical by removing the barriers that cause architecture documentation to become stale: the rigid hierarchies that don't match real systems, the choice between maintainability and accessibility, and the assumption that only one persona – engineer or non-technical – will maintain the diagram.

Whether or not CN specifically fits your needs, I hope the ideas resonate: graphs as the fundamental model for system relationships, arbitrary encapsulation depth over fixed hierarchies, and dual interfaces that serve different personas working on the same artifact.

Try it at CN Diagrams. Browse the source at github.com/chiply/cn-diagrams. If you build something interesting or have feedback, I'd love to hear about it.

• reddit: CN Diagrams: Architecture Diagrams That Scale With Your System

*tl;dr: CN is a new open-source architecture diagramming tool that bridges the gap between code-based maintainability and visual accessibility. The problem is universal: architecture diagrams become stale because traditional tools force teams to choose between drag-and-drop flexibility (which doesn't version control) and code-based definitions (which non-engineers can't edit). CN extends Simon Brown's C4 model by removing the four-level hierarchy limit – the "N" represents arbitrary depth, letting you zoom from system context down to any level of detail your architecture requires.

Architecture diagrams are fundamentally graphs, and CN embraces this with force-directed layouts that reveal natural clustering and dependencies. This locality property means you only need to understand immediate connections when making changes, not the entire system. Current tools fall into two camps: visual-first options like Lucidchart that don't scale, and code-first options like Mermaid that alienate non-technical users. CN solves this with bidirectional editing – changes in the YAML-based DSL update the visual canvas, and GUI edits update the code.

Key features include hierarchical encapsulation (nodes can contain nodes indefinitely), real-time visualization with no compile step, and example templates for common architectures. The payoff is concrete: faster onboarding as new engineers explore visually, reduced coordination overhead with a single source of truth, explicit dependency analysis through the graph structure, and documentation that actually stays current because it's easy to update.

The bootstrap strategy leverages AI to crawl codebases and generate initial diagrams, lowering the barrier to adoption – a 70% accurate starting point beats a blank canvas. CN is MIT-licensed and built with SvelteKit, Cytoscape.js, and CodeMirror, welcoming contributions from bug reports to pull requests. Try it at the CN Diagrams page or explore the source at github.com/chiply/cn-diagrams.