---
id: wiki-2026-0508-sequence-diagram
title: Sequence Diagram
category: 10_Wiki/Topics
status: verified
canonical_id: self
aliases: [UML Sequence Diagram, Mermaid Sequence, PlantUML Sequence]
duplicate_of: none
source_trust_level: A
confidence_score: 0.9
verification_status: applied
tags: [uml, diagramming, documentation, architecture]
raw_sources: []
last_reinforced: 2026-05-10
github_commit: pending
tech_stack:
  language: text
  framework: Mermaid / PlantUML
---

# Sequence Diagram

## 매 한 줄
> **"매 시간 축으로 actor 간 message 주고받음 시각화"**. 매 UML 의 dynamic behavior 다이어그램, 매 distributed system / API 흐름 / agent loop 설명에 매 standard. 매 2026: AI agent 가 code → diagram 자동 생성 (Claude, Mermaid Chart, Eraser AI), 매 text-as-code (Mermaid) 가 GUI tool 보다 dominant.

## 매 핵심

### 매 element
- **Lifeline**: 매 actor / object 의 vertical line.
- **Message**: 매 horizontal arrow (sync solid, async dashed, return dotted).
- **Activation bar**: 매 처리 중 vertical bar.
- **Combined fragment**: alt / opt / loop / par / critical.
- **Note**: 매 inline annotation.

### 매 vs 다른 다이어그램
- **Flowchart**: control flow, no actors. 매 single perspective.
- **Activity diagram**: state machine 비슷, branching 강조.
- **Component diagram**: static structure.
- **Sequence**: 매 dynamic interaction over time — "누가 누구에게 언제".

### 매 응용
1. API contract docs (REST/gRPC handshake).
2. Auth flow (OAuth, OIDC, SAML).
3. Distributed transaction (saga, 2PC).
4. AI agent loop (user → LLM → tool → LLM → user).
5. Bug reproduction trace.
6. Onboarding 신입 — 매 system overview.

## 💻 패턴

### Mermaid basic
```mermaid
sequenceDiagram
    participant U as User
    participant A as App
    participant DB
    U->>A: GET /profile
    A->>DB: SELECT * FROM users
    DB-->>A: row
    A-->>U: 200 OK (json)
```

### Mermaid with alt/loop
```mermaid
sequenceDiagram
    actor User
    participant API
    participant LLM
    User->>API: question
    loop until done
        API->>LLM: prompt
        LLM-->>API: tool_call
        alt tool == search
            API->>SearchAPI: query
            SearchAPI-->>API: results
        else tool == done
            API-->>User: final answer
        end
    end
```

### PlantUML
```plantuml
@startuml
actor Client
participant "Auth Service" as Auth
participant "Resource API" as API
Client -> Auth: POST /token (creds)
activate Auth
Auth --> Client: JWT
deactivate Auth
Client -> API: GET /data (Bearer JWT)
API -> API: verify JWT
API --> Client: 200 data
@enduml
```

### Generate from code (Claude)
```python
import anthropic
c = anthropic.Anthropic()
diagram = c.messages.create(
    model="claude-opus-4-7",
    max_tokens=2048,
    messages=[{
        "role": "user",
        "content": f"Generate a Mermaid sequenceDiagram from this code:\n```python\n{src}\n```",
    }],
).content[0].text
```

### Embed in MkDocs / GitHub README
````markdown
```mermaid
sequenceDiagram
    A->>B: ping
    B-->>A: pong
```
````

### Mermaid CLI render
```bash
npx -p @mermaid-js/mermaid-cli mmdc -i flow.mmd -o flow.svg -t dark
```

### OAuth 2.0 PKCE 매 example
```mermaid
sequenceDiagram
    participant App
    participant Browser
    participant Auth as AuthServer
    App->>Browser: redirect /authorize?code_challenge
    Browser->>Auth: login
    Auth-->>Browser: redirect ?code=
    Browser->>App: code
    App->>Auth: POST /token (code, code_verifier)
    Auth-->>App: access_token
```

## 매 결정 기준
| 상황 | Approach |
|---|---|
| README / GitHub / Notion | Mermaid (native render) |
| Detailed UML (combined fragments) | PlantUML |
| Whiteboard 빠르게 | Excalidraw |
| Auto-from-code | Claude / Eraser AI |
| Live trace | OpenTelemetry → Jaeger trace view |

**기본값**: Mermaid in markdown.

## 🔗 Graph
- 변형: [[Component-Diagram]]
- Adjacent: [[Mermaid]] · [[PlantUML]] · [[Distributed-Tracing]]

## 🤖 LLM 활용
**언제**: code/log → diagram 자동화, refactor 후 docs 갱신, agent flow 설명.
**언제 X**: 매 매우 복잡한 system — 단일 sequence diagram 으로 부족, 매 break down.

## ❌ 안티패턴
- **너무 많은 lifeline (>7)**: 매 cognitive overload — split.
- **모든 detail 포함**: 매 high-level abstraction 우선.
- **Static structure 표현**: 매 잘못된 diagram type — component diagram 사용.
- **Out of date**: code 와 sync 안 됨 → CI 에서 lint.

## 🧪 검증 / 중복
- Verified (UML 2.5 spec, Mermaid docs, PlantUML docs).
- 신뢰도 A.

## 🕓 Changelog
| 날짜 | 변경 |
|---|---|
| 2026-05-08 | Phase 1 |
| 2026-05-10 | Manual cleanup — Mermaid + AI gen 2026 |