Skip to content

LCORE-460: sequence diagram for query endpoint #791

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
tisnik merged 1 commit into from
Nov 13, 2025
Merged

LCORE-460: sequence diagram for query endpoint #791

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 11 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Comment on lines +37 to +39
Copy link
Contributor

@coderabbitai coderabbitai bot Nov 13, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Fix list indentation for System prompt subsections (markdownlint MD007).

The three new subsections under "System prompt" use inconsistent indentation. Based on markdownlint feedback, these should use 4-space indentation instead of 8 spaces to align with the expected nested list structure.

     * [System prompt](#system-prompt)
-        * [System Prompt Path](#system-prompt-path)
-        * [System Prompt Literal](#system-prompt-literal)
-        * [Custom Profile](#custom-profile)
+    * [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)
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
* [System Prompt Path](#system-prompt-path)
* [System Prompt Literal](#system-prompt-literal)
* [Custom Profile](#custom-profile)
* [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)
🧰 Tools
🪛 markdownlint-cli2 (0.18.1)

37-37: Unordered list indentation
Expected: 4; Actual: 8

(MD007, ul-indent)

38-38: Unordered list indentation
Expected: 4; Actual: 8

(MD007, ul-indent)

39-39: Unordered list indentation
Expected: 4; Actual: 8

(MD007, ul-indent)

🤖 Prompt for AI Agents 
In README.md around lines 37 to 39, the three subsections under the "System
prompt" list are indented with 8 spaces which violates markdownlint MD007;
change their indentation to 4 spaces so they nest correctly under the parent
list item (i.e., reduce each subsection's leading spaces from 8 to 4) to produce
a proper nested markdown list.

* [Control model/provider overrides via authorization](#control-modelprovider-overrides-via-authorization)
* [Safety Shields](#safety-shields)
* [Authentication](#authentication)
Expand Down Expand Up @@ -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 -->

Expand Down Expand Up @@ -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)
43 changes: 43 additions & 0 deletions docs/query_endpoint.puml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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

Comment on lines +1 to +8
Copy link
Contributor

@coderabbitai coderabbitai bot Nov 13, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🔴 Critical

Declare the DB participant or remove the interaction.

Lines 14-15 reference a "DB" participant that is never declared at the top of the diagram. PlantUML participant declarations at lines 3-7 do not include DB.

Either declare DB as a participant:

 @startuml

 participant Client
 participant Endpoint as "Query Endpoint handler"
 participant Auth
 participant LlamaStack as "Llama Stack Client"
 participant Cache as Cache
+participant DB as "Database"

 Client->>Endpoint: POST /query + attachments

Or, if the database interaction should remain implicit and not shown in the diagram, remove lines 14-15.

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
@startuml
participant Client
participant Endpoint as "Query Endpoint handler"
participant Auth
participant LlamaStack as "Llama Stack Client"
participant Cache as Cache
@startuml
participant Client
participant Endpoint as "Query Endpoint handler"
participant Auth
participant LlamaStack as "Llama Stack Client"
participant Cache as Cache
participant DB as "Database"
🤖 Prompt for AI Agents 
In docs/query_endpoint.puml around lines 1 to 8 (the participant declarations)
the diagram later references a "DB" participant (lines ~14-15) that isn't
declared; either add a DB participant declaration at the top (matching the label
used later, e.g., participant DB or participant "DB" as <alias>) so the later
interactions resolve, or remove the two lines that reference the DB if you
intend the database interaction to be implicit and not shown; ensure the chosen
fix keeps participant naming consistent with the later interaction.

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
Loading
Loading