아키텍처 문서를 코드베이스의 일급 시민으로 만드는 기능을 출시했습니다. archyl.yaml을 소개합니다 — 완전한 C4 모델을 기술하고, Git에 저장되며, 코드 리뷰를 거치고, CI/CD를 통해 자동 동기화되는 선언적 DSL입니다.

Architecture as Code: YAML 파일로 전체 C4 모델 정의하기

아키텍처 다이어그램에는 유통기한 문제가 있습니다. 디자인 세션 후에 그리면 일주일 정도는 멋져 보이지만, 코드는 진화하는 반면 다이어그램은 낡아갑니다. 6개월 후, 신입 개발자는 Q2에 통합된 세 개의 서비스를 보여주면서 Q3에 구축된 두 개는 언급하지 않는 Container 다이어그램을 바라보게 됩니다.

Archyl에서는 첫날부터 이 문제에 집중해 왔습니다. AI 발견 기능은 최신 상태 유지에 도움이 됩니다. 비주얼 에디터는 업데이트를 쉽게 만듭니다. 하지만 인프라를 코드로, 정책을 코드로, 모든 것을 코드로 다루는 팀들은 더 근본적인 것을 원했습니다.

그들은 아키텍처가 Git 안에, 그것이 기술하는 코드 옆에 존재하기를 원했습니다. 오늘, 바로 그것을 출시합니다.

`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 클릭 불필요, 수동 동기화 불필요, "다이어그램 업데이트를 잊었다"는 일도 없습니다.

모든 것을 하나의 파일에

DSL은 간소화된 부분집합이 아닙니다 — Archyl이 모델링할 수 있는 모든 범위를 다룹니다:

C4의 네 가지 레벨 모두. 시스템은 컨테이너를 포함하고, 컨테이너는 컴포넌트를 포함하고, 컴포넌트는 코드 엘리먼트를 포함합니다. YAML 중첩이 계층 구조를 직접 반영합니다.

점 표기법을 사용한 관계. Payment Service.API Gateway → Payment Service.Database와 같은 읽기 쉬운 참조로 임의의 두 요소를 연결. UUID 없음, 암호화된 식별자 없음. grep 호환, diff 호환, 사람이 읽을 수 있음.

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

ADR과 문서. Architecture Decision Record를 인라인으로 작성하거나 리포지토리의 폴더를 지정. 프로젝트 문서도 마찬가지.

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이 리포지토리에 존재하기 때문에, 아키텍처 변경은 코드 변경과 동일한 워크플로를 따릅니다:

Branch. 피처 브랜치를 생성하고 YAML을 편집.
Review. 풀 리퀘스트를 열어 팀이 코드 변경과 함께 아키텍처 변경을 리뷰.
Merge. 승인 후 main에 머지.
Sync. Archyl이 변경을 감지하고 다이어그램을 자동 업데이트.

"다이어그램에는 X라고 되어 있지만 코드는 Y를 한다"는 일이 사라집니다. 리뷰를 우회하는 아키텍처 변경도 사라집니다. 아무도 업데이트된 줄 모르는 문서도 사라집니다.

CI/CD 통합

CI/CD 파이프라인과의 일급 통합을 구축했습니다. GitHub용으로 파일 읽기, API 호출, 변경 사항 보고를 모두 처리하는 공식 GitHub Action을 제공합니다.

GitHub Actions (공식 Action):

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'

이게 전부입니다. 설정 3줄로 푸시할 때마다 아키텍처가 동기화됩니다. Action은 커스텀 파일 경로(모노레포용), 셀프 호스팅 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 설정에서 "지금 동기화"를 클릭하면 Archyl이 리포지토리에서 직접 파일을 가져옵니다.

양방향: Export와 Import

워크플로는 단방향이 아닙니다. Archyl의 비주얼 에디터에서 이미 프로젝트를 모델링했나요? 내보내세요:

Export는 현재 모델에서 완전한 archyl.yaml을 생성합니다. 모든 시스템, 컨테이너, 컴포넌트, 관계, 오버레이, ADR, API 컨트랙트, 이벤트 채널, 릴리스 — 모두 깔끔한 YAML로 직렬화됩니다.
Import는 archyl.yaml을 파싱하고 프로젝트의 모든 요소를 생성 또는 업데이트합니다. 멱등성이 있습니다: 같은 파일을 두 번 가져와도 중복이 생기지 않습니다. 요소는 이름으로 매칭되어 upsert됩니다.
Import as Project는 YAML 파일에서 완전히 새로운 프로젝트를 생성합니다. archyl.yaml을 배치하면 원클릭으로 완전히 구성된 프로젝트를 얻을 수 있습니다.

즉, UI에서 시작해 YAML로 내보내고, Git에 커밋하고, 코드 퍼스트 워크플로로 전환할 수 있습니다 — 또는 그 반대도 가능합니다. 어떤 접근 방식에도 락인이 없습니다.

스마트 참조 해결

DSL의 가장 까다로운 부분 중 하나는 관계, 오버레이, 이벤트, API 컨트랙트에서의 요소 참조 해결입니다. 이를 자연스럽게 처리하는 리졸버를 구축했습니다:

짧은 이름은 모호하지 않을 때 작동: API Gateway는 해당 이름을 가진 요소가 하나뿐이면 직접 해결됩니다.
점 표기법으로 모호성 해소: Payment Service.API Gateway vs Analytics.API Gateway.
모든 깊이 지원: 깊이 중첩된 참조를 위해 System.Container.Component.CodeElement.

리졸버는 가능한 모든 경로 깊이에서 각 요소를 인덱싱하므로, 항상 가장 짧은 모호하지 않은 참조를 사용할 수 있습니다. 내보내기는 같은 로직을 역방향으로 사용하여 가장 읽기 쉬운 참조를 생성합니다.

부작용 없는 유효성 검사

YAML이 유효한지 확신이 없나요? /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 서버로 연결하세요.

Architecture as Code: YAML 파일로 전체 C4 모델 정의하기 - Archyl Blog