Backstage vs Archyl: Two Approaches to Architecture Documentation

If you're evaluating tools for architecture documentation, you've probably looked at Backstage. It's open-source, it's backed by Spotify, and it has a plugin ecosystem that covers everything from CI/CD to cost management. One of those plugins handles C4 diagrams.

Archyl takes the opposite approach. It's not a developer portal. It doesn't manage CI pipelines or service catalogs. It does one thing: architecture documentation with the C4 model — and it goes deep on that.

This isn't a "which tool is better" article. They serve different purposes. But if what you actually need is architecture documentation, the differences matter. Let me walk through them.

The Core Philosophy

Backstage is a developer portal framework. Its job is to unify all the tools, services, and documentation a development team uses into a single internal platform. Architecture documentation is one of many plugins available — it's a feature within a larger ecosystem.

Archyl is a purpose-built architecture documentation platform. The entire product exists to model, visualize, analyze, and evolve software architecture using the C4 model. Every feature feeds back into that single purpose.

This difference in scope shapes everything else.

C4 Model Support

Backstage

Backstage's entity model includes Components, APIs, Resources, Systems, Domains, Groups, and Users. This maps loosely to C4 Levels 1 and 2 — systems and containers. But the mapping is approximate, not precise.

The C4 plugin for Backstage (backstage-plugin-c4-model) renders diagrams from the existing catalog entities. It supports System Context and Container views. There is no native support for C4 Level 3 (Components) or Level 4 (Code). If your architecture modeling needs go below the container level, you hit a wall.

The catalog itself is YAML-driven. Every entity is defined in catalog-info.yaml files, typically committed alongside the code. This means architecture is defined in configuration files, not in a visual tool.

Archyl

Archyl implements all four C4 levels natively:

• Level 1 — System Context: Systems, external systems, and people
• Level 2 — Container: Applications, services, databases, message queues, caches, and more
• Level 3 — Component: Controllers, services, repositories, handlers, middleware, models
• Level 4 — Code: Classes, interfaces, functions, methods, enums, constants

Each level has its own dedicated node types, visual styles, and metadata. You can drill down from a system to its containers, from a container to its components, from a component to its code elements — all within the same interactive diagram. Relationships between elements at any level are first-class citizens with typed connections (uses, depends_on, calls, reads_from, writes_to, etc.).

The difference: Backstage gives you a catalog with C4 views bolted on. Archyl gives you a complete C4 modeling environment where you can represent your entire architecture at any level of detail.

Visualization

Backstage

The C4 plugin generates static or semi-interactive diagrams from catalog data. Visualization depends on the specific plugin implementation — some use PlantUML, some use Structurizr, some render in the browser. But the experience is fundamentally read-only. You view diagrams generated from YAML definitions. You don't interact with them.

There is no canvas manipulation, no drag-and-drop positioning, no real-time collaboration on diagrams. To change the architecture representation, you edit YAML files and wait for the catalog to refresh.

Archyl

Archyl provides a fully interactive canvas built on React Flow. You can:

• Drag and position any element on the diagram
• Draw relationships between elements directly on the canvas
• Navigate across C4 levels by drilling into systems, containers, and components
• See real-time cursors of teammates working on the same diagram
• Use auto-layout to arrange elements automatically, or position them manually
• Apply overlays to visually group related elements
• Switch between light and dark themes on the diagram

The canvas is the primary workspace, not a generated artifact. Every change you make on the diagram is reflected instantly.

AI-Powered Discovery

Backstage

Backstage has no built-in AI-powered architecture discovery. To populate the catalog, you manually create catalog-info.yaml files for every service, or use entity providers that import from external sources (Kubernetes, GitHub, etc.). Some community plugins add AI capabilities, but there's no native architecture analysis from code.

If you have 200 services and none have catalog-info.yaml files, you're writing 200 YAML files by hand — or building custom tooling to generate them.

Archyl

Archyl includes built-in AI discovery that connects to your Git repository (GitHub, GitLab, Bitbucket, Azure DevOps, Gitea, or local repos), reads your codebase, and automatically generates a complete C4 model.

The discovery pipeline:

1. Connects to your repository
2. Analyzes source files, infrastructure code, and configuration
3. Identifies systems, containers, components, and their relationships
4. Detects dependencies from package manifests
5. Generates a proposed C4 model with auto-layout
6. Presents the result for your review and approval

You can approve, modify, or reject any part of the generated model. The AI handles the heavy lifting of initial architecture mapping; you provide the judgment.

The system understands Go, TypeScript, JavaScript, Python, Java, Kotlin, Swift, Rust, C/C++, Ruby, Scala, Terraform, Docker, Kubernetes YAML, Helm charts, and more.

Architecture Decision Records

Backstage

ADRs in Backstage are typically handled through the ADR plugin, which reads ADR markdown files from a repository. It displays them in the Backstage UI, often following the MADR (Markdown Architectural Decision Records) format. The ADRs live in Git as markdown files.

There's no linking between ADRs and catalog entities. An ADR about choosing PostgreSQL over MongoDB sits in a /docs/adr/ folder — there's no direct connection to the database container it references.

Archyl

ADRs in Archyl are first-class objects linked directly to C4 elements. When you create an ADR, you can attach it to specific systems, containers, components, or code elements. This means:

• Open a container on the diagram, and you see its related ADRs
• Browse ADRs and see exactly which architecture elements they affect
• Understand the reasoning behind architectural choices in context

ADRs support statuses (proposed, accepted, deprecated, superseded) and rich markdown content with structured sections for context, decision, and consequences.

Documentation

Backstage

Backstage's TechDocs system converts markdown files (typically using MkDocs) into browsable documentation within the portal. It's markdown-based and Git-backed. The documentation renders well and supports search.

However, TechDocs is general-purpose documentation, not architecture documentation. There's no structural connection between docs and the architecture model. A page about "Authentication Architecture" doesn't link to the authentication system on the diagram.

Archyl

Archyl's documentation system is integrated with the architecture model. Documentation items can be linked to C4 elements, organized in folders, and accessed in context alongside the diagrams. When you view a system or container, its related documentation is visible in the side panel.

This isn't about replacing general documentation tools. It's about ensuring architecture documentation lives alongside the architecture it describes.

Impact Analysis

Backstage

Backstage has no impact analysis capability. If you want to understand what breaks when you deprecate a service, you manually trace dependencies through the catalog. There's no automated upstream/downstream analysis, no risk scoring, no what-if simulation.

Some organizations build custom scripts or plugins to analyze catalog relationships, but there's nothing built in.

Archyl

Archyl's Impact Radar provides comprehensive impact analysis directly on the diagram. Right-click any element and instantly see:

• Upstream dependents and downstream dependencies organized by degree (1, 2, 3 hops)
• Risk score computed from upstream dependents, downstream reach, structural children, and coupling ratio
• Critical path highlighting the longest dependency chain
• Cross-project dependencies when using Global Architecture
• Affected flows cross-referenced against documented user journeys
• What-if simulation showing exactly what breaks if an element is removed

The analysis runs deterministically over the relationship graph. No guessing, no meetings to figure out who's affected.

Change Management

Backstage

Changes to the Backstage catalog go through Git. You create a PR that modifies catalog-info.yaml, get it reviewed, and merge. This is standard Git workflow — there's no architecture-specific change management.

The review happens in GitHub/GitLab, not in the context of the architecture. Reviewers see YAML diffs, not visual diffs of how the architecture changes.

Archyl

Archyl has dedicated Architecture Change Requests — a pull-request-like workflow specifically for architecture changes. You propose changes to the C4 model, reviewers see exactly what's being added, modified, or removed, and the change goes through an approval process before being applied.

This brings governance to architecture evolution without forcing everything through YAML files and Git diffs.

Collaboration

Backstage

Backstage is a web portal. Multiple people can access it simultaneously, but there's no real-time collaboration on the architecture itself. You view the catalog independently. There are no live cursors, no presence indicators, no concurrent editing.

Archyl

Archyl provides real-time collaboration on C4 diagrams:

• Live cursors showing where teammates are on the canvas
• Presence indicators showing who's viewing the diagram
• Element focus tracking so you see which elements teammates are working on
• Concurrent editing with conflict resolution

This extends to both project-level C4 diagrams and the Global Architecture view.

Live Operational Data

One of the biggest surprises when people discover Archyl is the Marketplace. Architecture documentation isn't just static diagrams — Archyl connects to the tools your teams already use and displays live data directly on your architecture.

Backstage

Backstage's plugin ecosystem is its core strength here. There are plugins for almost everything — CI/CD status, monitoring dashboards, cost tracking, Kubernetes status, and more. But these plugins live in their own pages within the portal. They're not connected to the architecture view. You see CI/CD status for a service on its catalog page, but not on the C4 diagram where that service lives in context with everything it depends on.

Archyl

Archyl's Marketplace provides integrations that surface live data as widgets directly on your architecture dashboards:

• CI/CD: GitHub Actions workflow status, open PRs, Dependabot alerts, security scanning. GitLab pipeline status, merge requests, vulnerability reports, SAST/DAST alerts. Argo CD application status and deployment tracking.
• Observability: Datadog embedded dashboards, metric queries, monitor status. Prometheus instant and range queries, target health. Sentry error tracking.
• Code Quality: SonarQube quality gate status, code measures, issues, security hotspots and ratings.
• Incident Management: PagerDuty incident status, active incidents, on-call schedules, service health.

Widgets refresh automatically and can be scoped at three levels — organization-wide, per-project, or attached to a specific C4 element. A container representing your payment service can display its GitHub Actions build status, SonarQube quality gate, Datadog health metrics, and PagerDuty on-call schedule, all in one place.

This turns architecture documentation from a static reference into a living operational view. The diagram doesn't just show what your system looks like — it shows how it's doing right now.

Beyond the Basics

A few more areas where the approaches diverge:

When to Choose What

Choose Backstage if you need a unified developer portal that aggregates documentation, CI/CD, service catalog, cost management, and dozens of other concerns into a single internal platform. Architecture documentation is one piece of that puzzle, and a high-level C4 view is sufficient for your needs.

Choose Archyl if architecture documentation is a primary concern — but you don't want to sacrifice operational visibility to get it. Archyl goes deep on the C4 model (all 4 levels), interactive diagrams, AI-powered discovery, impact analysis, and change governance, while its Marketplace integrations bring live CI/CD status, monitoring, code quality, and incident data directly onto your architecture. You get focused architecture tooling without losing the operational context that Backstage provides through its plugin ecosystem.

They can also coexist. Archyl handles detailed architecture modeling, analysis, and operational visibility scoped to your architecture. Backstage handles the broader developer experience — onboarding, catalog search, cost dashboards, and general documentation. The architecture model in Archyl can inform what you document in Backstage's service catalog, without either tool replacing the other.

The Bottom Line

Backstage is a platform framework that you assemble from plugins. It's powerful, flexible, and solves the problem of developer experience fragmentation. But its architecture documentation capabilities are limited to what catalog-driven C4 plugins can provide — typically Levels 1 and 2, static views, no AI, no impact analysis, no real-time collaboration on diagrams.

Archyl is a focused tool that goes deep on architecture. It covers the full C4 model, AI discovery, impact analysis, change governance, real-time collaboration — and connects to your CI/CD, observability, code quality, and incident tools so your architecture stays grounded in operational reality. It's not a developer portal, but it's far more than static documentation.

Your architecture deserves more than a catalog entry.

New to the C4 model? Start with our Introduction to the C4 Model. Already modeling? Try AI-Powered Architecture Discovery to bootstrap your first project from code, or explore Impact Radar to understand change before you make it.