Import a Backstage Catalog into Archyl: Backstage to C4
Turn your Backstage Software Catalog into a navigable C4 model. Systems, Components, Resources, and inline API specs import from entities.json.
Import your Backstage catalog into Archyl
Backstage lists what you run. Archyl turns the same catalog into a navigable C4 model: Systems become systems, Components and Resources become containers, and every API entity becomes a contract with its spec preserved inline and linked to the services that provide and consume it. You keep Backstage. Ownership does not come across, and you get two C4 levels to build on.
Import a Backstage Catalog into Archyl | Backstage to C4
Turn your Backstage Software Catalog into a navigable C4 architecture model. Systems, Components, Resources, and inline API specs import from entities.json. Ownership stays in Backstage.
Backstage to C4, Backstage catalog import, export Backstage catalog, Backstage architecture diagram, Backstage software catalog C4 model, Backstage architecture documentation
Every System entity becomes a C4 software system with its description and tags. Two Systems sharing a name across namespaces are renamed rather than merged, and the import tells you which.
Components become containers under the System that owns them, resolved from spec.system or a partOf relation. Their spec.type is mapped: service to service, website to web app, cronworkflow to worker, library to library.
Resources become containers too, typed from spec.type. RDS instances and Valkey clusters become databases, Kafka topics and SQS queues become message queues, S3 buckets become file storage.
API entities become Archyl API contracts. The inline spec.definition is kept verbatim, typed as HTTP, gRPC, GraphQL, or async, and linked to the containers that provide and consume it.
dependsOn, consumesApi, producesTo, consumesFrom, and versionedIn become typed relationships. Backstage emits both directions of most relations and the import keeps one. A consumesApi edge is resolved through the API to the container that actually provides it.
Namespaces and Lifecycle
Your metadata.tags come across unchanged, alongside namespace, lifecycle, and type as prefixed tags, so the grouping you curated in Backstage survives in the architecture model.
Call your Backstage catalog API and save the response. The entities endpoint returns every System, Component, Resource, and API it knows about as a single JSON array.
Choose the Backstage format
In Archyl's import dialog, pick the "Backstage" tab. It takes the entities array exactly as Backstage exports it, with no reshaping.
Upload or paste entities.json
Upload the file or paste it in, then validate. Archyl reports any errors in the JSON before you commit to the import.
Import, then read the warnings
Archyl builds the model and reports how many systems, containers, API contracts, and relationships it created, plus every entity it had to rename. Assign owners afterwards: Backstage Groups and Users are not imported.
Get a 0-100% health score showing how accurately your documentation reflects your actual codebase. Catch drift before it compounds.
Define architecture rules and run automated checks to ensure your system stays within defined guardrails.
Track deployment frequency, lead time, change failure rate, and recovery time alongside your architecture health.
MCP Server (181 Tools)
Query architecture data from Claude, Cursor, or Windsurf through 181 specialized MCP tools. Architecture knowledge at your fingertips.
Architecture Decision Records
Link ADRs directly to C4 elements so every design decision has traceable context within your architecture model.
Attach OpenAPI, AsyncAPI, or GraphQL schemas to containers and components. Keep contracts versioned alongside your architecture.
Do we have to leave Backstage?
No, and most teams should not. Backstage is a developer portal; Archyl is an architecture model. The import reads a catalog export and never touches your Backstage instance, so both keep running. Archyl answers the questions a flat catalog cannot: how these services fit together, what has drifted from the code, and which contracts break if one of them changes.
How many C4 levels does the import give me?
Two. Systems land at C4 Level 1, and both Components and Resources land at Level 2 as containers. Backstage has no entity kind below Component, so there is nothing to fill Level 3 from. You add components and code elements afterwards by hand, or point Archyl's AI discovery at the repository and approve what it proposes.
Does ownership transfer?
No. User and Group entities are skipped and ownedBy relations are not mapped, so spec.owner does not become an owner in Archyl. This is the one thing worth planning for: if you use Archyl's ownership map, you assign owners after the import.
What happens to our OpenAPI and gRPC specs?
An API entity carrying an inline spec.definition keeps that spec verbatim as an Archyl API contract, typed from spec.type as HTTP, gRPC, GraphQL, or async, and linked to the containers that provide and consume it. An API entity with no inline definition still comes across with its name, description, and type, but no body.
What does the import skip?
User and Group entities, along with the ownedBy relations pointing at them. Location and Template entities. The metadata.annotations and metadata.links blocks, which means the TechDocs pointer does not come across. Relations outside the mapped set are ignored. The import warns you about duplicate and renamed entities. The kinds above are dropped without a warning, which is why this page names them.
Our catalog has thousands of auto-discovered resources. Do they all come in?
Yes. Every Resource is imported, because silently dropping data you curated is worse than importing too much. Each container keeps a type tag taken from its Backstage spec.type, so the noisy categories stay identifiable, and you can narrow the import at the source with Backstage's filter query parameter before you export.