docs/sequence_diagram.xml

<mxGraphModel dx="1422" dy="762" grid="1" gridSize="10" guides="1" tooltips="1" connect="1" arrows="1" fold="1" page="1" pageScale="1" pageWidth="1500" pageHeight="1700" math="0" shadow="0">
  <root>
    <mxCell id="0"/>
    <mxCell id="1" parent="0"/>

    <!-- =========================================================
         ACTOR HEADERS
         Column centers: User=95, Frontend=260, Backend=435,
         CodeAgent=610, Retriever=790, FAISS (HF Dataset)=965,
         LLM APIs=1145, AsyncWorkers=1330
    ========================================================= -->
    <mxCell id="2" value="User" style="rounded=1;fillColor=#f5f5f5;strokeColor=#666666;fontStyle=1;fontSize=11;" vertex="1" parent="1">
      <mxGeometry x="25" y="20" width="140" height="50" as="geometry"/>
    </mxCell>
    <mxCell id="3" value="React Frontend" style="rounded=1;fillColor=#DAE8FC;strokeColor=#6c8ebf;fontStyle=1;fontSize=11;" vertex="1" parent="1">
      <mxGeometry x="190" y="20" width="140" height="50" as="geometry"/>
    </mxCell>
    <mxCell id="4" value="FastAPI Backend" style="rounded=1;fillColor=#f5f5f5;strokeColor=#666666;fontStyle=1;fontSize=11;" vertex="1" parent="1">
      <mxGeometry x="360" y="20" width="150" height="50" as="geometry"/>
    </mxCell>
    <mxCell id="5" value="smolagents&#xa;CodeAgent" style="rounded=1;fillColor=#D5E8D4;strokeColor=#82b366;fontStyle=1;fontSize=11;" vertex="1" parent="1">
      <mxGeometry x="540" y="20" width="140" height="50" as="geometry"/>
    </mxCell>
    <mxCell id="6" value="Retriever + ML&#xa;(FAISS · CrossEncoder)" style="rounded=1;fillColor=#DAE8FC;strokeColor=#6c8ebf;fontStyle=1;fontSize=11;" vertex="1" parent="1">
      <mxGeometry x="720" y="20" width="140" height="50" as="geometry"/>
    </mxCell>
    <mxCell id="7" value="FAISS Index&#xa;(HF Dataset · in-memory)" style="rounded=1;fillColor=#FFD21E;strokeColor=#c9a800;fontStyle=1;fontSize=11;" vertex="1" parent="1">
      <mxGeometry x="895" y="20" width="140" height="50" as="geometry"/>
    </mxCell>
    <mxCell id="8" value="LLM APIs&#xa;(OpenAI / Azure / Gemini)" style="rounded=1;fillColor=#e6e6e6;strokeColor=#999999;fontStyle=1;fontSize=10;" vertex="1" parent="1">
      <mxGeometry x="1075" y="20" width="140" height="50" as="geometry"/>
    </mxCell>
    <mxCell id="9" value="TruLens / VizCodeAgent&#xa;(Async Workers)" style="rounded=1;fillColor=#ffe6cc;strokeColor=#d6b656;fontStyle=1;fontSize=10;" vertex="1" parent="1">
      <mxGeometry x="1255" y="20" width="155" height="50" as="geometry"/>
    </mxCell>

    <!-- =========================================================
         LIFELINES  (dashed vertical lines, standalone edges)
    ========================================================= -->
    <mxCell id="10" value="" style="endArrow=none;dashed=1;strokeColor=#666666;strokeWidth=1;" edge="1" parent="1">
      <mxGeometry relative="1" as="geometry">
        <mxPoint x="95" y="70" as="sourcePoint"/>
        <mxPoint x="95" y="1530" as="targetPoint"/>
      </mxGeometry>
    </mxCell>
    <mxCell id="11" value="" style="endArrow=none;dashed=1;strokeColor=#6c8ebf;strokeWidth=1;" edge="1" parent="1">
      <mxGeometry relative="1" as="geometry">
        <mxPoint x="260" y="70" as="sourcePoint"/>
        <mxPoint x="260" y="1530" as="targetPoint"/>
      </mxGeometry>
    </mxCell>
    <mxCell id="12" value="" style="endArrow=none;dashed=1;strokeColor=#666666;strokeWidth=1;" edge="1" parent="1">
      <mxGeometry relative="1" as="geometry">
        <mxPoint x="435" y="70" as="sourcePoint"/>
        <mxPoint x="435" y="1530" as="targetPoint"/>
      </mxGeometry>
    </mxCell>
    <mxCell id="13" value="" style="endArrow=none;dashed=1;strokeColor=#82b366;strokeWidth=1;" edge="1" parent="1">
      <mxGeometry relative="1" as="geometry">
        <mxPoint x="610" y="70" as="sourcePoint"/>
        <mxPoint x="610" y="1530" as="targetPoint"/>
      </mxGeometry>
    </mxCell>
    <mxCell id="14" value="" style="endArrow=none;dashed=1;strokeColor=#6c8ebf;strokeWidth=1;" edge="1" parent="1">
      <mxGeometry relative="1" as="geometry">
        <mxPoint x="790" y="70" as="sourcePoint"/>
        <mxPoint x="790" y="1530" as="targetPoint"/>
      </mxGeometry>
    </mxCell>
    <mxCell id="15" value="" style="endArrow=none;dashed=1;strokeColor=#c9a800;strokeWidth=1;" edge="1" parent="1">
      <mxGeometry relative="1" as="geometry">
        <mxPoint x="965" y="70" as="sourcePoint"/>
        <mxPoint x="965" y="1530" as="targetPoint"/>
      </mxGeometry>
    </mxCell>
    <mxCell id="16" value="" style="endArrow=none;dashed=1;strokeColor=#999999;strokeWidth=1;" edge="1" parent="1">
      <mxGeometry relative="1" as="geometry">
        <mxPoint x="1145" y="70" as="sourcePoint"/>
        <mxPoint x="1145" y="1530" as="targetPoint"/>
      </mxGeometry>
    </mxCell>
    <mxCell id="17" value="" style="endArrow=none;dashed=1;strokeColor=#d6b656;strokeWidth=1;" edge="1" parent="1">
      <mxGeometry relative="1" as="geometry">
        <mxPoint x="1332" y="70" as="sourcePoint"/>
        <mxPoint x="1332" y="1530" as="targetPoint"/>
      </mxGeometry>
    </mxCell>

    <!-- =========================================================
         SEQUENCE STEPS
         Step boxes: w=130, h=42 (w=145,h=42 for Backend)
         Column x offsets (centered on lifeline):
           User     x=30   (cx=95)
           Frontend x=195  (cx=260)
           Backend  x=358  (cx=435)
           Agent    x=545  (cx=610)
           Retriever x=725 (cx=790)
           FAISS    x=900  (cx=965)
           LLM      x=1080 (cx=1145)
           Async    x=1257 (cx=1332)
    ========================================================= -->

    <!-- Step 1 — User submits query -->
    <mxCell id="100" value="1. Submit query&#xa;(include_viz?)" style="rounded=1;fillColor=#f5f5f5;strokeColor=#666666;fontSize=10;" vertex="1" parent="1">
      <mxGeometry x="30" y="100" width="130" height="42" as="geometry"/>
    </mxCell>

    <!-- Step 2 — Frontend adds JWT (same row, message goes right) -->
    <mxCell id="101" value="2. Add JWT · POST /api/v1/query" style="rounded=1;fillColor=#DAE8FC;strokeColor=#6c8ebf;fontSize=10;" vertex="1" parent="1">
      <mxGeometry x="195" y="100" width="130" height="42" as="geometry"/>
    </mxCell>
    <!-- Arrow 1: User → Frontend -->
    <mxCell id="200" value="HTTPS query" style="edgeStyle=orthogonalEdgeStyle;rounded=1;orthogonalLoop=1;jettySize=auto;exitX=1;exitY=0.5;entryX=0;entryY=0.5;" edge="1" source="100" target="101" parent="1">
      <mxGeometry relative="1" as="geometry"/>
    </mxCell>

    <!-- Step 3 — Backend authenticates -->
    <mxCell id="102" value="3. Validate JWT&#xa;create query_id" style="rounded=1;fillColor=#f5f5f5;strokeColor=#666666;fontSize=10;" vertex="1" parent="1">
      <mxGeometry x="358" y="175" width="145" height="42" as="geometry"/>
    </mxCell>
    <!-- Arrow 2: Frontend → Backend -->
    <mxCell id="201" value="JWT + query body" style="edgeStyle=orthogonalEdgeStyle;rounded=1;orthogonalLoop=1;jettySize=auto;exitX=1;exitY=0.5;entryX=0;entryY=0.5;" edge="1" source="101" target="102" parent="1">
      <mxGeometry relative="1" as="geometry"/>
    </mxCell>

    <!-- Step 4 — CodeAgent starts -->
    <mxCell id="103" value="4. CodeAgent starts&#xa;max_steps=5" style="rounded=1;fillColor=#D5E8D4;strokeColor=#82b366;fontSize=10;" vertex="1" parent="1">
      <mxGeometry x="545" y="250" width="130" height="42" as="geometry"/>
    </mxCell>
    <!-- Arrow 3: Backend → CodeAgent via run_in_executor -->
    <mxCell id="202" value="run_in_executor" style="edgeStyle=orthogonalEdgeStyle;rounded=1;orthogonalLoop=1;jettySize=auto;exitX=1;exitY=0.5;entryX=0;entryY=0.5;" edge="1" source="102" target="103" parent="1">
      <mxGeometry relative="1" as="geometry"/>
    </mxCell>

    <!-- Step 5 — Retriever Stage 1: embed -->
    <mxCell id="104" value="5. Stage 1: embed&#xa;query → 384-dim" style="rounded=1;fillColor=#DAE8FC;strokeColor=#6c8ebf;fontSize=10;" vertex="1" parent="1">
      <mxGeometry x="725" y="325" width="130" height="42" as="geometry"/>
    </mxCell>
    <!-- Arrow 4: CodeAgent → Retriever tool call -->
    <mxCell id="203" value="tool call (query string)" style="edgeStyle=orthogonalEdgeStyle;rounded=1;orthogonalLoop=1;jettySize=auto;exitX=1;exitY=0.5;entryX=0;entryY=0.5;" edge="1" source="103" target="104" parent="1">
      <mxGeometry relative="1" as="geometry"/>
    </mxCell>

    <!-- Step 6 — FAISS cosine search -->
    <mxCell id="105" value="6. FAISS cosine search&#xa;Top 20 candidates (in-memory)" style="rounded=1;fillColor=#FFD21E;strokeColor=#c9a800;fontSize=10;" vertex="1" parent="1">
      <mxGeometry x="900" y="400" width="130" height="42" as="geometry"/>
    </mxCell>
    <!-- Arrow 5: Retriever → FAISS -->
    <mxCell id="204" value="cosine search · Top 20" style="edgeStyle=orthogonalEdgeStyle;rounded=1;orthogonalLoop=1;jettySize=auto;exitX=1;exitY=0.5;entryX=0;entryY=0.5;" edge="1" source="104" target="105" parent="1">
      <mxGeometry relative="1" as="geometry"/>
    </mxCell>

    <!-- Step 7 — CrossEncoder rerank (back on Retriever lifeline) -->
    <mxCell id="106" value="7. CrossEncoder rerank&#xa;Top 20 → Top 5 (&lt;500 ms)" style="rounded=1;fillColor=#DAE8FC;strokeColor=#6c8ebf;fontSize=10;" vertex="1" parent="1">
      <mxGeometry x="725" y="476" width="130" height="42" as="geometry"/>
    </mxCell>
    <!-- Arrow 6: FAISS → Retriever return -->
    <mxCell id="205" value="Top 20 chunks" style="edgeStyle=orthogonalEdgeStyle;rounded=1;orthogonalLoop=1;jettySize=auto;exitX=0;exitY=0.5;entryX=1;entryY=0.5;" edge="1" source="105" target="106" parent="1">
      <mxGeometry relative="1" as="geometry"/>
    </mxCell>

    <!-- Step 8 — CodeAgent receives context, calls LLM -->
    <mxCell id="107" value="8. Context ready&#xa;→ reason + call LLM" style="rounded=1;fillColor=#D5E8D4;strokeColor=#82b366;fontSize=10;" vertex="1" parent="1">
      <mxGeometry x="545" y="552" width="130" height="42" as="geometry"/>
    </mxCell>
    <!-- Arrow 7: Retriever → CodeAgent (Top 5 formatted) -->
    <mxCell id="206" value="Top 5 (title · url · citation)" style="edgeStyle=orthogonalEdgeStyle;rounded=1;orthogonalLoop=1;jettySize=auto;exitX=0;exitY=0.5;entryX=1;entryY=0.5;" edge="1" source="106" target="107" parent="1">
      <mxGeometry relative="1" as="geometry"/>
    </mxCell>

    <!-- Step 9 — LLM generates answer -->
    <mxCell id="108" value="9. Generate answer&#xa;+ source citations" style="rounded=1;fillColor=#e6e6e6;strokeColor=#999999;fontSize=10;" vertex="1" parent="1">
      <mxGeometry x="1080" y="628" width="130" height="42" as="geometry"/>
    </mxCell>
    <!-- Arrow 8: CodeAgent → LLM API -->
    <mxCell id="207" value="context + question (reasoning)" style="edgeStyle=orthogonalEdgeStyle;rounded=1;orthogonalLoop=1;jettySize=auto;exitX=1;exitY=0.5;entryX=0;entryY=0.5;" edge="1" source="107" target="108" parent="1">
      <mxGeometry relative="1" as="geometry"/>
    </mxCell>

    <!-- Step 10 — CodeAgent returns JSON (back on CodeAgent lifeline) -->
    <mxCell id="109" value="10. Return JSON&#xa;{answer, sources}" style="rounded=1;fillColor=#D5E8D4;strokeColor=#82b366;fontSize=10;" vertex="1" parent="1">
      <mxGeometry x="545" y="704" width="130" height="42" as="geometry"/>
    </mxCell>
    <!-- Arrow 9: LLM → CodeAgent answer -->
    <mxCell id="208" value="answer + citations" style="edgeStyle=orthogonalEdgeStyle;rounded=1;orthogonalLoop=1;jettySize=auto;exitX=0;exitY=0.5;entryX=1;entryY=0.5;" edge="1" source="108" target="109" parent="1">
      <mxGeometry relative="1" as="geometry"/>
    </mxCell>

    <!-- Step 11 — Backend fires async tasks, returns immediately -->
    <mxCell id="110" value="11. Fire async tasks&#xa;return immediately" style="rounded=1;fillColor=#f5f5f5;strokeColor=#666666;fontSize=10;" vertex="1" parent="1">
      <mxGeometry x="358" y="780" width="145" height="42" as="geometry"/>
    </mxCell>
    <!-- Arrow 10: CodeAgent → Backend JSON -->
    <mxCell id="209" value="JSON response" style="edgeStyle=orthogonalEdgeStyle;rounded=1;orthogonalLoop=1;jettySize=auto;exitX=0;exitY=0.5;entryX=1;entryY=0.5;" edge="1" source="109" target="110" parent="1">
      <mxGeometry relative="1" as="geometry"/>
    </mxCell>

    <!-- Async arrows (dashed, to Async Workers column) -->
    <!-- Arrow 11a: Backend → TruLens eval -->
    <mxCell id="210" value="async TruLens eval" style="edgeStyle=orthogonalEdgeStyle;rounded=1;orthogonalLoop=1;jettySize=auto;dashed=1;endArrow=open;endFill=0;exitX=1;exitY=0.3;entryX=0;entryY=0.3;" edge="1" source="110" target="111" parent="1">
      <mxGeometry relative="1" as="geometry"/>
    </mxCell>
    <!-- Arrow 11b: Backend → VizCodeAgent -->
    <mxCell id="211" value="async VizCodeAgent" style="edgeStyle=orthogonalEdgeStyle;rounded=1;orthogonalLoop=1;jettySize=auto;dashed=1;endArrow=open;endFill=0;exitX=1;exitY=0.7;entryX=0;entryY=0.7;" edge="1" source="110" target="111" parent="1">
      <mxGeometry relative="1" as="geometry"/>
    </mxCell>

    <!-- Async worker box -->
    <mxCell id="111" value="TruLens: RAG Triad eval&#xa;VizCodeAgent: Plotly spec&#xa;→ VIZ_CACHE (1 h TTL)" style="rounded=1;fillColor=#ffe6cc;strokeColor=#d6b656;fontSize=10;" vertex="1" parent="1">
      <mxGeometry x="1257" y="780" width="155" height="60" as="geometry"/>
    </mxCell>

    <!-- VizCodeAgent → LLM API for spec -->
    <mxCell id="212" value="generate Plotly spec" style="edgeStyle=orthogonalEdgeStyle;rounded=1;orthogonalLoop=1;jettySize=auto;dashed=1;" edge="1" source="111" target="112" parent="1">
      <mxGeometry relative="1" as="geometry"/>
    </mxCell>
    <mxCell id="112" value="Plotly JSON spec" style="rounded=1;fillColor=#e6e6e6;strokeColor=#999999;fontSize=10;" vertex="1" parent="1">
      <mxGeometry x="1080" y="860" width="130" height="42" as="geometry"/>
    </mxCell>

    <!-- TruLens → LLM for judge -->
    <mxCell id="213" value="LLM-as-judge&#xa;(RAG Triad)" style="edgeStyle=orthogonalEdgeStyle;rounded=1;orthogonalLoop=1;jettySize=auto;dashed=1;" edge="1" source="111" target="113" parent="1">
      <mxGeometry relative="1" as="geometry"/>
    </mxCell>
    <mxCell id="113" value="RAG Triad scores&#xa;→ evaluation_results" style="rounded=1;fillColor=#e6e6e6;strokeColor=#999999;fontSize=10;" vertex="1" parent="1">
      <mxGeometry x="1080" y="780" width="130" height="42" as="geometry"/>
    </mxCell>

    <!-- Step 12 — Frontend renders answer -->
    <mxCell id="114" value="12. Render answer&#xa;+ citations" style="rounded=1;fillColor=#DAE8FC;strokeColor=#6c8ebf;fontSize=10;" vertex="1" parent="1">
      <mxGeometry x="195" y="856" width="130" height="42" as="geometry"/>
    </mxCell>
    <!-- Arrow 12: Backend → Frontend (QueryResponse) -->
    <mxCell id="214" value="QueryResponse (immediate)" style="edgeStyle=orthogonalEdgeStyle;rounded=1;orthogonalLoop=1;jettySize=auto;exitX=0;exitY=0.5;entryX=1;entryY=0.5;strokeColor=#0000FF;" edge="1" source="110" target="114" parent="1">
      <mxGeometry relative="1" as="geometry"/>
    </mxCell>

    <!-- Step 13 — User sees answer -->
    <mxCell id="115" value="13. View answer&#xa;+ citations" style="rounded=1;fillColor=#f5f5f5;strokeColor=#666666;fontSize=10;" vertex="1" parent="1">
      <mxGeometry x="30" y="856" width="130" height="42" as="geometry"/>
    </mxCell>
    <!-- Arrow 13: Frontend → User -->
    <mxCell id="215" value="display answer" style="edgeStyle=orthogonalEdgeStyle;rounded=1;orthogonalLoop=1;jettySize=auto;exitX=0;exitY=0.5;entryX=1;entryY=0.5;" edge="1" source="114" target="115" parent="1">
      <mxGeometry relative="1" as="geometry"/>
    </mxCell>

    <!-- =========================================================
         POLLING SECTION DIVIDER
    ========================================================= -->
    <mxCell id="300" value="— — — — — — — — — — Polling Loop: Frontend polls GET /query/{id}/visualization every 2 s (max 60 s) — — — — — — — — — —" style="text;html=1;align=center;verticalAlign=middle;resizable=0;strokeColor=none;fillColor=none;fontStyle=2;fontSize=11;fontColor=#666666;" vertex="1" parent="1">
      <mxGeometry x="20" y="935" width="1400" height="30" as="geometry"/>
    </mxCell>

    <!-- Step 14 — Frontend polls -->
    <mxCell id="116" value="14. Poll for&#xa;visualization" style="rounded=1;fillColor=#DAE8FC;strokeColor=#6c8ebf;fontSize=10;" vertex="1" parent="1">
      <mxGeometry x="195" y="980" width="130" height="42" as="geometry"/>
    </mxCell>

    <!-- Step 15 — Backend checks VIZ_CACHE -->
    <mxCell id="117" value="15. Check VIZ_CACHE&#xa;(returns when ready)" style="rounded=1;fillColor=#f5f5f5;strokeColor=#666666;fontSize=10;" vertex="1" parent="1">
      <mxGeometry x="358" y="980" width="145" height="42" as="geometry"/>
    </mxCell>
    <!-- Arrow 14: Frontend → Backend poll -->
    <mxCell id="216" value="GET /query/{id}/visualization" style="edgeStyle=orthogonalEdgeStyle;rounded=1;orthogonalLoop=1;jettySize=auto;exitX=1;exitY=0.5;entryX=0;entryY=0.5;" edge="1" source="116" target="117" parent="1">
      <mxGeometry relative="1" as="geometry"/>
    </mxCell>

    <!-- Step 16 — Frontend renders VizPanel -->
    <mxCell id="118" value="16. VizPanel renders&#xa;Plotly chart" style="rounded=1;fillColor=#DAE8FC;strokeColor=#6c8ebf;fontSize=10;" vertex="1" parent="1">
      <mxGeometry x="195" y="1056" width="130" height="42" as="geometry"/>
    </mxCell>
    <!-- Arrow 15: Backend → Frontend chart_data -->
    <mxCell id="217" value="chart_data (Plotly spec)" style="edgeStyle=orthogonalEdgeStyle;rounded=1;orthogonalLoop=1;jettySize=auto;exitX=0;exitY=0.5;entryX=1;entryY=0.5;" edge="1" source="117" target="118" parent="1">
      <mxGeometry relative="1" as="geometry"/>
    </mxCell>

    <!-- Step 17 — User sees chart -->
    <mxCell id="119" value="17. View interactive&#xa;Plotly chart" style="rounded=1;fillColor=#f5f5f5;strokeColor=#666666;fontSize=10;" vertex="1" parent="1">
      <mxGeometry x="30" y="1056" width="130" height="42" as="geometry"/>
    </mxCell>
    <!-- Arrow 16: Frontend → User (chart) -->
    <mxCell id="218" value="interactive visualization" style="edgeStyle=orthogonalEdgeStyle;rounded=1;orthogonalLoop=1;jettySize=auto;exitX=0;exitY=0.5;entryX=1;entryY=0.5;" edge="1" source="118" target="119" parent="1">
      <mxGeometry relative="1" as="geometry"/>
    </mxCell>

    <!-- =========================================================
         PERFORMANCE SLA BANNER
    ========================================================= -->
    <mxCell id="400" value="SLA Targets: Full pipeline &lt; 6 s  ·  LLM generation &lt; 3 s  ·  CrossEncoder &lt; 500 ms  ·  Vector query &lt; 50 ms  ·  Context Relevance &gt; 0.85  ·  Groundedness &gt; 0.9" style="text;html=1;align=center;verticalAlign=middle;strokeColor=#666666;fillColor=#fff2cc;fontStyle=0;fontSize=10;rounded=1;" vertex="1" parent="1">
      <mxGeometry x="20" y="1140" width="1420" height="35" as="geometry"/>
    </mxCell>

  </root>
</mxGraphModel>