lidorshimoni/visualize

Visualize: アーキテクチャ & フロー可視化パターン

意図

テキストベースのアーキテクチャ、複雑なアルゴリズム、マルチエージェントの相互作用、データモデルを、標準的なMermaid構文を使用して曖昧さのない視覚的ダイアグラムに変換します。

理論的基盤

認知的負荷理論とソフトウェアアーキテクチャのC4モデル（Brown, 2018）に基づいています。視覚モデルは抽象的なシステム記述を具体化し、境界、データフロー、状態遷移を人間とエージェントの両方が即座に検証できるようにします。

標準ダイアグラム原型

1. コンポーネント & 境界アーキテクチャ図（C4 コンテナ / コンポーネント）

アーキテクチャの階層を表すには、flowchart TD または flowchart LR とサブグラフを使用します。

flowchart TD
    subgraph Client["Client Layer"]
        Web["Web Application (React)"]
        CLI["CLI Tool (Python)"]
    end

    subgraph Gateway["API Gateway"]
        Proxy["Reverse Proxy / Nginx"]
        Auth["Auth Service (JWT)"]
    end

    subgraph Core["Core Services"]
        App["Application Engine"]
        Worker["Async Background Worker"]
    end

    subgraph Data["Persistence Layer"]
        DB[("PostgreSQL")]
        Queue[("Redis Queue")]
    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 Coding Agent
    participant Tool as Tool Runner
    participant Git as Version Control

    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
    [*] --> Draft
    Draft --> InReview: レビュー提出
    InReview --> Approved: 検証合格
    InReview --> NeedsChanges: ブロッカー発見
    NeedsChanges --> InReview: 修正を再提出
    Approved --> InProgress: 実装開始
    InProgress --> Completed: 全テスト合格
    Completed --> [*]

4. データモデル & 関係図（ER図）

リレーショナルスキーマやドメインモデルには erDiagram を使用します。

erDiagram
    PROJECT ||--o{ SPECIFICATION : contains
    SPECIFICATION ||--o{ TICKET : decomposes_into
    TICKET ||--o{ COMMIT : implemented_by
    TICKET {
        string id PK
        string title
        string status
        string blocked_by
    }

Mermaid構文の安全規則

1. 特殊文字を含むノードラベルは必ず引用符で囲む:
   • id["Label (Extra Info)"] と記述し、id[Label (Extra Info)] とはしない。
2. サポートされる図のタイプのみを使用:
   • フローチャート (flowchart TD)、シーケンス図 (sequenceDiagram)、状態図 (stateDiagram-v2)、クラス図 (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.