# sap-samples/btp-cap-genai-semantic-search architecture

> Architecture diagram of the GitHub repository sap-samples/btp-cap-genai-semantic-search, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sap-samples/btp-cap-genai-semantic-search
- Repository: https://github.com/sap-samples/btp-cap-genai-semantic-search

## Overview

This is a SAP BTP CAP semantic-search sample. A user submits a query in the SAPUI5 interface; the request is routed to the CAP search service, which may reformulate the text, derive metadata filters, generate an embedding, and query HANA for similar documents. The service also supports embedding and storing documents. The README documents Generative AI Hub and HANA Vector Engine; backend behavior is based on the sampled service excerpt, while routing and service definitions are represented only where the tree supports exact paths.

Main entry points: [`api/srv/sample.ts`](https://github.com/sap-samples/btp-cap-genai-semantic-search/blob/main/api/srv/sample.ts) (Sample service), [`router/xs-app.json`](https://github.com/sap-samples/btp-cap-genai-semantic-search/blob/main/router/xs-app.json) (Application router), [`api/srv/sample.cds`](https://github.com/sap-samples/btp-cap-genai-semantic-search/blob/main/api/srv/sample.cds) (CAP service endpoint), [`ui/webapp/controller/Main.controller.ts`](https://github.com/sap-samples/btp-cap-genai-semantic-search/blob/main/ui/webapp/controller/Main.controller.ts) (Search controller)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Search interface"]
  node_search_ui["Search controller<br/>[Main.controller.ts]"]
  node_search_view["Search view<br/>[Main.view.xml]"]
end

subgraph group_routing["Request routing"]
  node_router["Application router<br/>[xs-app.json]"]
end

subgraph group_backend["Search service"]
  node_cap_endpoint["CAP service endpoint<br/>[sample.cds]"]
  node_sample_service["Sample service<br/>[sample.ts]"]
  node_query_reformulation["Query reformulation<br/>[sample.ts]"]
  node_metadata_filter["Metadata filtering<br/>[sample.ts]"]
  node_embedding["Embedding generation<br/>[sample.ts]"]
  node_document_ingestion["Document ingestion<br/>[sample.ts]"]
end

subgraph group_integrations["AI and persistence"]
  node_orchestration["LLM orchestration"]
  node_embedding_service["Embedding provider"]
  node_hana[("HANA document store<br/>[schema.cds]")]
end

node_searcher(("Search user"))

node_searcher -->|"enters query"| node_search_view
node_search_view -->|"triggers search"| node_search_ui
node_search_ui -->|"POSTs search"| node_router
node_router -->|"forwards request"| node_cap_endpoint
node_cap_endpoint -->|"dispatches search"| node_sample_service
node_sample_service -->|"reformulates text"| node_query_reformulation
node_query_reformulation -->|"requests completion"| node_orchestration
node_sample_service -->|"extracts filters"| node_metadata_filter
node_metadata_filter -->|"requests completion"| node_orchestration
node_sample_service -->|"embeds query"| node_embedding
node_embedding -->|"requests vector"| node_embedding_service
node_sample_service -->|"runs similarity query"| node_hana
node_hana -->|"returns matches"| node_sample_service
node_sample_service -->|"returns documents"| node_cap_endpoint
node_cap_endpoint -->|"returns response"| node_router
node_router -->|"delivers results"| node_search_ui
node_sample_service -->|"dispatches embedding"| node_document_ingestion
node_document_ingestion -->|"requests vector"| node_embedding_service
node_document_ingestion -->|"stores document vector"| node_hana

click node_search_ui "https://github.com/sap-samples/btp-cap-genai-semantic-search/blob/main/ui/webapp/controller/Main.controller.ts"
click node_search_view "https://github.com/sap-samples/btp-cap-genai-semantic-search/blob/main/ui/webapp/view/Main.view.xml"
click node_router "https://github.com/sap-samples/btp-cap-genai-semantic-search/blob/main/router/xs-app.json"
click node_cap_endpoint "https://github.com/sap-samples/btp-cap-genai-semantic-search/blob/main/api/srv/sample.cds"
click node_sample_service "https://github.com/sap-samples/btp-cap-genai-semantic-search/blob/main/api/srv/sample.ts"
click node_query_reformulation "https://github.com/sap-samples/btp-cap-genai-semantic-search/blob/main/api/srv/sample.ts"
click node_metadata_filter "https://github.com/sap-samples/btp-cap-genai-semantic-search/blob/main/api/srv/sample.ts"
click node_embedding "https://github.com/sap-samples/btp-cap-genai-semantic-search/blob/main/api/srv/sample.ts"
click node_document_ingestion "https://github.com/sap-samples/btp-cap-genai-semantic-search/blob/main/api/srv/sample.ts"
click node_hana "https://github.com/sap-samples/btp-cap-genai-semantic-search/blob/main/api/db/schema.cds"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_search_ui,node_search_view,node_searcher toneBlue
class node_router toneAmber
class node_cap_endpoint,node_sample_service,node_query_reformulation,node_metadata_filter,node_embedding,node_document_ingestion toneMint
class node_orchestration,node_embedding_service,node_hana toneRose
```

## Components

### Search interface

- [Search controller](https://github.com/sap-samples/btp-cap-genai-semantic-search/blob/main/ui/webapp/controller/Main.controller.ts): `ui/webapp/controller/Main.controller.ts`
- [Search view](https://github.com/sap-samples/btp-cap-genai-semantic-search/blob/main/ui/webapp/view/Main.view.xml): `ui/webapp/view/Main.view.xml`

### Request routing

- [Application router](https://github.com/sap-samples/btp-cap-genai-semantic-search/blob/main/router/xs-app.json): `router/xs-app.json`

### Search service

- [CAP service endpoint](https://github.com/sap-samples/btp-cap-genai-semantic-search/blob/main/api/srv/sample.cds): `api/srv/sample.cds`
- [Sample service](https://github.com/sap-samples/btp-cap-genai-semantic-search/blob/main/api/srv/sample.ts): `api/srv/sample.ts`
- [Query reformulation](https://github.com/sap-samples/btp-cap-genai-semantic-search/blob/main/api/srv/sample.ts): `api/srv/sample.ts`
- [Metadata filtering](https://github.com/sap-samples/btp-cap-genai-semantic-search/blob/main/api/srv/sample.ts): `api/srv/sample.ts`
- [Embedding generation](https://github.com/sap-samples/btp-cap-genai-semantic-search/blob/main/api/srv/sample.ts): `api/srv/sample.ts`
- [Document ingestion](https://github.com/sap-samples/btp-cap-genai-semantic-search/blob/main/api/srv/sample.ts): `api/srv/sample.ts`

### AI and persistence

- **LLM orchestration**
- **Embedding provider**
- [HANA document store](https://github.com/sap-samples/btp-cap-genai-semantic-search/blob/main/api/db/schema.cds): `api/db/schema.cds`

### Other components

- **Search user**

## Connections

- Search user → Search view: enters query
- Search view → Search controller: triggers search
- Search controller → Application router: POSTs search
- Application router → CAP service endpoint: forwards request
- CAP service endpoint → Sample service: dispatches search
- Sample service → Query reformulation: reformulates text
- Query reformulation → LLM orchestration: requests completion
- Sample service → Metadata filtering: extracts filters
- Metadata filtering → LLM orchestration: requests completion
- Sample service → Embedding generation: embeds query
- Embedding generation → Embedding provider: requests vector
- Sample service → HANA document store: runs similarity query
- HANA document store → Sample service: returns matches
- Sample service → CAP service endpoint: returns documents
- CAP service endpoint → Application router: returns response
- Application router → Search controller: delivers results
- Sample service → Document ingestion: dispatches embedding
- Document ingestion → Embedding provider: requests vector
- Document ingestion → HANA document store: stores document vector