---
title: "Architecture"
manual: "LLM Foundation"
version: "0.44"
permalink: "https://docs.typo3.org/permalink/netresearch/nr-llm:architecture@0.44"
source: "Architecture/Index.rst"
rendered: "2026-11-12T17:35:48+00:00"
---
# Architecture {#architecture}
nr-llm separates a use-case configuration, a model and its provider connection.
Applications normally call the configuration-bound service rather than an
adapter directly. The provider protocol maps that operation to its own API;
it is not always an OpenAI Chat Completions endpoint.
## Selection and execution {#architecture-benefits}
1. Resolve a configuration with the caller's access checks.
1. In fixed mode, use its model. In criteria mode, select an eligible model
for the requested operation without mutating the configuration entity.
1. Resolve that model's provider and nr-vault credential reference.
1. Compose the applicable prompt, snippets and skills for that service path.
1. Screen inputs and execute the provider pipeline. Record usage and permitted
telemetry. Apply output policy before returning the result.
The exact call path matters: converting a configuration to options does not
retain its identity or every policy. See [Step 5: Select a database configuration](https://docs.typo3.org/permalink/netresearch/nr-llm:integration-guide-step5@0.44),
[Model routing reference](https://docs.typo3.org/permalink/netresearch/nr-llm:routing-reference@0.44) and [Persisted agent runtime](https://docs.typo3.org/permalink/netresearch/nr-llm:api-agent-runtime@0.44).
## Provider connection {#architecture-provider-layer}
`tx_nrllm_provider` holds adapter type, endpoint, a vault identifier,
request limits, declared trust zone and persistence ceiling. Several provider
records may use one protocol with different accounts or endpoints.
See [Provider fields](https://docs.typo3.org/permalink/netresearch/nr-llm:configuration-provider@0.44) for actual field names and defaults.
## Model catalogue {#architecture-model-layer}
`tx_nrllm_model` belongs to a provider. It declares the outbound model ID,
context/output limits, capabilities and pricing. Capability provenance is
metadata, not proof of successful execution. A model's presence does not
establish support for every operation. See [Model fields](https://docs.typo3.org/permalink/netresearch/nr-llm:configuration-model@0.44).
## Use-case configuration {#architecture-configuration-layer}
`tx_nrllm_configuration` stores fixed/criteria selection, optional system
prompt, parameters, budgets, fallback references, prompt attachments and
access rules. There is no `use_case_type` field; the calling service chooses
the operation. Criteria mode does not require a fixed model relation.
See [Configuration field reference](https://docs.typo3.org/permalink/netresearch/nr-llm:configuration-llm@0.44).
## Consumer and extension contracts {#architecture-feature-services}
- [API reference](https://docs.typo3.org/permalink/netresearch/nr-llm:api-reference@0.44) identifies public consumer interfaces and extension
points. `LlmServiceManagerInterface` coordinates stateless operations.
- Feature services adapt completion, translation, image input and embeddings.
[Specialized services](https://docs.typo3.org/permalink/netresearch/nr-llm:api-specialized-services@0.44) covers separate translator/image/speech paths.
- [Stored conversations](https://docs.typo3.org/permalink/netresearch/nr-llm:api-conversations@0.44) persists session history with explicit actor checks.
- [Persisted agent runtime](https://docs.typo3.org/permalink/netresearch/nr-llm:api-agent-runtime@0.44) owns persisted execution, queueing and human pauses.
- [Tool extension API](https://docs.typo3.org/permalink/netresearch/nr-llm:api-tool-extensions@0.44) and [Guardrail extensions](https://docs.typo3.org/permalink/netresearch/nr-llm:api-guardrails@0.44) are implementation
contracts for extensions. A manual tool protocol does not acquire the
managed runtime's policy or approval behavior automatically.
## Adapter protocols {#architecture-adapter-types}
The [Adapter catalogue](https://docs.typo3.org/permalink/netresearch/nr-llm:configuration-adapters@0.44) is the shared protocol inventory. Decision
adapters answer typed questions; they do not generate chat text. Text adapters
can use Responses, Messages, generateContent or compatible endpoints.
Custom provider code remains trusted server code.
## Credentials and boundaries {#architecture-api-key-encryption}
nr-llm's provider records store nr-vault UUID references, not encrypted key
material owned by nr-llm. Vault authentication resolves secrets when required;
some specialized routing paths briefly inspect a key in memory. Database
references do not remove the need to secure vault storage, backups and logs.
Budgets are preflight checks, not atomic reservations. Trust zones are operator
declarations, not a proof of provider hosting. Egress gates constrain
cooperating HTTP paths, not arbitrary PHP. Content logs, conversation history,
waiting-run state and caches have distinct retention rules. See
[Data retention & purge](https://docs.typo3.org/permalink/netresearch/nr-llm:administration-data-retention@0.44) and [Effective policy](https://docs.typo3.org/permalink/netresearch/nr-llm:administration-governance@0.44).
Architecture history belongs in [Architecture decision records](https://docs.typo3.org/permalink/netresearch/nr-llm:architecture-decision-records@0.44).
Those records explain decisions at their dates; current API and operations
pages state the contract to use today.