フロント図

sequenceDiagram
    participant User as 自然文（ユーザ）
    participant Client as クライアント（LLMでNL→SQL）
    participant API as APIサーバ
    participant DB as Postgres/Chroma/Metabase

    User->>Client: 「過去3ヶ月の売上推移を見せて」
    Client->>Client: NL→SQL 生成（LLM）
    Client->>API: POST /nlq/plan { message: "SELECT ..." }
    API->>DB: スキーマ確認（存在/非空）+ LIMIT強制 + ガード
    API-->>Client: { candidate_sql, validated_sql, used/skipped }

    Client->>API: POST /nlq/execute { sql: validated_sql, mode, output_level }
    API->>DB: SQL実行 / マスキング / Metabaseリンク生成
    API-->>Client: { rows, stats.metabase, ... }

    Client->>API: POST /nlq/history（plan/executeを保存）
    API->>DB: nlq_history へ永続化

    Client->>API: POST /chroma/package（差分ドキュメント組立）
    API-->>Client: { ChromaPackage ... }（プレビュー or キュー投入）

    Client->>API: POST /chroma/upsert { dry_run? items? }
    API->>DB: portal_chroma_doc → Chroma upsert（idempotent）
    API-->>Client: { processed/succeeded/failed/items }

最新

sequenceDiagram
    autonumber
    participant U as User
    participant L as ChatPanel(Left)
    participant M as SqlAndResult(Middle)
    participant R as AnalysisPanel(Right)
    participant S as StepBar(Top)
    participant C as api.ts(client)
    participant A as NLQ API(8081)
    participant B as Metabase
    participant H as History
    participant X as Chroma

    U->>L: type message
    L->>C: POST /nlq/plan
    C->>A: /nlq/plan
    A-->>C: PlanResponse
    C-->>L: show candidate SQL
    C-->>M: preview SQL + hint

    U->>M: click Execute (mode, analyze_mode)
    M->>C: POST /nlq/execute
    C->>A: /nlq/execute

    alt 200 OK
        A-->>C: ExecuteResponse (rows, stats)
        C-->>S: stats.timeline update
        C-->>M: table(rows, columns, column_map)
        C-->>R: analysis
        alt metabase public
            M->>B: iframe src = stats.metabase.url
        else metabase signed
            M->>B: iframe src = stats.metabase.iframe_src
        end
        par save history (optional)
            C->>A: POST /nlq/history
            A-->>C: 202
        and chroma upsert (optional)
            C->>A: POST /chroma/package
            A-->>C: ChromaPackage(source_hash)
            C->>A: POST /chroma/upsert {items:[pkg]}
            A-->>C: UpsertResponse(ok, doc_id)
        end
    else 429 Rate Limited
        A-->>C: 429 + Retry-After
        C-->>S: mark rate_limited
        C-->>M: show countdown + retry/quick button
    else 400 Guard Error
        A-->>C: 400 {title, detail}
        C-->>S: guard note=error
        C-->>L: tip with reason
    else 500 Server Error
        A-->>C: 500
        C-->>M: snackbar + retry
    end

    U->>L: restore session
    L->>C: GET /nlq/history?session_id=...
    C->>A: /nlq/history
    A-->>C: items[], next_cursor
    C-->>L: rebuild chat list