김현석(TwoTwo-me)

mermaid-vertical-guide

7 min read

세로형 Mermaid 가이드

메인 인덱스 | CCG-Platform | Cross-Repo 분석

이 가이드는 CCG-Platform 문서에서 ASCII 박스 다이어그램 대신 Mermaid를 사용할 때, 세로형 페이지와 좁은 문서 폭에 맞게 다이어그램을 정리하기 위한 기준입니다.

왜 Mermaid로 바꾸는가

  • ASCII 박스 다이어그램은 줄 폭에 강하게 묶여서 모바일, 사이드바, 좁은 문서 레이아웃에서 쉽게 깨집니다.
  • Mermaid는 수동 공백 정렬보다 구조와 관계를 직접 표현하기 쉬워서 유지보수가 편합니다.
  • 문서가 길어질수록 “정렬”보다 “의미”가 중요하므로, 자동 레이아웃이 있는 다이어그램 문법이 더 안정적입니다.

기본 원칙

  • 기본 방향은 flowchart TB 또는 flowchart TD를 사용합니다.
  • 다이어그램 하나에는 질문 하나만 담습니다. 계층 구조, 라우팅, 상태 전이, DB 관계를 한 장에 다 넣지 않습니다.
  • 너비를 넓히지 말고 깊이를 늘립니다. 가로로 5개를 늘어놓기보다 세로 계층 3~4단으로 쪼갭니다.
  • 큰 박스를 공백으로 흉내 내지 말고 subgraph로 계층을 표현합니다.
  • 긴 문장은 한 줄에 우겨 넣지 말고 <br/>로 줄을 나눕니다.
  • 노드 이름은 짧게 두고, 세부 설명은 2~4줄 안에서 끝냅니다.
  • 박스 모양을 맞추기 위한 수동 공백, ┌─┐, │ │, ════ 같은 ASCII 장식은 쓰지 않습니다.
  • 파일 트리, CLI 출력, YAML 예시는 Mermaid로 바꾸지 않고 코드 블록으로 유지합니다.

문법 선택 기준

문서 목적권장 문법이유
계층형 아키텍처flowchart TB표현 계층, API 계층, 인프라 계층처럼 위에서 아래로 읽기 좋습니다.
요청/데이터 라우팅flowchart TB세로 페이지에서 URL, 서비스, 목적지를 순서대로 내리기 좋습니다.
단계별 상태 변화stateDiagram-v2상태 전이와 종료 지점을 명확하게 표현할 수 있습니다.
엔터티 관계erDiagramFK 관계를 ASCII 목록보다 짧고 명확하게 담고 있습니다.
사람/서비스 간 상세 상호작용sequenceDiagram순서 자체가 핵심일 때만 사용합니다. 폭이 넓어지기 쉬우므로 남용하지 않습니다.

세로형 레이아웃 규칙

  • 최상단에는 사용자나 진입점, 최하단에는 인프라나 결과를 둡니다.
  • 한 레벨에 노드가 3개를 넘으면 새 subgraph로 묶거나 다이어그램을 둘로 나눕니다.
  • 비교가 필요한 경우에만 작은 영역 안에서 direction LR를 씁니다.
  • 서비스 설명은 이름<br/>역할<br/>역할 형태로 정리합니다.
  • 화살표 라벨은 짧게 씁니다. 긴 API 목록은 별도 노드로 빼는 편이 낫습니다.
  • 노드 하나가 문단처럼 길어지면 다이어그램이 아니라 표나 본문이어야 할 가능성이 큽니다.
  • 같은 문서 안에서는 같은 개념에 같은 이름을 씁니다. 예: Portal Backend, portal-backend, Portal API를 섞지 않습니다.

ASCII 대신 쓸 패턴

1. 계층형 아키텍처

flowchart TB
    subgraph Presentation["표현 계층"]
        UI["CCGP-ui<br/>React 프론트엔드"]
    end

    subgraph API["API 계층"]
        Portal["portal-backend<br/>인증 / 과금 / 임대"]
        PodMgr["PodManager_V2<br/>Pod 수명주기 / 라우팅"]
    end

    subgraph Infra["인프라 계층"]
        EKS["AWS EKS"]
        Traefik["Traefik"]
    end

    UI --> Portal --> PodMgr --> EKS
    PodMgr --> Traefik

2. 상태 머신

stateDiagram-v2
    [*] --> IDLE
    IDLE --> CREATING: 생성 요청
    CREATING --> RUNNING
    RUNNING --> ACTIVE: 사용자 접속
    ACTIVE --> EXPIRED
    ACTIVE --> DELETED

3. DB 관계

erDiagram
    USERS ||--o{ CONTAINER_RENTALS : rents
    CONTAINER_RESOURCES ||--o{ CONTAINER_RENTALS : selected_by

언제 Mermaid보다 표가 나은가

  • 설정 변수 목록
  • 레포지토리 비교
  • 장단점 비교
  • API 엔드포인트 목록
  • 운영 체크리스트

관계보다 항목 비교가 중심이면 Mermaid보다 Markdown 표가 더 읽기 좋습니다.

작성 체크리스트

  • 이 다이어그램이 세로 스크롤로 자연스럽게 읽히는가
  • 가장 긴 노드가 페이지 폭을 깨지 않는가
  • 화살표 라벨이 문장 대신 짧은 신호 역할만 하는가
  • ASCII 장식 없이도 계층과 흐름이 보이는가
  • 상태, 흐름, 관계가 서로 다른 문법으로 분리되어 있는가
  • 같은 내용을 다이어그램과 본문에 중복해서 과하게 반복하지 않았는가

CCG-Platform 적용 메모

  • cross-repo-analysis.md에서는 아키텍처, 의존 관계, 라우팅, 상태 전이, DB 추론을 세로형 Mermaid로 통일합니다.
  • Appendix의 파일 트리처럼 코드 구조를 그대로 보여줘야 하는 구간은 ASCII 트리 코드를 유지합니다.
  • 넓은 sequenceDiagram이 꼭 필요하지 않다면 flowchart TB로 다시 풀어 쓰는 편이 문서 폭에 더 안정적입니다.

그래프 뷰

백링크