Merge pull request lightspeed-core#791 from tisnik/lcore-460-sequence-diagram-for-query-endpoint

LCORE-460: sequence diagram for query endpoint

Author: tisnik

README.md

@@ -34,6 +34,9 @@ The service includes comprehensive user data collection capabilities for various
     * [Llama Stack version check](#llama-stack-version-check)
     * [User data collection](#user-data-collection)
     * [System prompt](#system-prompt)
+        * [System Prompt Path](#system-prompt-path)
+        * [System Prompt Literal](#system-prompt-literal)
+        * [Custom Profile](#custom-profile)
         * [Control model/provider overrides via authorization](#control-modelprovider-overrides-via-authorization)
     * [Safety Shields](#safety-shields)
     * [Authentication](#authentication)
@@ -75,6 +78,8 @@ The service includes comprehensive user data collection capabilities for various
 * [Project structure](#project-structure)
     * [Configuration classes](#configuration-classes)
     * [REST API](#rest-api)
+    * [Sequence diagrams](#sequence-diagrams)
+        * [Query endpoint REST API handler](#query-endpoint-rest-api-handler)
 
 <!-- vim-markdown-toc -->
 
@@ -889,3 +894,9 @@ For complete integration setup, deployment options, and configuration details, s
 ## REST API
 
 ![REST API](docs/rest_api.png)
+
+## Sequence diagrams
+
+### Query endpoint REST API handler
+
+![Query endpoint](docs/query_endpoint.svg)

docs/query_endpoint.puml

@@ -0,0 +1,43 @@
+@startuml
+
+participant Client
+participant Endpoint as "Query Endpoint handler"
+participant Auth
+participant LlamaStack as "Llama Stack Client"
+participant Cache as Cache
+
+Client->>Endpoint: POST /query + attachments
+Endpoint->>Auth: Validate auth & permissions
+Auth-->>Endpoint: Authorized ✓
+Endpoint->>Auth: Check config & token quota
+Auth-->>Endpoint: Config valid, tokens available
+Endpoint->>DB: Retrieve user conversation (optional)
+DB-->>Endpoint: UserConversation or None
+Endpoint->>Endpoint: Select model/provider from hints/config
+Endpoint->>LlamaStack: Get model capabilities
+LlamaStack-->>Endpoint: Capabilities response
+Endpoint->>Endpoint: Build system prompt, toolgroups, MCP headers
+Endpoint->>LlamaStack: Create turn (agent interaction)
+LlamaStack-->>Endpoint: Turn response + tool calls + RAG chunks
+Endpoint->>Endpoint: Parse metadata & referenced documents
+Endpoint->>Endpoint: Transform to QueryResponse
+Endpoint->>DB: Persist conversation metadata (model, topic, count)
+Endpoint->>Cache: Store conversation with timing metadata
+Endpoint-->>Client: Return QueryResponse + token metrics
+
+alt Connection Error
+    LlamaStack-->>Endpoint: APIConnectionError
+    Endpoint-->>Client: HTTP 500
+end
+
+alt Quota Exceeded
+    Auth-->>Endpoint: Rate limit violation
+    Endpoint-->>Client: HTTP 429
+end
+
+alt Invalid Request
+    Endpoint-->>Client: Missing/invalid conversation or attachments
+    Endpoint-->>Client: HTTP 400/403/404
+end
+
+@enduml