YAML로 작성하는 C4 모델: archyl.yaml 형식과 Git 워크플로우

아키텍처 다이어그램에는 유통기한 문제가 있습니다. 설계 세션 후에 그리면 일주일은 멋져 보이지만, 코드가 진화하는 동안 다이어그램은 썩어 갑니다. 여섯 달 뒤, 새로 합류한 사람은 2분기에 합쳐진 서비스 세 개가 그려져 있고 3분기에 만든 서비스 두 개는 빠져 있는 Container 다이어그램을 멍하니 바라봅니다.

Archyl은 처음부터 이 문제에 매달려 왔습니다. AI 발견은 내용을 최신으로 유지하는 데 도움이 됩니다. 시각적 편집기는 업데이트를 수월하게 만듭니다. 하지만 인프라를 코드로, 정책을 코드로, 모든 것을 코드로 다루는 팀들은 더 근본적인 것을 원했습니다.

그들은 아키텍처가 그것이 설명하는 코드 옆, 즉 Git 안에 있기를 원했습니다. 오늘 우리가 출시하는 것이 바로 그것입니다.

이 글은 파일 자체에 대한 레퍼런스입니다: 무엇이 들어가는지, 참조가 어떻게 해석되는지, 어떻게 동기화되는지. Architecture as code 전반의 의의와 Structurizr DSL 같은 형식과의 비교는 Architecture as code 가이드를 읽어 보세요.

`archyl.yaml`이란?

전체 아키텍처를 선언적으로 기술하는 단일 YAML 파일입니다. 리포지토리 루트에 두면 Archyl에서 C4 모델의 기준 정보가 됩니다.

최소한의 파일은 다음과 같습니다:

version: "1.0"

project:
  name: "My Platform"
  description: "Microservices architecture"

systems:
  - name: Platform
    type: software_system
    containers:
      - name: API Gateway
        type: api
        technologies: [Go, gRPC]
      - name: User Database
        type: database
        technologies: [PostgreSQL]

relationships:
  - from: API Gateway
    to: User Database
    label: "Reads user data"
    type: reads_from

이게 전부입니다. Archyl은 이 파일을 읽어 전체 C4 모델을 만들고, 다이어그램을 렌더링하고, 모든 것을 동기화된 상태로 유지합니다. UI를 클릭하며 돌아다닐 필요도, 수동 동기화도, "다이어그램 업데이트를 깜빡했네"도 없습니다.

최상위 키

키	담는 내용
`version`	형식 버전, 현재 `"1.0"`
`project`	프로젝트 이름과 설명
`technologies`	요소들이 참조하는 기술 카탈로그
`environments`	스테이징, 프로덕션 같은 배포 환경
`systems`	시스템. 그 안에 컨테이너, 컴포넌트, 코드 요소가 중첩됨
`relationships`	임의의 두 요소 사이의 연결. 이름 또는 점 표기법 경로로 지정
`overlays`	다이어그램 위의 이름 붙은 시각적 그룹
`events`	Kafka 토픽 같은 이벤트 채널, 생산자와 소비자 포함
`api_contracts`	OpenAPI, gRPC 등의 명세. 이를 노출하는 요소에 연결됨
`releases`	릴리스와 그것이 배포한 것
`adrs`	인라인 ADR 또는 리포지토리 안의 ADR 폴더
`docs`	프로젝트 문서. 인라인 또는 폴더에서
`include`	병합할 다른 `archyl.yaml` 파일. 모노레포용

최상위에서 필수인 것은 version뿐입니다. 나머지는 모두 선택 사항이므로, 파일은 시스템 하나로 시작해 점점 키워 갈 수 있습니다.

모든 것을 하나의 파일에

이 DSL은 단순화된 부분집합이 아닙니다. Archyl이 모델링할 수 있는 전체 범위를 다룹니다:

C4의 네 가지 레벨 모두. 시스템은 컨테이너를, 컨테이너는 컴포넌트를, 컴포넌트는 코드 요소를 포함합니다. YAML 중첩이 계층을 그대로 반영합니다.

점 표기법을 쓰는 관계. Payment Service.API Gateway → Payment Service.Database 같은 읽기 쉬운 참조로 임의의 두 요소를 연결합니다. UUID도, 알아보기 힘든 식별자도 없습니다. grep 가능하고, diff에 친화적이며, 사람이 읽을 수 있습니다.

기술, 환경, 릴리스. 기술 카탈로그를 정의하고, 배포 환경(스테이징, 프로덕션)을 선언하고, 릴리스를 추적합니다 — 모두 같은 파일에서.

ADR과 문서. 아키텍처 결정 기록을 인라인으로 쓰거나 리포지토리의 폴더를 가리키세요. 프로젝트 문서도 마찬가지입니다.

API 계약과 이벤트 채널. OpenAPI 명세, gRPC 정의, Kafka 토픽을 선언하고, 이를 노출하거나 소비하는 컴포넌트에 연결합니다.

시각적 오버레이. 이름 붙은 오버레이로 다이어그램 위의 요소를 그룹화하고 색상과 레벨을 제어합니다.

모노레포 지원. include를 사용해 아키텍처를 여러 파일(서비스, 팀, 바운디드 컨텍스트마다 하나씩)로 나누면, Archyl이 자동으로 병합합니다.

왜 YAML인가?

자체 DSL 문법(Structurizr의 DSL이나 Terraform의 HCL 같은)을 만드는 것도 고려했습니다. YAML을 고른 것은 실용적인 이유 때문입니다:

학습 곡선이 없습니다. 모든 개발자가 이미 YAML을 압니다. 새로운 문법을 배울 필요도, 파서를 설치할 필요도, 에디터 플러그인도 필요 없습니다.
IDE 지원을 공짜로 얻습니다. /api/v1/dsl/schema에서 JSON Schema를 제공합니다. IDE가 이를 가리키게 하면 Archyl 전용 도구 없이 자동 완성, 유효성 검사, 인라인 문서를 얻을 수 있습니다.
diff 친화적입니다. YAML diff는 풀 리퀘스트에서 깔끔하고 읽기 쉽습니다. 리뷰어는 "아, Payment Service에 새 컨테이너를 추가하고 Redis에 연결했구나"를 바로 알아봅니다.
도구 생태계. 린터, 포매터, 템플릿 엔진(Helm, Kustomize)이 모두 YAML에서 바로 동작합니다.

Git 네이티브 워크플로우

진짜 힘은 여기에 있습니다. archyl.yaml이 리포지토리에 있기 때문에, 아키텍처 변경은 코드 변경과 같은 워크플로우를 따릅니다:

브랜치. 피처 브랜치를 만들고 YAML을 수정합니다.
리뷰. 풀 리퀘스트를 엽니다. 팀은 코드 변경과 함께 아키텍처 변경도 리뷰합니다.
병합. 승인되면 main에 병합합니다.
동기화. Archyl이 변경을 가져와 다이어그램을 자동으로 업데이트합니다.

"다이어그램은 X라고 하는데 코드는 Y를 한다"는 더 이상 없습니다. 리뷰를 우회하는 아키텍처 변경도, 업데이트된 줄 아무도 모르는 문서도 없습니다.

CI/CD 통합

CI/CD 파이프라인과의 일급 통합을 만들었습니다. GitHub에는 파일 읽기, API 호출, 변경 내용 보고까지 모두 처리하는 공식 GitHub Action을 제공합니다.

GitHub Actions (공식 액션):

name: Sync Architecture
on:
  push:
    branches: [main]
    paths: ['archyl.yaml']
jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: archyl-com/actions/sync@v1
        with:
          api-key: ${{ secrets.ARCHYL_API_KEY }}
          project-id: 'your-project-uuid'

이게 전부입니다. 설정 세 줄이면 푸시할 때마다 아키텍처가 동기화됩니다. 이 액션은 사용자 지정 파일 경로(모노레포용)와 셀프 호스팅 Archyl 인스턴스를 지원하며, 후속 단계를 위해 summary, systems-created, relationships-created 같은 출력을 제공합니다.

GitLab CI:

sync-architecture:
  stage: deploy
  script:
    - |
      curl -X POST \
        https://api.archyl.com/api/v1/projects/$ARCHYL_PROJECT_ID/dsl/ingest \
        -H "X-API-Key: $ARCHYL_API_KEY" \
        -H "Content-Type: application/json" \
        -d "{\"content\": \"$(cat archyl.yaml | jq -Rs .)\"}"
  only:
    changes:
      - archyl.yaml

/ingest 엔드포인트는 API 키 인증을 받으므로 CI에서 OAuth 흐름이 필요 없습니다. 전체 모델을 가져와 모든 요소를 생성하거나 업데이트하고, 무엇이 바뀌었는지 상세한 요약을 반환합니다.

Archyl UI에서 직접 동기화할 수도 있습니다. 프로젝트에 Git 리포지토리가 연결되어 있다면, Architecture as Code 설정에서 "Sync Now"를 누르면 Archyl이 리포지토리에서 직접 파일을 가져옵니다.

양방향: 내보내기와 가져오기

워크플로우는 단방향이 아닙니다. 이미 Archyl의 시각적 편집기로 모델링한 프로젝트가 있나요? 내보내세요:

Export는 현재 모델에서 완전한 archyl.yaml을 생성합니다. 모든 시스템, 컨테이너, 컴포넌트, 관계, 오버레이, ADR, API 계약, 이벤트 채널, 릴리스가 깔끔한 YAML로 직렬화됩니다.
Import는 archyl.yaml을 파싱해 프로젝트의 모든 요소를 생성하거나 업데이트합니다. 멱등적이므로 같은 파일을 두 번 가져와도 중복이 생기지 않습니다. 요소는 이름으로 매칭되어 업서트됩니다.
Import as Project는 YAML 파일에서 완전히 새로운 프로젝트를 만듭니다. archyl.yaml을 넣으면 클릭 한 번으로 내용이 채워진 프로젝트가 생깁니다.

즉, UI에서 시작해 YAML로 내보내고, Git에 커밋하고, 코드 우선 워크플로우로 전환할 수 있습니다 — 반대 방향도 가능합니다. 어느 쪽 접근 방식에도 종속되지 않습니다.

똑똑한 참조 해석

DSL에서 가장 까다로운 부분 중 하나는 관계, 오버레이, 이벤트, API 계약에서 요소 참조를 해석하는 것입니다. 우리는 이를 자연스럽게 처리하는 리졸버를 만들었습니다:

짧은 이름은 모호하지 않을 때 동작합니다: 그 이름을 가진 요소가 하나뿐이면 API Gateway가 바로 해석됩니다.
점 표기법으로 모호함을 없앱니다: Payment Service.API Gateway 대 Analytics.API Gateway.
어떤 깊이든 동작합니다: 깊이 중첩된 참조에는 System.Container.Component.CodeElement.

리졸버는 모든 요소를 가능한 모든 경로 깊이에서 인덱싱하므로, 항상 모호하지 않은 가장 짧은 참조를 쓸 수 있습니다. 내보내기는 같은 로직을 반대로 사용해 가능한 한 읽기 쉬운 참조를 만들어 냅니다.

부작용 없는 유효성 검사

YAML이 올바른지 확신이 없나요? /validate 엔드포인트(그리고 가져오기 모달의 "Validate" 버튼)는 데이터베이스를 건드리지 않고 파일을 파싱하고 검사합니다:

스키마 버전 확인
필수 필드 유효성 검사
중복 이름 감지
타입 열거값 유효성 검사(컨테이너 유형, 관계 유형 등)
상호 참조 해석

오류는 정확한 경로(systems[2].containers[1].name)와 명확한 메시지와 함께 반환됩니다. pre-commit 훅이나 CI 검사에 연결하면 main에 도달하기 전에 문제를 잡을 수 있습니다.

실제 활용 패턴

모노레포

# Root archyl.yaml
version: "1.0"
project:
  name: "Our Platform"
include:
  - services/payments/archyl.yaml
  - services/users/archyl.yaml
  - services/notifications/archyl.yaml

각 서비스는 자신의 컨테이너와 컴포넌트를 정의하는 자체 archyl.yaml을 유지합니다. 루트 파일이 이들을 병합하고, 서비스 간 관계는 루트 수준에서 정의합니다. 기술과 환경은 자동으로 중복 제거됩니다.

부트스트래퍼

새 프로젝트를 시작하나요? 코드를 쓰기 전에 archyl.yaml을 만드세요. 만들 계획인 시스템과 컨테이너를 정의하세요. Archyl의 "Import as Project"로 아키텍처를 즉시 생성하세요. 개발이 진행되면서 YAML도 코드와 함께 진화합니다.

감사 추적

YAML이 Git에 있으니 전체 이력을 공짜로 얻습니다. git log archyl.yaml을 실행하면 모든 아키텍처 변경, 누가 했는지, 언제 했는지, 그리고 논의가 이루어진 PR까지 보입니다. 다이어그램 도구에서 이걸 얻어 보세요.

문서 생성기

아키텍처를 YAML로 내보낸 다음 아무 템플릿 엔진에 통과시키면 Markdown 문서, Confluence 페이지, 사내 위키를 생성할 수 있습니다. 구조화된 형식이라 자동화가 아주 쉽습니다.

다음 단계

이것은 DSL 형식의 1.0 버전입니다. 다음에 작업 중인 것은 다음과 같습니다:

드리프트 감지. 리포지토리의 YAML을 라이브 모델과 비교해 차이를 강조합니다 — UI에서 추가되었지만 파일에는 없는 요소, 또는 그 반대.

PR 미리보기 댓글. PR이 archyl.yaml을 수정하면, 봇이 아키텍처에서 무엇이 바뀌었는지 시각적 diff로 댓글을 남깁니다.

스키마 진화. Archyl에 새 기능이 추가되면 DSL도 커집니다. 하위 호환성을 유지하고 마이그레이션 도구를 제공할 것입니다.

지금 사용해 보세요

Architecture as Code는 오늘부터 모든 Archyl 플랜에서 사용할 수 있습니다. 이미 프로젝트가 있다면:

프로젝트의 Architecture as Code 페이지로 이동합니다
Export를 클릭해 archyl.yaml을 생성합니다
리포지토리에 커밋합니다
공식 GitHub Action을 워크플로우에 추가하면 끝입니다

처음부터 시작한다면 archyl.yaml을 만들고 Import as Project를 사용하세요. 몇 초 만에 완전히 렌더링된 C4 아키텍처를 얻을 수 있습니다.

여러분의 아키텍처도 코드와 같은 엄격함을 누릴 자격이 있습니다. 버전 관리하고, 리뷰하고, 자동화하세요.

C4가 처음이신가요? C4 모델 가이드부터 시작하세요. 초기 아키텍처를 AI로 생성하고 싶다면 AI 기반 아키텍처 발견을 참고하세요. 이미 AI 어시스턴트를 쓰고 있다면 MCP 서버로 연결하세요.