---
title: "Architecture decisions"
manual: "AI Assistant"
version: "main"
source: "Developers/Architecture/ADR.rst"
rendered: "2026-10-03T14:54:45+00:00"
---

# Architecture decisions {#adr}

## ADR-001: Registry-based extension architecture {#adr-001-registry-based-extension-architecture}

The extension uses registries for processors, indexers, connectors and adapters.
This keeps orchestration generic and allows third-party extensions to add
functionality through dependency injection tags.

## ADR-002: Separate AI and vector store connections {#adr-002-separate-ai-and-vector-store-connections}

AI providers and vector databases are configured independently. This allows the
same assistant to use different providers for chat, embeddings and vector
storage without changing pipeline code.

## ADR-003: Pipeline instead of fixed chat workflow {#adr-003-pipeline-instead-of-fixed-chat-workflow}

The assistant request is processed by configured steps. This supports simple
retrieval-augmented answers and advanced workflows with query refinement,
context optimization and quality gates.

## ADR-004: Prompts in records, not processors {#adr-004-prompts-in-records-not-processors}

Processors implement behaviour. Project-specific prompt text belongs into
assistant profile and pipeline step records so it can be configured and imported.

## ADR-005: SourceHash and ContentHash separation {#adr-005-sourcehash-and-contenthash-separation}

A stable source hash identifies the same source. A content hash detects changes.
This avoids duplicate vectors after re-indexing.

## ADR-006: Collection and storage are indexing scope {#adr-006-collection-and-storage-are-indexing-scope}

The same collection name can exist in different vector stores. Indexing state
therefore considers both vector store connection and collection. Source hash
remains independent of storage and collection.

## ADR-007: Metadata-driven retrieval {#adr-007-metadata-driven-retrieval}

Retrieved documents must preserve payload metadata. Prompt metadata and frontend
source fields are configured per step to balance traceability, safety and prompt
size.