Mermaid 설명

Mermaid 설명

Mermaid는 텍스트로 다이어그램을 작성하는 JavaScript 기반 다이어그램 도구입니다. 코드를 작성하면 브라우저에서 자동으로 Flowchart, Sequence Diagram, Class Diagram, ERD 등의 그래픽으로 변환해 줍니다.

1. Mermaid란?

Mermaid의 핵심 철학은 다음과 같습니다.

다이어그램을 이미지 편집 도구로 그리는 대신 텍스트 코드로 정의한다.

예를 들어 다음 코드만 작성하면:

flowchart TD
    A[사용자] --> B[웹 브라우저]
    B --> C[웹 서버]
    C --> D[데이터베이스]

다음과 같은 구조의 다이어그램이 생성됩니다.

사용자
  ↓
웹 브라우저
  ↓
웹 서버
  ↓
데이터베이스

즉, Mermaid는 Diagram as Code 방식의 대표적인 도구입니다.

2. Mermaid 개발 배경

기존 다이어그램 제작 방식에는 몇 가지 문제가 있었습니다.

기존 방식

Microsoft Visio, PowerPoint, Illustrator 등의 그래픽 도구를 이용하여 직접 도형을 배치했습니다.

예를 들어 시스템 구성도를 만들려면:

[서버]
   │
   ├──── [DB]
   │
   ├──── [Redis]
   │
   └──── [API]

각각의 박스와 선을 직접 배치해야 합니다.

문제는 시스템 규모가 커지면 수정이 매우 어려워진다는 것입니다.

예를 들어 서버 하나를 추가하면:

기존 다이어그램
      ↓
도형 추가
      ↓
선 연결
      ↓
위치 조정
      ↓
크기 조정
      ↓
전체 레이아웃 수정

이러한 문제를 해결하기 위한 방향이 텍스트 기반 다이어그램입니다.

3. Mermaid의 탄생

Mermaid는 Knut Sveinsson이 개발한 프로젝트로 알려져 있으며, 초기에는 개발자가 문서 안에서 쉽게 다이어그램을 표현할 수 있도록 만들어졌습니다.

핵심 아이디어는 매우 단순했습니다.

텍스트
  ↓
Mermaid 파서
  ↓
다이어그램 구조 생성
  ↓
SVG
  ↓
브라우저 표시

즉, 사람이 직접 그래픽을 그리는 것이 아니라 문법으로 구조를 설명하면 Mermaid가 그래픽을 생성합니다.

4. Markdown과 Mermaid

Mermaid가 크게 성장할 수 있었던 중요한 이유 중 하나가 Markdown과의 결합입니다.

예를 들어 Markdown 문서에서:

```mermaid
flowchart TD
    A[Client] --> B[Server]
    B --> C[Database]
```

처럼 작성할 수 있습니다.

따라서 다음과 같은 문서에 활용할 수 있습니다.

• 기술 문서
• 개발 설계서
• API 문서
• README
• 프로젝트 문서
• 교육 자료
• 시스템 구성도
• ERD
• 프로그램 흐름도

5. Mermaid의 발전

초기 Mermaid는 비교적 단순한 Flowchart와 Sequence Diagram 중심이었습니다.

이후 다양한 다이어그램 문법이 추가되면서 현재는 상당히 많은 종류의 다이어그램을 지원합니다.

대표적인 종류는 다음과 같습니다.

종류	용도
Flowchart	프로그램 흐름
Sequence Diagram	시스템 간 통신
Class Diagram	객체지향 설계
ER Diagram	데이터베이스 설계
State Diagram	상태 변화
Gantt	프로젝트 일정
Pie Chart	비율
User Journey	사용자 경험
Git Graph	Git 브랜치
Mindmap	개념 구조
Timeline	시간 흐름
Architecture	시스템 아키텍처

6. Mermaid의 기본 동작 구조

Mermaid는 대략 다음과 같이 동작합니다.

flowchart TD
    A[Mermaid Source] --> B[Parser]
    B --> C[Diagram Model]
    C --> D[Renderer]
    D --> E[SVG]
    E --> F[Browser]

개발자가 작성하는 것은 Mermaid Source입니다.

A --> B
B --> C

Mermaid 내부에서 이를 해석하고 SVG 형태로 렌더링합니다.

7. 가장 기본적인 Flowchart

코드

flowchart TD
    A[시작] --> B[로그인]
    B --> C{인증 성공?}
    C -->|Yes| D[메인 화면]
    C -->|No| E[로그인 실패]
    E --> B

문법

flowchart TD

여기서 TD는 방향입니다.

방향	의미
TD	Top → Down
TB	Top → Bottom
BT	Bottom → Top
LR	Left → Right
RL	Right → Left

예를 들어:

flowchart LR
    A[Client] --> B[API] --> C[Database]

왼쪽에서 오른쪽으로 흐릅니다.

8. 노드 작성법

가장 기본적인 노드는 다음과 같습니다.

flowchart TD
    A[일반 사각형]
    B(둥근 모서리)
    C{조건}
    D((원))

대표적으로:

A[텍스트]
B(텍스트)
C{텍스트}
D((텍스트))

를 사용할 수 있습니다.

9. 연결선

기본 연결은:

flowchart TD
    A --> B

화살표 방향을 바꿀 수도 있습니다.

flowchart LR
    A --> B
    B -.-> C
    C ==> D

의미는 대략 다음과 같습니다.

문법	의미
-->	일반 화살표
---	일반 선
-.->	점선 화살표
==>	굵은 화살표

10. 조건문

프로그램 설계에서 매우 자주 사용하는 기능입니다.

flowchart TD
    A[로그인 요청] --> B{아이디와 비밀번호 확인}
    B -->|성공| C[로그인]
    B -->|실패| D[오류 메시지]

조건 노드는 {}를 사용합니다.

B{조건}

그리고:

B -->|성공| C
B -->|실패| D

형태로 분기합니다.

11. Subgraph

큰 시스템을 구성할 때 매우 중요한 기능입니다.

flowchart TD

    subgraph Client["Client 영역"]
        A[Web Browser]
        B[Mobile App]
    end

    subgraph Server["Server 영역"]
        C[FastAPI]
        D[WebSocket]
    end

    subgraph Database["Database 영역"]
        E[(PostgreSQL)]
        F[(Redis)]
    end

    A --> C
    B --> C
    C --> D
    C --> E
    D --> F

실제 시스템 구성도를 만들 때 매우 유용합니다.

12. Sequence Diagram

서버 간 통신을 표현할 때 사용합니다.

sequenceDiagram
    participant Client
    participant Server
    participant DB

    Client->>Server: 로그인 요청
    Server->>DB: 사용자 조회
    DB-->>Server: 사용자 정보
    Server-->>Client: 로그인 성공

예를 들어 REST API 동작을 표현할 수 있습니다.

sequenceDiagram
    participant Browser
    participant API
    participant MariaDB

    Browser->>API: GET /users
    API->>MariaDB: SELECT users
    MariaDB-->>API: User List
    API-->>Browser: JSON Response

13. ERD

데이터베이스 설계에서도 Mermaid를 사용할 수 있습니다.

erDiagram
    USER {
        int user_id PK
        string username
        string password
        datetime created_at
    }

    ORDER {
        int order_id PK
        int user_id FK
        decimal amount
        datetime created_at
    }

    USER ||--o{ ORDER : creates

관계형 데이터베이스 설계 문서에 상당히 유용합니다.

14. Class Diagram

객체지향 프로그램을 설계할 때 사용할 수 있습니다.

classDiagram

    class User {
        +int id
        +string name
        +login()
        +logout()
    }

    class Order {
        +int id
        +decimal amount
        +create()
        +cancel()
    }

    User "1" --> "*" Order

C#, Java, Python 등의 클래스 설계 문서에 사용할 수 있습니다.

15. State Diagram

장치나 프로그램의 상태 변화를 표현할 수 있습니다.

예를 들어 IoT 장치라면:

stateDiagram-v2
    [*] --> Boot
    Boot --> Connecting
    Connecting --> Connected
    Connected --> Running
    Running --> Error
    Error --> Connecting
    Running --> Shutdown
    Shutdown --> [*]

ESP32, Raspberry Pi, 서버 등의 상태 머신 설계에 적합합니다.

16. Git Graph

Git 브랜치 구조도 표현할 수 있습니다.

gitGraph
    commit
    commit
    branch develop
    checkout develop
    commit
    commit
    checkout main
    merge develop
    commit

개발 프로젝트의 브랜치 전략을 설명할 때 사용할 수 있습니다.

17. Gantt Chart

프로젝트 개발 일정을 표현할 수도 있습니다.

gantt
    title 프로젝트 개발 일정
    dateFormat YYYY-MM-DD

    section 분석
    요구사항 분석 :a1, 2026-08-01, 7d

    section 설계
    시스템 설계 :a2, after a1, 10d

    section 개발
    Backend 개발 :a3, after a2, 20d
    Frontend 개발 :a4, after a2, 20d

    section 테스트
    통합 테스트 :a5, after a3, 10d

18. Mermaid와 실제 개발 문서

Mermaid의 가장 큰 장점은 다이어그램 자체가 소스 코드가 된다는 점입니다.

예를 들어 다음 프로젝트 구조를 문서화한다고 가정합니다.

flowchart TD
    User[사용자]
    Web[Web Browser]
    API[FastAPI]
    WS[WebSocket]
    DB[(MariaDB)]
    Redis[(Redis)]

    User --> Web
    Web --> API
    Web --> WS
    API --> DB
    API --> Redis
    WS --> Redis

이것을 Git 저장소에 .md 파일로 저장하면 됩니다.

예:

project/
├── README.md
├── docs/
│   ├── architecture.md
│   ├── api.md
│   ├── database.md
│   └── websocket.md
└── src/

그리고 architecture.md에 Mermaid 코드를 넣습니다.

19. Mermaid의 장점

① 텍스트 기반

그래픽 프로그램 없이 다이어그램을 수정할 수 있습니다.

② Git 관리

Mermaid 소스는 일반 텍스트이므로 Git으로 버전 관리할 수 있습니다.

Version 1
    ↓
Version 2
    ↓
Version 3

다이어그램 변경 이력도 추적할 수 있습니다.

③ 자동화

프로그램이 Mermaid 코드를 생성하도록 만들 수도 있습니다.

예를 들어 DB 구조를 분석하여 ERD Mermaid 코드를 자동 생성할 수 있습니다.

Database
   ↓
Schema 분석
   ↓
Table 분석
   ↓
Relation 분석
   ↓
Mermaid ERD 생성

④ 문서와 코드의 일치

프로그램 설계와 실제 문서를 함께 관리하기 좋습니다.

20. Mermaid의 단점

Mermaid가 모든 다이어그램 작업에 적합한 것은 아닙니다.

항목	Mermaid
빠른 시스템 구성도	매우 좋음
소프트웨어 설계	매우 좋음
ERD	좋음
Sequence Diagram	매우 좋음
Git 문서화	매우 좋음
정밀한 그래픽 디자인	제한적
자유로운 도형 배치	제한적
인쇄용 고급 디자인	제한적
복잡한 회로도	부적합

따라서 개발 문서와 시스템 설계에는 매우 적합하지만 전문 그래픽 디자인 도구를 완전히 대체하는 목적은 아닙니다.

21. 실제 웹페이지에서 Mermaid 사용

Mermaid는 JavaScript 라이브러리이므로 웹페이지에서도 사용할 수 있습니다.

<!DOCTYPE html>
<html lang="ko">
<head>
    <meta charset="UTF-8">
    <title>Mermaid Example</title>

    <script type="module">
        import mermaid from
            "https://cdn.jsdelivr.net/npm/mermaid@latest/dist/mermaid.esm.min.mjs";

        mermaid.initialize({
            startOnLoad: true
        });
    </script>
</head>

<body>

<h1>시스템 구성도</h1>

<pre class="mermaid">
flowchart TD
    A[사용자] --> B[웹 브라우저]
    B --> C[FastAPI]
    C --> D[(MariaDB)]
</pre>

</body>
</html>

브라우저가 Mermaid 코드를 읽고 다이어그램을 생성합니다.

22. FastAPI 시스템에 적용한 예제

웹 시스템을 설계한다고 하면 다음과 같이 표현할 수 있습니다.

flowchart TD

    U[사용자]

    subgraph Frontend
        W[Web Browser]
        JS[JavaScript]
    end

    subgraph Backend
        API[FastAPI]
        WS[WebSocket]
    end

    subgraph Data
        DB[(MariaDB)]
        R[(Redis)]
    end

    U --> W
    W --> JS
    JS --> API
    JS --> WS

    API --> DB
    API --> R
    WS --> R

이런 방식으로 프로그램 설계서 자체를 Mermaid 코드 중심으로 작성할 수 있습니다.

23. Mermaid의 핵심 가치

Mermaid를 한 문장으로 정리하면:

다이어그램
    ↓
그래픽 파일

방식에서

다이어그램
    ↓
텍스트 코드
    ↓
렌더링
    ↓
SVG

방식으로 바꾼 도구라고 볼 수 있습니다.

특히 소프트웨어 개발에서는 다음 조합이 매우 강력합니다.

flowchart LR
    Markdown --> Mermaid
    Mermaid --> SVG
    Git --> VersionControl[버전 관리]
    Markdown --> Documentation[기술 문서]

즉, Markdown + Mermaid + Git을 결합하면 소프트웨어 설계도와 기술 문서를 코드처럼 관리할 수 있습니다.