핵심 개념

이 페이지에서는 Archyl을 사용할 때 접하게 되는 주요 개념을 설명합니다.

프로젝트

프로젝트는 아키텍처 문서의 최상위 컨테이너입니다. 각 프로젝트는 문서화하려는 소프트웨어 시스템 또는 제품을 나타냅니다.

프로젝트에는 다음이 포함됩니다:

아키텍처 다이어그램 (시스템, 컨테이너, 컴포넌트, 코드)
요소 간 관계
문서 및 ADR
사용자 플로우
설정 및 팀 접근 권한

요소

요소는 아키텍처 다이어그램의 구성 요소입니다:

시스템

시스템은 소프트웨어 시스템을 나타냅니다 — 가장 높은 수준의 추상화입니다. C4 모델에서 이것이 문서화하는 대상입니다.

내부 시스템: 직접 소유하고 유지 관리하는 시스템
외부 시스템: 상호작용하는 서드파티 시스템 (API, SaaS 제품)

컨테이너

컨테이너는 코드를 실행하거나 데이터를 저장하는 별도로 배포/실행 가능한 단위입니다:

웹 애플리케이션
모바일 앱
API 서버
데이터베이스
메시지 큐
파일 시스템

컴포넌트

컴포넌트는 컨테이너 내 관련 기능의 그룹입니다:

컨트롤러
서비스
리포지토리
모듈

코드 요소

코드는 가장 낮은 수준을 나타냅니다 — 실제 코드 구조:

클래스
인터페이스
함수
모듈

관계

관계는 요소가 서로 어떻게 통신하거나 의존하는지 보여줍니다. 다음을 포함합니다:

상호작용을 설명하는 라벨 (예: "읽기 대상", "이벤트 전송 대상")
선택적 기술 정보 (예: "REST/HTTPS", "gRPC", "AMQP")
흐름을 나타내는 방향

오버레이

오버레이는 기본 구조를 변경하지 않고 다이어그램을 구성하는 데 도움이 되는 시각적 그룹입니다. 용도:

관련 요소 그룹화
특정 영역 강조
시각적 경계 생성

레벨

Archyl은 C4 모델의 4가지 추상화 레벨을 사용합니다:

레벨	표시 내용	대상
시스템 컨텍스트	환경 내의 시스템	모든 사람
컨테이너	높은 수준의 기술 구성 요소	기술 인력
컴포넌트	컨테이너 내 컴포넌트 구조	개발자
코드	코드 수준 세부 사항	개발자

조직 및 팀

조직

조직은 계정의 워크스페이스입니다. 다음을 포함합니다:

모든 프로젝트
팀원
청구 정보
설정

팀

팀은 프로젝트에 대한 접근 권한을 구성하는 데 도움이 됩니다:

부서, 프로젝트 또는 책임별로 팀원 그룹화
특정 프로젝트에 대한 접근 권한 제어
팀 수준에서 권한 관리

역할

Archyl에는 세 가지 역할이 있습니다:

역할	조회 가능	편집 가능	관리 가능
뷰어	예	아니오	아니오
편집자	예	예	아니오
관리자	예	예	예

AI 디스커버리

AI 디스커버리는 코드베이스를 자동으로 분석하여 아키텍처 요소를 발견하는 프로세스입니다:

Git 저장소에 연결
코드 구조와 패턴 분석
시스템, 컨테이너, 컴포넌트 식별
요소 간 관계 생성
문서 제안 생성

ADR

**아키텍처 결정 기록 (ADR)**은 중요한 아키텍처 결정을 문서화합니다:

무엇이 결정되었는지
왜 결정되었는지
어떤 대안이 고려되었는지
결과가 무엇인지

플로우

사용자 플로우는 사용자나 데이터가 시스템을 통해 어떻게 이동하는지 문서화합니다:

단계별 시퀀스
아키텍처 요소에 대한 링크
시각적 플로우 다이어그램

핵심 개념 - Archyl Docs