arch-diagram은(는) 무엇을 하나요?
두 가지 방법, 개별적으로 사용하거나 연결(자연어 → Mermaid → HTML)하여 사용할 수 있습니다.
- nl2mmd: 자연어 → Mermaid 방언
- mmd2html: Mermaid 방언 → 인터랙티브 HTML (템플릿: 본 스킬 디렉토리
assets/template.html)
공통 약속: Mermaid 방언
구조 (3계층, HTML의 서버→서비스→하위 서비스와 대응):
- 최상위
subgraph= 서버, 내부에direction TB작성 - 2계층
subgraph= 서비스 (하위 서비스가 있을 때만 서브그래프 생성; 하위 서비스가 없으면 직접 노드로 작성) - 서비스 서브그래프 내의 노드 = 하위 서비스
- 모든 제목은 따옴표 문자열 사용:
subgraph X["제목"],N["제목"]
비고(meta): 제목 내에서 |로 이름과 비고를 구분하며, HTML 생성 후 이름 옆에 연한 작은 글씨로 표시됩니다(서버 규격, 포트, 작업량, 파라미터 등). 비고가 없으면 |를 쓰지 않습니다:
subgraph WEB["Web 엣지 | 이중화 · LAN"]→ 서버명 "Web 엣지", 비고 "이중화 · LAN"WEB_GW["API 게이트웨이 | QPS 3k"]→ 서비스명 + 비고- 파싱 규칙: 마지막
|를 기준으로 왼쪽은 이름, 오른쪽은 비고
엣지 유형은 선 스타일로 표현되며, 고정되어 있습니다:
| 유형 | 선 스타일 | 의미 |
|---|---|---|
| sync | ==> | 데이터 동기화 / 쓰기 |
| call | --> | API / RPC / WS |
| job | -.-> | cron / 예약 작업 / 푸시 |
| data | -.- | 읽기 전용 조회 |
- 엣지 레이블:
==>|"type · 시각 또는 빈도"|, 예:==>|"sync · 07:10 4회/일"|;-->|call|은 설명 생략 가능 - 노드 id는 대문자 스네이크 케이스 사용:
<서버>_<서비스>_<하위서비스>, 예:NAS_SCHED_FLAT - 엣지는 서브그래프(서비스 레벨/서버 레벨)에 연결할 수 있으며, 해당 세분화 수준을 의미합니다.
flowchart LR로 시작; 같은 호스트 내부 엣지는 그대로 작성합니다(HTML 생성 시 오른쪽으로 나갔다 들어오는 순환선으로 그려집니다).
방법 1: nl2mmd (자연어 → Mermaid)
- 엔티티 추출: 머신/호스트/환경 → 서버; 그 위에 설치되거나 실행되는 소프트웨어 → 서비스; 소프트웨어 내의 컴포넌트/기능/작업/라이브러리 → 하위 서비스.
- 관계 추출: 동사를 유형에 매핑 — 동기화/쓰기/미러 → sync; 호출/요청/송수신 → call; 매일/정기/cron/xx:xx/푸시 → job; 읽기/조회/화이트박스 → data. 시간과 빈도는 엣지 레이블에 작성합니다.
- 계층이 애매하면 서비스 레벨에 배치하고, 하위 서비스를 임의로 만들지 마세요.
- 숫자 및 규격 정보(포트, 규격, 작업량, IP 대역 등)는 노드 비고에 넣습니다:
["이름 | 비고"]; 시간과 빈도는 엣지 레이블에 넣습니다. 정보를 누락하지 마세요. - 설명 없이 완전한
flowchart LR코드 블록을 출력합니다.
방법 2: mmd2html (Mermaid → 인터랙티브 HTML)
절차
assets/template.html전체를 읽습니다(약 38KB, 단일 파일 자체 포함, 기본 데이터는examples/sample.mmd의 내용입니다).- Mermaid를 파싱하여(위 방언 기준),
mermaid id → 계층 경로매핑을 만듭니다: 경로는 점으로 연결된서버.서비스.하위서비스(중첩 깊이에 따라 잘림). 엣지가 서브그래프에 연결된 경우 경로는 해당 계층에서 멈춥니다. - 템플릿에서
/*==DATA==*/와/*==DATA-END==*/사이의 전체 블록을 새 데이터 블록으로 교체하며, 나머지 코드는 한 글자도 변경하지 않습니다:
/*==DATA==*/
var ARCH_TITLE='그래프 제목 (터미널 제목 표시줄 및 standalone <title>)';
var ARCH_LSKEY='arch-<slug>'; // localStorage 키, 그래프마다 고유
var TYPE={sync:{c:'#3ecf8e',dash:'10 4',dur:'1.5s',label:'동기화'},
call:{c:'#58a6ff',dash:'6 5',dur:'1.1s',label:'호출'},
job :{c:'#f0a942',dash:'2 4',dur:'0.85s',label:'예약'},
data:{c:'#b18cff',dash:'14 5',dur:'1.9s',label:'읽기'}};
var COLS=[['srvA','srvB'],['srvC']]; // 기본 열 레이아웃: 배열의 각 열 = 서버 id 그룹
var SERVERS=[
{id:'srvA',short:'A',name:'A · 표시명',meta:'비고',ac:'#b18cff',svc:[
{id:'svc1',short:'svc1',name:'서비스1',meta:'',subs:[
{id:'sub1',short:'sub1',name:'하위서비스1',meta:''}]},
{id:'svc2',short:'svc2',name:'서비스2'}]},
];
var EDGES=[
{from:'srvA.svc1.sub1',to:'srvC.svc2',type:'sync',sched:'07:10 4회/일'},
];
/*==DATA-END==*/
필드 규칙:
id는 ASCII 사용 (점 경로가 이 id로 조합됨);name은 한글 가능;short는 연결/로그에 사용되는 짧은 이름meta는 노드/서브그래프 제목에서 마지막|이후 부분, 없으면 생략ac는 색상 팔레트에서 순환:#b18cff #3ecf8e #39d0c4 #58a6ff #f0a942type∈sync|call|job|data(Mermaid 선 스타일에 대응);sched는 엣지 레이블에서 type 이후 부분, 없으면실시간COLS: 엣지 흐름 순서로 대략 정렬(소스는 왼쪽, 싱크는 오른쪽); 단일 서버의 열 생성기는 자동으로 수직 중앙 정렬
- 결과물을 대상 경로에 작성합니다 (프래그먼트 버전). 더블 클릭으로 사용할 수 있도록 하려면 다음과 같이 감쌉니다:
<!doctype html><html lang="ko"><head><meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>{ARCH_TITLE}</title>
<style>html,body{margin:0;padding:0;background:#080b12}#svcarch{min-height:100vh}</style></head><body>
{fragment}</body></html>
QA
- 필수:
<script>를 추출하여node --check실행; 데이터 확인 — 서버/서비스/하위 서비스 수가 Mermaid와 일치하는지, 엣지 수 = Mermaid 엣지 수, 기본 뷰 연결선 수 = 중복 제거된 (from,to,type) 그룹 수. - 브라우저가 있는 경우: 로컬 서버를 반드시 charset 헤더와 함께 실행합니다 (
python3 -m http.server는 charset이 없어 한글이 깨지므로,.html에Content-Type: text/html; charset=utf-8을 추가하는 커스텀 핸들러 필요). 열어서 제목, 개수,▾ servers세분화 수준 전환, 접기 기능을 확인합니다. - 템플릿은 DATA 블록만 변경; 나머지 코드(드래그/접기/영속화)는 다시 구현하지 않습니다.
예제
examples/sample.mmd— 방언 완전 예제 (서버 4대, 엣지 9개, 모든 4가지 선 스타일과 동일 호스트 엣지 포함)examples/sample.html— 템플릿으로 생성된 완성품 (더블 클릭 사용 가능)
생성된 HTML의 내장 기능 (템플릿 외부에서 다시 구현하지 마세요)
드래그 이동(상자 상단 핸들, Alt 키를 누르면 모두 표시), 오른쪽 가장자리 너비 조정, 접이식 상승, 세 가지 세분화 수준 프리셋(servers/services/leaves), 엣지 로그/인스펙터, 레이아웃 및 접힘 상태를 localStorage에 저장(키 = ARCH_LSKEY). 인터페이스 텍스트는 영어입니다.
- 캔버스 확대/축소 및 이동: ctrl+휠로 커서 중심 확대/축소(0.4–2.5배), ctrl을 누르면 마우스가 손 모양으로 변해 캔버스를 드래그 이동; 우측 하단의 백분율 칩을 클릭하면 재설정. 확대/축소 및 이동 상태는 localStorage에 영속화됩니다.
- 내장 편집: Alt 키를 누른 상태에서 임의의 노드 헤더(3계층 모두)를 클릭하면 이름/비고/서버 상자 색상 변경, 하위 항목 추가, 삭제(2단계 확인, 하위 트리와 엣지까지 연쇄 삭제) 가능; Alt 키를 누른 상태에서 연결선을 클릭하면 유형/시각 변경 또는 삭제 가능; Alt 키를 누르고 있을 때 우측 상단에 ⇱ 내보내기 버튼이 나타나며, 최신 상태의 Mermaid를 팝업으로 표시(문법 강조 + 복사), 내부에 ⟲ 재배치 및 ↺ 기본 데이터 복원 기능 포함. 편집 결과는 localStorage에 영속화됩니다.