lidorshimoni/visualize

Visualize: 아키텍처 및 흐름 시각화 패턴

의도

텍스트 기반의 아키텍처, 복잡한 알고리즘, 멀티 에이전트 상호작용, 데이터 모델을 표준 Mermaid 구문을 사용하여 명확한 시각적 다이어그램으로 변환합니다.

이론적 기반

인지 부하 이론과 C4 소프트웨어 아키텍처 모델(Brown, 2018)에 뿌리를 두고 있습니다. 시각적 모델은 추상적인 시스템 설명을 구체화하여 경계, 데이터 흐름, 상태 전이를 사람과 에이전트 모두가 즉시 검증할 수 있도록 합니다.

표준 다이어그램 아키타입

1. 컴포넌트 및 경계 아키텍처 (C4 컨테이너 / 컴포넌트)

아키텍처 계층을 표현하기 위해 flowchart TD 또는 flowchart LR과 서브그래프를 사용합니다:

flowchart TD
    subgraph Client["클라이언트 계층"]
        Web["웹 애플리케이션 (React)"]
        CLI["CLI 도구 (Python)"]
    end

    subgraph Gateway["API 게이트웨이"]
        Proxy["리버스 프록시 / Nginx"]
        Auth["인증 서비스 (JWT)"]
    end

    subgraph Core["핵심 서비스"]
        App["애플리케이션 엔진"]
        Worker["비동기 백그라운드 워커"]
    end

    subgraph Data["영속성 계층"]
        DB[("PostgreSQL")]
        Queue[("Redis 큐")]
    end

    Web --> Proxy
    CLI --> Proxy
    Proxy --> Auth
    Auth --> App
    App --> Queue
    Queue --> Worker
    Worker --> DB
    App --> DB

2. 요청 / 응답 및 프로토콜 흐름 (시퀀스 다이어그램)

시간 순서 상호작용을 보여주기 위해 활성 라이프라인이 있는 sequenceDiagram을 사용합니다:

sequenceDiagram
    autonumber
    actor User
    participant Agent as 코딩 에이전트
    participant Tool as 도구 실행기
    participant Git as 버전 관리

    User->>Agent: 기능 구현 요청
    Agent->>Tool: 실패 테스트 실행 (Red)
    Tool-->>Agent: 예상대로 테스트 실패
    Agent->>Tool: 최소 코드 작성 (Green)
    Agent->>Tool: 테스트 스위트 실행
    Tool-->>Agent: 모든 테스트 통과
    Agent->>Git: 원자적 변경 커밋
    Git-->>Agent: 커밋 해시 생성
    Agent-->>User: 완료된 작업 보고

3. 상태 머신 및 라이프사이클 (상태 다이어그램)

엔티티 상태, 작업 상태 또는 연결 라이프사이클에 stateDiagram-v2를 사용합니다:

stateDiagram-v2
    [*] --> 초안
    초안 --> 검토중: 검토 제출
    검토중 --> 승인됨: 검증 통과
    검토중 --> 변경필요: 차단 요인 발견
    변경필요 --> 검토중: 수정 사항 재제출
    승인됨 --> 진행중: 구현 시작
    진행중 --> 완료됨: 모든 테스트 통과
    완료됨 --> [*]

4. 데이터 모델 및 관계 (엔티티-관계 다이어그램)

관계형 스키마 및 도메인 모델에 erDiagram을 사용합니다:

erDiagram
    PROJECT ||--o{ SPECIFICATION : 포함
    SPECIFICATION ||--o{ TICKET : 분해
    TICKET ||--o{ COMMIT : 구현
    TICKET {
        string id PK
        string title
        string status
        string blocked_by
    }

Mermaid 구문 안전 규칙

1. 특수 문자가 포함된 노드 라벨은 항상 인용:
   • id[Label (Extra Info)] 대신 id["Label (Extra Info)"].
2. 지원되는 다이어그램 유형만 사용:
   • Flowcharts (flowchart TD), Sequence (sequenceDiagram), State (stateDiagram-v2), Class (classDiagram), ER (erDiagram).
3. 노드 텍스트에 원시 HTML 사용 금지: 노드 문자열 내부에는 순수 마크다운 또는 깨끗한 텍스트를 사용합니다.

---

인용 및 출처

1. C4 소프트웨어 아키텍처 모델: Brown, S. (2018). Software Architecture for Developers: Visualise, document and explore your software architecture. Leanpub.
2. Mermaid 그래프 표준: Sveidqvist, K., et al. (2014-2026). Mermaid: Markdown-inspired syntax for generating charts and diagrams (https://mermaid.js.org/).
3. 소프트웨어 시각화에서의 인지 부하 이론: Sweller, J. (2011). Cognitive Load Theory. Psychology of Learning and Motivation, Vol. 55.