이 다이어그램의 핵심은 저장소를 처음 보는 사람이 믿을 수 있어야 한다는 점입니다. 존재하지 않는 서비스를 만들거나 데이터베이스를 빼먹은 다이어그램은 없는 것보다 나쁘므로, 여기 있는 모든 것은 코드가 실제로 보여주는 내용을 그림으로 나타내는 것입니다.
1. 그리기 전에 조사
저장소 루트에서 scripts/survey.py를 실행합니다(이 기술의 경로는 해당 폴더를 기준으로 함).
python3 scripts/survey.py /path/to/repo > /tmp/mermaid-survey.txt
이 스크립트는 파일 수가 포함된 모듈 목록, 매니페스트, 진입점, 선언된 종속성에서 찾은 외부 서비스, 데이터 모델 소스, 그리고 모듈 간 가져오기 그래프(가져오기 횟수 포함)를 출력합니다. 각각의 가져오기 엣지는 실제 import 문에서 비롯되므로, 해당 엣지를 아키텍처 다이어그램의 백본으로 사용하세요. 한 모듈이 대부분의 코드를 차지하고 분할이 필요하다면 --depth 3 옵션을 사용하여 다시 실행하세요.
그런 다음 스크립트가 볼 수 없는 항목을 읽으세요.
- README 및 기존 문서: 팀이 이미 사용하는 이름을 확인
- 진입점: 자체 프로세스로 실행되는 항목(서버, 워커, CLI, 크론 작업, 람다)을 확인
- 배포 설정(Dockerfile, compose 파일, fly.toml, serverless/CDK, Terraform): 개별적으로 배포되는 항목과 통신 대상을 확인
- 프로세스 경계를 넘는 호출: HTTP 클라이언트 및 기본 URL, 큐 게시자 및 소비자, 외부 서비스용 SDK 클라이언트
각 상자와 화살표를 뒷받침하는 파일을 간단히 기록해 두세요. 이 내용은 출력의 출처 목록이 됩니다.
사용자가 "데이터베이스의 ER 다이어그램"과 같은 하나의 다이어그램만 요청하면 해당 다이어그램만 만들되, 그래도 먼저 조사하세요.
2. 아키텍처 개요
배포 가능한 구성 요소와 그 내부 모듈, 사용하는 데이터 저장소 및 외부 서비스를 flowchart로 그리세요. 6~20개의 노드를 목표로 하세요. 더 큰 저장소는 더 많은 상자를 추가하는 대신 배포 가능한 단위별로 서브그래프로 그룹화하세요.
- 노드는 개발자가 이름을 붙일 만한 것입니다: "API 서버", "웹 앱", "firehose 소비자", "PostgreSQL", "Stripe". README의 팀 이름이나 패키지 이름을 사용하세요.
- 화살표는 호출자에서 피호출자 방향을 가리키며, 프로세스를 넘나들 때는 방법을 명시하세요("REST /api", "SQL", "S3 업로드"). 인-프로세스 임포트는 레이블을 남기지 마세요.
- 시스템 설명에 필요하지 않은 것은 제거하세요: 모든 사람이 임포트하는 유틸리티 모듈, 타입 전용 패키지, 테스트, 빌드 스크립트. 중요하다면 텍스트로 언급하세요.
- 확실하지 않은 것은 그리지 마세요. 연결이 의심되지만 코드를 찾을 수 없다면 생략하고 텍스트로 그 사실을 밝히세요.
모양 및 스타일 규칙은 references/diagram-guide.md에 있습니다.
3. 데이터 모델
조사 결과 데이터 모델 소스가 있는 경우에만 erDiagram을 그리세요. 소스가 없으면 한 문장으로 그 사실을 밝히고 건너뛰세요. API 타입이나 변수 이름에서 테이블을 유추하지 마세요. 추측한 스키마는 실제 스키마만큼 권위 있어 보이기 때문입니다.
- 마이그레이션이 진실입니다 (존재할 경우). 순서대로 적용하여 나중의
ALTER,DROP, 이름 변경이 우선 적용됩니다. ORM 모델이 마이그레이션과 일치하지 않으면 마이그레이션을 따르고 불일치를 기록하세요. - 두 세트의 마이그레이션(예: 이전
supabase/migrations/와 현재drizzle/폴더)은 일반적으로 하나가 오래된 것입니다. 앱의 마이그레이션 명령이나 ORM 설정(drizzle.config.*,prisma/schema.prisma, package.json의migrate스크립트)이 가리키는 마이그레이션을 따르고, 오래된 것은 텍스트에 이름을 명시하세요. - 키와 행을 식별하는 열을 표시하세요: 기본 키, 외래 키, 고유 열, 그리고 독자가 엔티티를 인식하는 데 필요한 몇 개의 열. 타임스탬프 및 기타 부기 열은 중요하지 않으면 생략하세요.
- 제약 조건에서 카디널리티를 읽으세요. NOT NULL 외래 키는 부모 쪽에서 정확히 하나, NULL 허용은 0 또는 하나, 고유 외래 키는 관계를 일대일로 만듭니다. 각 관계에 짧은 동사구로 레이블을 붙이세요.
- 약 15개 엔티티를 넘으면 하나의 큰 테이블로 그리는 대신 도메인별로 다이어그램을 분할하세요.
4. 파일 작성
docs/architecture.md 파일을 작성하거나, 이미 존재하면 업데이트하세요. 저장소가 문서를 다른 곳에 보관한다면 그 관행을 따르고, 사용자가 경로를 지정했다면 그 경로를 사용하세요. 각 다이어그램에 대해:
## Architecture
다이어그램이 보여주는 내용과 생략된 내용에 대한 두세 문장.
<!-- mermaid-gen:start architecture -->
```mermaid
flowchart LR
...
```
<!-- mermaid-gen:end architecture -->
**출처:** `cmd/server/main.go`, `internal/handler/`, `fly.toml`
마커 주석은 이후 실행 시 수동으로 편집된 설명을 건드리지 않고 다이어그램만 교체할 수 있게 해줍니다. 기존 파일을 업데이트할 때는 마커 사이의 내용과 그 주변의 설명 및 출처만 변경하세요.
5. 렌더링 확인
파일에 대해 scripts/lint_mermaid.py를 실행하세요:
python3 scripts/lint_mermaid.py /path/to/repo/docs/architecture.md
이 스크립트는 렌더링을 가장 자주 깨뜨리는 실수(따옴표로 묶이지 않은 레이블의 특수 문자, 노드 ID로 사용된 end 같은 예약어, 닫히지 않은 subgraph, 잘못된 ER 관계 또는 속성)를 잡아냅니다. 종료하기 전에 모든 오류를 수정하세요. mmdc(mermaid-cli)가 설치되어 있으면 함께 렌더링하세요.
마지막으로 사용자에게 파일 위치, 각 다이어그램이 다루는 내용, 그리고 생략했거나 확인할 수 없었던 내용을 알려주세요.