Turn Your Backstage Catalog Into a Real C4 Architecture in 60 Seconds

Backstage is the catalog. If you work in a platform team, odds are you've spent months curating catalog-info.yaml files, wiring up annotations, getting dependsOn links right, and answering Slack questions about why a service didn't show up. That work is real. It represents an actual map of your systems.

But here's the thing: Backstage was built to list your software, not to model it. The component pages are useful. The relationships are sparse. The C4 plugin is an afterthought. You can scroll through 700 services in a flat list, but you can't see how they fit together.

If you want a real architecture view, you usually have a choice: rebuild your catalog by hand in another tool, or live with what Backstage gives you.

Today, that choice goes away.

Archyl now imports your Backstage Software Catalog directly. One curl, one upload, and every System, Component, Resource, and API you've already curated shows up as a complete, navigable C4 model — with relationships, OpenAPI contracts, infrastructure resources, and metadata intact.

Sixty Seconds, Three Steps

Backstage exposes its full entity catalog through a single REST endpoint. Pull it, drop it into Archyl, done.

Step 1 — Export your catalog

curl -H "Authorization: Bearer $BACKSTAGE_TOKEN" \
  https://backstage.your-company.com/api/catalog/entities \
  -o entities.json

That's the whole export. The endpoint streams every entity Backstage knows about: Systems, Components, Resources, APIs, Groups, Users — everything. For most organizations, you get a 5–30 MB JSON array with thousands of entries.

If you're testing without auth (some Backstage instances allow public catalog reads on the internal network), you can drop the Authorization header. If you need to filter by kind to keep the file smaller, Backstage supports query params: ?filter=kind=component,kind=system,kind=api,kind=resource will cut the response to just what Archyl actually maps.

Step 2 — Open the import dialog

In Archyl, click Import Project (or Import inside an existing project), select the Backstage tab, and either upload entities.json or paste it directly.

Archyl validates the file, then shows you exactly what will be created — number of systems, containers, API contracts, relationships — before anything is written.

Step 3 — Click import

Your project is populated. A 9 MB catalog with ~3,000 entities imports in seconds. You can now click into any system, see its containers laid out in C4 Level 2, drill into APIs, and follow dependsOn edges across your stack.

What Actually Gets Mapped

The hard part of importing from Backstage isn't reading the JSON — it's translating between two different mental models. Backstage thinks in flat entities connected by typed relations. C4 thinks in nested levels. Here's how Archyl bridges them:

Components and Resources without a spec.system go into a synthetic Uncategorized system so nothing is silently dropped.

The two details that matter most in practice:

• API contracts come with their bodies. Every Backstage API entity that includes a spec.definition (your inline OpenAPI YAML, your gRPC .proto) gets imported as an Archyl API Contract with the full spec attached and linked to the provider component. No re-uploading specs by hand.
• Resource types are preserved. A Kafka topic doesn't become a generic "service" — it's a message_queue container. An RDS instance is a database. An S3 bucket is file_storage. Your visual model reflects the actual nature of each piece of infrastructure.

A Word About Resource Sprawl

If your organization runs heavily on Kubernetes, your Backstage catalog probably has hundreds — maybe thousands — of external-secret, repository, datadog-service, and load-balancer resources auto-discovered from clusters. We import them all.

That might look like a lot at first. It is.

But you have a few options:

• Keep them and filter. Every imported container carries a type:external-secret (or whatever) tag. Archyl's overlays and tag filters let you hide them in the diagram while keeping them queryable.
• Bulk delete what's noise. Two clicks per type to remove an entire category if you don't want it in your model.
• Re-export with a filter. Use Backstage's ?filter= query params to exclude resource kinds you don't care about before importing.

We chose to import everything because the alternative — silently dropping data we thought you didn't need — is worse. You curated your catalog. You decide what stays.

What You Actually Gain

A Backstage catalog tells you what exists. An Archyl architecture tells you what's happening.

Once your catalog lives in Archyl, you unlock things Backstage simply doesn't do:

A real C4 diagram. Interactive, zoomable, navigable across all four levels — System Context, Container, Component, and Code. Click any service to drill into its internals. Follow a relationship across the stack.

Drift detection. Archyl continuously compares your documented architecture against the actual code in your repositories. When your catalog says "Service A calls Service B" but the code stopped doing that six months ago, you find out — instead of discovering it during an incident.

Architecture conformance rules. Codify "no service outside the payments domain may call legacy-auth-api," or "all external calls must go through the API gateway." Archyl enforces them automatically and surfaces violations on every PR.

API contract intelligence. The OpenAPI specs you've been feeding into Backstage now live inside the architecture, linked to producers and consumers. Breaking change in news-api? See exactly which downstream services depend on it.

DORA metrics tied to architecture. Connect deployment frequency, lead time, change failure rate, and MTTR to specific systems, containers, and teams. See which parts of your architecture are healthy and which are in trouble.

Architecture Decision Records. Finally have a place to write down the why alongside the what, linked directly to the systems and components affected.

MCP integration. Every AI coding agent on your team — Claude Code, Cursor, Windsurf — shares the same architecture context. Stop re-explaining how your services fit together to your LLM.

The Backstage catalog answers "what services do we run?" Archyl answers "how are they connected, what's drifting, what's at risk, and where should we invest?" Importing your catalog means you don't have to choose between the two.

For AI Agent Workflows

The same import is exposed through Archyl's MCP server. Point Claude Code, Cursor, or any AI coding agent at the import_dsl tool with format: "backstage" and the content of your entities.json — and your architecture lands without anyone touching a browser.

Use the import_dsl tool with:
- projectId: <your project UUID>
- content: <contents of entities.json>
- format: "backstage"

Useful when you're scripting catalog syncs from CI, or when you want your AI assistant to refresh the model after a major Backstage update.

Try It Now

If your team runs Backstage today, you're literally one curl away from a complete C4 architecture.

1. Run the curl above.
2. Open Archyl, click Import Project, choose Backstage.
3. Watch your services, APIs, queues, and databases snap into a navigable architecture.

The import works on every plan, including the free tier. We don't think your decision should hinge on whether your catalog is portable — it should hinge on what you want to do with it next.

Your Backstage catalog has been waiting to be an architecture. Go make it one.