Archyl에서 첫 번째 아키텍처 프로젝트를 만들고 문서화하는 단계별 가이드

첫 번째 프로젝트 만들기

이 종합 가이드는 Archyl에서 첫 번째 아키텍처 문서 프로젝트를 만드는 방법을 초기 설정부터 팀과의 공유까지 안내합니다.

사전 요구 사항

시작하기 전에:

Archyl 계정 (여기서 가입)
문서화하려는 소프트웨어 시스템
선택사항: 코드베이스 저장소에 대한 접근 권한

1단계: 새 프로젝트 만들기

대시보드에서

Archyl에 로그인합니다
"+ 새 프로젝트" 버튼을 클릭합니다
프로젝트 세부 정보를 입력합니다:
- 이름: 명확하고 설명적인 이름 (예: "이커머스 플랫폼")
- 설명: 시스템의 간략한 개요
- 태그: 정리를 위한 키워드 (예: "백엔드", "마이크로서비스")
**"프로젝트 만들기"**를 클릭합니다

프로젝트 설정

생성 후 프로젝트를 구성합니다:

공개 설정: 공개 또는 비공개
팀 접근: 어떤 팀이 조회/편집할 수 있는지
저장소: AI 디스커버리를 위해 연결 (선택사항)

2단계: 시스템 컨텍스트 이해

다이어그램을 그리기 전에 시스템의 컨텍스트를 이해하세요:

사용자 식별

누가 시스템을 사용하나요?

최종 사용자 (고객, 직원)
관리자
외부 개발자
다른 시스템

외부 시스템 식별

시스템이 무엇과 상호작용하나요?

결제 프로세서
인증 프로바이더
이메일/알림 서비스
분석 플랫폼
파트너 API

3단계: 시스템 컨텍스트 다이어그램 만들기

메인 시스템 추가

빈 캔버스에서 **"+"**를 클릭하거나 우클릭합니다
**"시스템 추가"**를 선택합니다
입력합니다:
- 이름: 시스템 이름
- 설명: 무엇을 하는지
- 유형: 내부 (직접 소유)

사용자 추가

**"+"**를 클릭하고 **"사람 추가"**를 선택합니다
각 사용자 유형을 생성합니다:
- 이름: "고객", "관리자 사용자" 등
- 설명: 역할과 하는 일

외부 시스템 추가

**"+"**를 클릭하고 **"외부 시스템 추가"**를 선택합니다
각 외부 종속성에 대해:
- 이름: "Stripe", "SendGrid" 등
- 설명: 제공하는 것

관계 만들기

소스 요소 위에 마우스를 올립니다
연결 지점에서 대상으로 드래그합니다
라벨 추가: "~를 통해 주문", "~를 통해 이메일 전송" 등
선택적으로 기술 추가: "REST/HTTPS", "SMTP"

4단계: 컨테이너로 들어가기

컨테이너 뷰 열기

메인 시스템을 더블 클릭하여 컨테이너 레벨로 확대합니다.

컨테이너 식별

기술적 구성 요소는 무엇인가요?

애플리케이션: 웹 앱, 모바일 앱, 데스크톱 클라이언트
서비스: API 서버, 백그라운드 워커
데이터 저장소: 데이터베이스, 캐시, 파일 스토리지
메시지 큐: 이벤트 버스, 큐

컨테이너 추가

각 컨테이너에 대해:

**"+"**를 클릭하고 **"컨테이너 추가"**를 선택합니다
입력합니다:
- 이름: "웹 애플리케이션", "API 서버", "PostgreSQL"
- 설명: 책임 영역
- 기술: "React", "Node.js", "PostgreSQL 15"

컨테이너 연결

컨테이너 간 통신 방식을 보여줍니다:

웹 앱 → API 서버: "API 호출 수행 [REST/HTTPS]"
API 서버 → 데이터베이스: "데이터 읽기/쓰기 [SQL]"
API 서버 → 캐시: "세션 데이터 캐시 [Redis 프로토콜]"

5단계: 컴포넌트 추가 (선택사항)

중요한 컨테이너의 경우 컴포넌트로 확대합니다:

컨테이너를 더블 클릭합니다
주요 모듈을 나타내는 컴포넌트를 추가합니다:
- 컨트롤러
- 서비스
- 리포지토리
- 유틸리티

6단계: AI 디스커버리 사용 (선택사항)

AI가 아키텍처 문서화를 도와줍니다:

저장소 연결

프로젝트 설정 → 저장소로 이동합니다
Git 프로바이더를 연결합니다
저장소를 선택합니다

디스커버리 실행

**"디스커버리 시작"**을 클릭합니다
분석이 완료될 때까지 기다립니다
대기 중인 디스커버리를 검토합니다

검토 및 승인

발견된 각 요소를 확인합니다
필요에 따라 이름/설명을 편집합니다
정확한 항목을 승인합니다
부정확한 항목은 거부하거나 수정합니다

7단계: 문서 추가

요소 설명

아무 요소나 클릭하여 상세한 설명을 추가합니다:

목적 및 책임
주요 결정 사항
중요한 참고 사항

아키텍처 결정 기록

중요한 결정을 문서화합니다:

ADR 섹션으로 이동합니다
"새 ADR"을 클릭합니다
작성합니다:
- 제목: "영속성을 위해 PostgreSQL 사용"
- 컨텍스트: 이 결정이 왜 필요했는지
- 결정: 무엇이 결정되었는지
- 결과: 결정의 영향

문서 연결

맥락을 위해 ADR과 문서를 특정 요소에 연결합니다.

8단계: 팀과 공유

팀원 초대

프로젝트 설정 → 팀으로 이동합니다
"초대"를 클릭합니다
이메일 주소를 입력합니다
역할을 할당합니다 (뷰어, 편집자, 관리자)

공유 링크 만들기

계정이 없는 이해관계자를 위해:

도구 모음에서 "공유"를 클릭합니다
접근 옵션을 구성합니다
링크를 복사하여 공유합니다

다이어그램 내보내기

프레젠테이션이나 문서용:

"내보내기"를 클릭합니다
형식을 선택합니다 (PNG, SVG, PDF)
다이어그램을 다운로드합니다

모범 사례

간단하게 시작

시스템 컨텍스트부터 시작하세요
점진적으로 세부 사항을 추가하세요
한 번에 모든 것을 문서화하려고 하지 마세요

커뮤니케이션에 집중

명확하고 설명적인 이름을 사용하세요
설명에 맥락을 추가하세요
가장 중요한 관계를 보여주세요

다음 단계

축하합니다! 첫 번째 아키텍처 문서를 만들었습니다. 계속 학습하세요:

첫 번째 프로젝트 만들기 - Archyl Docs