# vitrivr/vitrivr-ng architecture

> Architecture diagram of the GitHub repository vitrivr/vitrivr-ng, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/vitrivr/vitrivr-ng
- Repository: https://github.com/vitrivr/vitrivr-ng

## Overview

Vitrivr NG is an Angular interface for browsing and retrieving items from mixed-media collections through Cineast, with optional DRES competition support. Users build multimodal or staged temporal queries, submit them, and inspect returned objects and segments in gallery, list, or temporal views; query history and item details support follow-up exploration. The map also includes configuration/connectivity and competition capabilities documented in the README. Query submission, WebSocket message handling, and history updates are supported by sampled source; other branches are based on the repository tree and README, so their internal wiring is not asserted.

Main entry points: [`src/app/core/queries/query.service.ts`](https://github.com/vitrivr/vitrivr-ng/blob/master/src/app/core/queries/query.service.ts) (Query service), [`src/app/query/query-sidebar.component.ts`](https://github.com/vitrivr/vitrivr-ng/blob/master/src/app/query/query-sidebar.component.ts) (Query sidebar), [`src/app/results`](https://github.com/vitrivr/vitrivr-ng/tree/master/src/app/results) (Result views), [`src/app/app.component.ts`](https://github.com/vitrivr/vitrivr-ng/blob/master/src/app/app.component.ts) (App shell)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_query["Query authoring"]
  node_query_sidebar["Query sidebar"]
  node_query_terms["Query terms"]
  node_temporal["Temporal stages"]
  node_query_models["Query models"]
end

subgraph group_retrieval["Retrieval and results"]
  node_query_service["Query service<br/>[query.service.ts]"]
  node_results["Result views"]
  node_result_state["Scored results"]
  node_history["Query history<br/>[history.service.ts]"]
  node_details["Media details"]
  node_segment_details["Segment details"]
  node_selection["Selection and tags"]
end

subgraph group_app["Application services"]
  node_app_shell["App shell<br/>[app.component.ts]"]
  node_websocket["WebSocket factory"]
  node_cineast_bindings["Cineast API bindings"]
  node_lookup["Distinct lookup"]
  node_config["Configuration<br/>[config.model.ts]"]
end

subgraph group_competition["Competition"]
  node_competition_ui["Competition UI"]
  node_competition_services["Competition services"]
  node_dres_service["DRES service<br/>[dres.service.ts]"]
  node_dres_bindings["DRES API bindings"]
end

node_user(("User"))
node_cineast{{"Cineast"}}
node_dres{{"DRES"}}

node_user -->|"configures query"| node_query_sidebar
node_query_sidebar -->|"edits terms"| node_query_terms
node_query_sidebar -->|"sets stage spacing"| node_temporal
node_query_sidebar -->|"submits query"| node_query_service
node_query_service -->|"builds messages"| node_query_models
node_query_service -->|"sends query"| node_websocket
node_websocket -->|"exchanges messages"| node_cineast
node_cineast -->|"streams results"| node_websocket
node_query_service -->|"processes results"| node_result_state
node_query_service -->|"appends results"| node_history
node_result_state -->|"supplies results"| node_results
node_user -->|"browses results"| node_results
node_results -->|"opens object"| node_details
node_results -->|"opens segment"| node_segment_details
node_user -->|"manages selections"| node_selection
node_query_terms -.->|"looks up tags"| node_cineast_bindings
node_cineast_bindings -.->|"calls REST API"| node_cineast
node_app_shell -->|"observes status"| node_query_service
node_app_shell -->|"initializes lookup"| node_lookup
node_app_shell -->|"reads settings"| node_config
node_competition_ui -.->|"uses competition tools"| node_competition_services
node_competition_services -.->|"records and submits"| node_dres_service
node_dres_service -.->|"calls client"| node_dres_bindings
node_dres_bindings -.->|"calls API"| node_dres

click node_app_shell "https://github.com/vitrivr/vitrivr-ng/blob/master/src/app/app.component.ts"
click node_query_sidebar "https://github.com/vitrivr/vitrivr-ng/blob/master/src/app/query/query-sidebar.component.ts"
click node_query_terms "https://github.com/vitrivr/vitrivr-ng/tree/master/src/app/query/containers"
click node_temporal "https://github.com/vitrivr/vitrivr-ng/blob/master/src/app/query/temporal-distance/temporal-distance.component.ts"
click node_query_models "https://github.com/vitrivr/vitrivr-ng/tree/master/src/app/shared/model/queries"
click node_query_service "https://github.com/vitrivr/vitrivr-ng/blob/master/src/app/core/queries/query.service.ts"
click node_websocket "https://github.com/vitrivr/vitrivr-ng/blob/master/src/app/core/api/web-socket-factory.service.ts"
click node_cineast_bindings "https://github.com/vitrivr/vitrivr-ng/tree/master/openapi/cineast/api"
click node_results "https://github.com/vitrivr/vitrivr-ng/tree/master/src/app/results"
click node_result_state "https://github.com/vitrivr/vitrivr-ng/blob/master/src/app/shared/model/results/scores/results-container.model.ts"
click node_history "https://github.com/vitrivr/vitrivr-ng/blob/master/src/app/core/queries/history.service.ts"
click node_details "https://github.com/vitrivr/vitrivr-ng/tree/master/src/app/objectdetails"
click node_segment_details "https://github.com/vitrivr/vitrivr-ng/tree/master/src/app/segmentdetails"
click node_selection "https://github.com/vitrivr/vitrivr-ng/blob/master/src/app/core/selection/selection.service.ts"
click node_lookup "https://github.com/vitrivr/vitrivr-ng/blob/master/src/app/core/lookup/distinct-element-lookup.service.ts"
click node_config "https://github.com/vitrivr/vitrivr-ng/blob/master/src/app/shared/model/config/config.model.ts"
click node_competition_ui "https://github.com/vitrivr/vitrivr-ng/blob/master/src/app/settings/dres/dres-sidebar.component.ts"
click node_competition_services "https://github.com/vitrivr/vitrivr-ng/tree/master/src/app/core/competition"
click node_dres_service "https://github.com/vitrivr/vitrivr-ng/blob/master/src/app/core/basics/dres.service.ts"
click node_dres_bindings "https://github.com/vitrivr/vitrivr-ng/tree/master/openapi/dres/api"

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_query_sidebar,node_query_terms,node_temporal,node_query_models,node_user toneBlue
class node_query_service,node_results,node_result_state,node_history,node_details,node_segment_details,node_selection toneAmber
class node_app_shell,node_websocket,node_cineast_bindings,node_lookup,node_config toneMint
class node_competition_ui,node_competition_services,node_dres_service,node_dres_bindings toneRose
class node_cineast,node_dres toneIndigo
```

## Components

### Query authoring

- [Query sidebar](https://github.com/vitrivr/vitrivr-ng/blob/master/src/app/query/query-sidebar.component.ts): `src/app/query/query-sidebar.component.ts`
- [Query terms](https://github.com/vitrivr/vitrivr-ng/tree/master/src/app/query/containers): `src/app/query/containers`
- [Temporal stages](https://github.com/vitrivr/vitrivr-ng/blob/master/src/app/query/temporal-distance/temporal-distance.component.ts): `src/app/query/temporal-distance/temporal-distance.component.ts`
- [Query models](https://github.com/vitrivr/vitrivr-ng/tree/master/src/app/shared/model/queries): `src/app/shared/model/queries`

### Retrieval and results

- [Query service](https://github.com/vitrivr/vitrivr-ng/blob/master/src/app/core/queries/query.service.ts): `src/app/core/queries/query.service.ts`
- [Result views](https://github.com/vitrivr/vitrivr-ng/tree/master/src/app/results): `src/app/results`
- [Scored results](https://github.com/vitrivr/vitrivr-ng/blob/master/src/app/shared/model/results/scores/results-container.model.ts): `src/app/shared/model/results/scores/results-container.model.ts`
- [Query history](https://github.com/vitrivr/vitrivr-ng/blob/master/src/app/core/queries/history.service.ts): `src/app/core/queries/history.service.ts`
- [Media details](https://github.com/vitrivr/vitrivr-ng/tree/master/src/app/objectdetails): `src/app/objectdetails`
- [Segment details](https://github.com/vitrivr/vitrivr-ng/tree/master/src/app/segmentdetails): `src/app/segmentdetails`
- [Selection and tags](https://github.com/vitrivr/vitrivr-ng/blob/master/src/app/core/selection/selection.service.ts): `src/app/core/selection/selection.service.ts`

### Application services

- [App shell](https://github.com/vitrivr/vitrivr-ng/blob/master/src/app/app.component.ts): `src/app/app.component.ts`
- [WebSocket factory](https://github.com/vitrivr/vitrivr-ng/blob/master/src/app/core/api/web-socket-factory.service.ts): `src/app/core/api/web-socket-factory.service.ts`
- [Cineast API bindings](https://github.com/vitrivr/vitrivr-ng/tree/master/openapi/cineast/api): `openapi/cineast/api`
- [Distinct lookup](https://github.com/vitrivr/vitrivr-ng/blob/master/src/app/core/lookup/distinct-element-lookup.service.ts): `src/app/core/lookup/distinct-element-lookup.service.ts`
- [Configuration](https://github.com/vitrivr/vitrivr-ng/blob/master/src/app/shared/model/config/config.model.ts): `src/app/shared/model/config/config.model.ts`

### Competition

- [Competition UI](https://github.com/vitrivr/vitrivr-ng/blob/master/src/app/settings/dres/dres-sidebar.component.ts): `src/app/settings/dres/dres-sidebar.component.ts`
- [Competition services](https://github.com/vitrivr/vitrivr-ng/tree/master/src/app/core/competition): `src/app/core/competition`
- [DRES service](https://github.com/vitrivr/vitrivr-ng/blob/master/src/app/core/basics/dres.service.ts): `src/app/core/basics/dres.service.ts`
- [DRES API bindings](https://github.com/vitrivr/vitrivr-ng/tree/master/openapi/dres/api): `openapi/dres/api`

### Other components

- **User**
- **Cineast**
- **DRES**

## Connections

- User → Query sidebar: configures query
- Query sidebar → Query terms: edits terms
- Query sidebar → Temporal stages: sets stage spacing
- Query sidebar → Query service: submits query
- Query service → Query models: builds messages
- Query service → WebSocket factory: sends query
- WebSocket factory → Cineast: exchanges messages
- Cineast → WebSocket factory: streams results
- Query service → Scored results: processes results
- Query service → Query history: appends results
- Scored results → Result views: supplies results
- User → Result views: browses results
- Result views → Media details: opens object
- Result views → Segment details: opens segment
- User → Selection and tags: manages selections
- Query terms → Cineast API bindings: looks up tags
- Cineast API bindings → Cineast: calls REST API
- App shell → Query service: observes status
- App shell → Distinct lookup: initializes lookup
- App shell → Configuration: reads settings
- Competition UI → Competition services: uses competition tools
- Competition services → DRES service: records and submits
- DRES service → DRES API bindings: calls client
- DRES API bindings → DRES: calls API