Backstage 카탈로그를 60초 안에 진정한 C4 아키텍처로 변환하세요

Backstage는 그 카탈로그입니다. 플랫폼 팀에서 일한다면, catalog-info.yaml 파일을 다듬고, 어노테이션을 연결하고, dependsOn 링크를 바로잡고, 왜 어떤 서비스가 나타나지 않는지에 대한 Slack 질문에 답하느라 몇 달을 보냈을 가능성이 큽니다. 그 작업은 진짜입니다. 시스템의 실제 지도를 나타냅니다.

하지만 여기 핵심이 있습니다: Backstage는 소프트웨어를 나열하기 위해 만들어졌지, 모델링하기 위해 만들어진 것이 아닙니다. 컴포넌트 페이지는 유용합니다. 관계는 드뭅니다. C4 플러그인은 부수적인 것입니다. 700개의 서비스를 평면 목록에서 스크롤할 수는 있지만, 그것들이 어떻게 맞물리는지는 볼 수 없습니다.

진정한 아키텍처 뷰를 원한다면, 보통 선택지가 있었습니다: 다른 도구에서 카탈로그를 손으로 다시 만들거나, Backstage가 제공하는 것에 만족하거나.

오늘, 그 선택지가 사라집니다.

Archyl이 이제 Backstage Software Catalog를 직접 가져옵니다. 한 번의 curl, 한 번의 업로드로, 이미 다듬어 둔 모든 System, Component, Resource, API가 완전하고 탐색 가능한 C4 모델로 나타납니다 — 관계, OpenAPI 계약, 인프라 리소스, 메타데이터가 모두 그대로.

60초, 3단계

Backstage는 단일 REST 엔드포인트를 통해 전체 엔티티 카탈로그를 노출합니다. 가져와서, Archyl에 떨어뜨리고, 끝입니다.

1단계 — 카탈로그 내보내기

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

이게 전체 export입니다. 엔드포인트는 Backstage가 알고 있는 모든 엔티티를 스트리밍합니다: Systems, Components, Resources, APIs, Groups, Users — 전부 다요. 대부분의 조직에서는 수천 개의 항목이 담긴 5–30 MB JSON 배열을 얻게 됩니다.

인증 없이 테스트한다면 (일부 Backstage 인스턴스는 내부 네트워크에서 카탈로그 공개 읽기를 허용함), Authorization 헤더를 빼도 됩니다. 파일을 더 작게 유지하기 위해 kind로 필터링이 필요하다면, Backstage는 쿼리 파라미터를 지원합니다: ?filter=kind=component,kind=system,kind=api,kind=resource로 Archyl이 실제로 매핑하는 것만으로 응답을 줄일 수 있습니다.

2단계 — 가져오기 다이얼로그 열기

Archyl에서 프로젝트 가져오기 (또는 기존 프로젝트 내에서 가져오기)를 클릭하고, Backstage 탭을 선택한 다음 entities.json을 업로드하거나 직접 붙여넣으세요.

Archyl은 파일을 검증한 다음, 아무것도 쓰여지기 전에 정확히 무엇이 생성될지 — 시스템 수, 컨테이너 수, API 계약 수, 관계 수 — 보여줍니다.

3단계 — 가져오기 클릭

프로젝트가 채워집니다. ~3,000개 엔티티가 있는 9 MB 카탈로그는 몇 초 안에 가져와집니다. 이제 어떤 시스템이든 클릭해서 C4 Level 2에서 컨테이너 배치를 보고, API로 파고들어, 스택 전반에 걸쳐 dependsOn 엣지를 따라갈 수 있습니다.

실제로 무엇이 매핑되는가

Backstage에서 가져오는 것의 어려운 부분은 JSON을 읽는 것이 아닙니다 — 두 개의 다른 정신 모델 사이를 번역하는 것입니다. Backstage는 타입이 있는 관계로 연결된 평면 엔티티로 생각합니다. C4는 중첩된 레벨로 생각합니다. Archyl이 이를 어떻게 잇는지 살펴보세요:

Backstage	Archyl	비고
`System`	C4 System (레벨 1)	네임스페이스 간 같은 이름 시스템은 자동으로 구분됩니다
`Component`	소속 System 아래 Container	`service` → service, `cronworkflow` → worker, `website` → web_app
`Resource`	소속 System 아래 Container	타입 인식: `s3-bucket` → file_storage; `rds-instance`, `dynamo-db-table`, `valkey-cluster`, `opensearch-domain` → database; `kafka-topic`, `sqs-queue` → message_queue; `repository` → library
`API` (`spec.definition` 포함)	API 계약	OpenAPI 3, gRPC, GraphQL, AsyncAPI 사양은 인라인으로 보존되어 프로바이더/컨슈머 컴포넌트에 연결됩니다
`dependsOn`, `dependencyOf`	`depends_on` 관계	양방향 쌍은 자동으로 중복 제거됩니다
`consumesApi`	`uses` 관계	API를 통해 실제 프로바이더 컴포넌트로 해석됩니다
`producesTo`, `producedBy`	`publishes_to` 관계
`consumesFrom`, `consumedBy`	`consumes_from` 관계
`versionedIn`, `versions`	`depends_on` 관계	"source code"로 라벨링
`metadata.namespace`, `spec.lifecycle`, `spec.type`, `metadata.tags`	태그	필터링 및 오버레이를 위해 모두 이전됨
`User`, `Group`	건너뜀	사람 그래프는 C4 개념이 아닙니다

spec.system이 없는 Component와 Resource는 어떤 것도 조용히 버려지지 않도록 합성 시스템인 Uncategorized로 들어갑니다.

실제로 가장 중요한 두 가지 세부사항:

API 계약은 본문과 함께 옵니다. spec.definition을 포함하는 모든 Backstage API 엔티티(인라인 OpenAPI YAML, gRPC .proto)는 전체 사양이 첨부되고 프로바이더 컴포넌트에 연결된 Archyl API 계약으로 가져와집니다. 사양을 손으로 다시 업로드할 필요가 없습니다.
Resource 타입은 보존됩니다. Kafka 토픽은 일반적인 "service"가 되지 않습니다 — message_queue 컨테이너입니다. RDS 인스턴스는 database입니다. S3 버킷은 file_storage입니다. 시각 모델은 각 인프라 조각의 실제 본질을 반영합니다.

리소스 폭증에 대한 한 마디

조직이 Kubernetes 위에서 크게 동작한다면, Backstage 카탈로그에는 클러스터에서 자동 발견된 수백 — 어쩌면 수천 — 개의 external-secret, repository, datadog-service, load-balancer 리소스가 있을 것입니다. 모두 가져옵니다.

처음에는 많아 보일 수 있습니다. 실제로 많습니다.

하지만 몇 가지 옵션이 있습니다:

유지하고 필터링하세요. 가져온 모든 컨테이너는 type:external-secret(또는 다른) 태그를 가집니다. Archyl의 오버레이와 태그 필터로 다이어그램에서 숨기면서도 쿼리 가능한 상태를 유지할 수 있습니다.
노이즈를 일괄 삭제하세요. 모델에 원하지 않는 카테고리 전체를 제거하려면 타입당 두 번 클릭하면 됩니다.
필터로 다시 export하세요. Backstage의 ?filter= 쿼리 파라미터를 사용하여 가져오기 전에 관심 없는 리소스 종류를 제외할 수 있습니다.

대안 — 필요 없다고 생각한 데이터를 조용히 버리는 것 — 이 더 나쁘기 때문에 모든 것을 가져오기로 선택했습니다. 당신이 카탈로그를 다듬었습니다. 무엇을 남길지는 당신이 결정합니다.

실제로 무엇을 얻는가

Backstage 카탈로그는 무엇이 존재하는지 알려줍니다. Archyl 아키텍처는 무엇이 벌어지고 있는지 알려줍니다.

카탈로그가 Archyl에 살아있게 되면, Backstage가 단순히 하지 않는 것들이 잠금 해제됩니다:

진짜 C4 다이어그램. 인터랙티브하고, 줌 가능하며, 네 가지 레벨 모두 — System Context, Container, Component, Code — 를 탐색할 수 있습니다. 어떤 서비스든 클릭해서 그 내부로 들어가세요. 스택 전반에 걸쳐 관계를 따라가세요.

드리프트 감지. Archyl은 문서화된 아키텍처를 리포지토리의 실제 코드와 지속적으로 비교합니다. 카탈로그가 "Service A는 Service B를 호출한다"고 하지만 코드가 6개월 전에 그것을 멈췄다면, 발견하게 됩니다 — 인시던트 중에 발견하는 대신에.

아키텍처 준수 규칙. "결제 도메인 외부의 어떤 서비스도 legacy-auth-api를 호출할 수 없다" 또는 "모든 외부 호출은 API gateway를 통과해야 한다"를 코드화하세요. Archyl이 자동으로 강제하고 모든 PR에서 위반사항을 표시합니다.

API 계약 인텔리전스. Backstage에 공급해 온 OpenAPI 사양들이 이제 아키텍처 안에 살며, 프로듀서와 컨슈머에 연결됩니다. news-api에서 깨지는 변경? 어떤 다운스트림 서비스가 의존하는지 정확히 보세요.

아키텍처에 묶인 DORA 메트릭. 배포 빈도, 리드 타임, 변경 실패율, MTTR을 특정 시스템, 컨테이너, 팀에 연결하세요. 아키텍처의 어떤 부분이 건강하고 어떤 부분이 어려움에 처해 있는지 보세요.

Architecture Decision Records. 마침내 왜를 무엇 옆에 적을 곳이 생겼고, 영향을 받는 시스템과 컴포넌트에 직접 연결됩니다.

MCP 통합. 팀의 모든 AI 코딩 에이전트 — Claude Code, Cursor, Windsurf — 가 같은 아키텍처 컨텍스트를 공유합니다. 서비스가 어떻게 맞물리는지 LLM에게 다시 설명하는 것을 멈추세요.

Backstage 카탈로그는 "우리가 어떤 서비스를 운영하는가?"에 답합니다. Archyl은 "그것들이 어떻게 연결되어 있고, 무엇이 드리프트하고 있고, 무엇이 위험에 처해 있고, 어디에 투자해야 하는가?"에 답합니다. 카탈로그를 가져온다는 것은 둘 사이에서 선택할 필요가 없다는 뜻입니다.

AI 에이전트 워크플로우용

같은 가져오기가 Archyl의 MCP 서버를 통해 노출됩니다. Claude Code, Cursor 또는 어떤 AI 코딩 에이전트라도 format: "backstage"와 entities.json 내용으로 import_dsl 도구에 가리키면 — 누구도 브라우저를 만지지 않고 아키텍처가 도착합니다.

다음과 함께 import_dsl 도구를 사용:
- projectId: <당신의 프로젝트 UUID>
- content: <entities.json 내용>
- format: "backstage"

CI에서 카탈로그 동기화를 스크립팅할 때나, Backstage 메이저 업데이트 후 AI 어시스턴트가 모델을 갱신하기를 원할 때 유용합니다.

지금 시도해 보세요

오늘 팀이 Backstage를 운영한다면, 문자 그대로 curl 한 번이면 완전한 C4 아키텍처에 도달합니다.

위의 curl을 실행하세요.
Archyl을 열고, 프로젝트 가져오기를 클릭하고, Backstage를 선택하세요.
서비스, API, 큐, 데이터베이스가 탐색 가능한 아키텍처로 맞물리는 모습을 지켜보세요.

가져오기는 무료 티어를 포함한 모든 플랜에서 작동합니다. 결정이 카탈로그가 이식 가능한지 여부에 달려 있어서는 안 된다고 생각합니다 — 그것으로 다음에 무엇을 하고 싶은지에 달려 있어야 합니다.

Backstage 카탈로그는 오랫동안 아키텍처가 되기를 기다려왔습니다. 가서 그렇게 만들어 주세요.