Architecture Decision Records 

This section documents significant architectural decisions made during the development of the TYPO3 LLM Extension.

Symbol legend 

Each consequence in the ADRs is marked with severity symbols to indicate impact weight:

Symbol Meaning Weight
●● Strong Positive +2 to +3
Medium Positive +1 to +2
Light Positive +0.5 to +1
Medium Negative -1 to -2
✕✕ Strong Negative -2 to -3
Light Negative -0.5 to -1

Net Score indicates the overall impact of the decision (sum of weights).

Decision records 

Foundation 

ADR-001: Provider abstraction layer 

Unified interface for OpenAI, Claude, Gemini, Ollama, and more.

ADR-002: Feature services architecture 

Translation, vision, embeddings, completion as injectable services.

ADR-003: Typed response objects 

Immutable value objects for all LLM responses.

ADR-007: Multi-provider strategy 

Fallback chains and provider selection logic.

ADR-013: Three-level configuration 

Provider -> Model -> Configuration hierarchy.

TYPO3 integration 

ADR-004: PSR-14 event system 

Extension points via TYPO3 events.

ADR-005: Caching framework 

Instance-default backend, nrllm cache group.

ADR-012: API key encryption 

Superseded — now via nr-vault envelope encryption.

API design 

ADR-006: Option objects vs arrays 

Typed option objects for API calls.

ADR-008: Error handling strategy 

Exception hierarchy and retry logic.

ADR-009: Streaming implementation 

Chunked transfer for real-time output.

ADR-010: Tool/function calling 

Provider-agnostic tool call abstraction.

ADR-011: Object-only options API 

Removed array support, typed objects only.

Modern architecture (v0.4+) 

ADR-014: AI-powered wizard system 

Natural language -> structured configuration generation with fallback defaults.

ADR-015: Type-safe domain models 

PHP 8.1+ enums, DTOs, and value objects.

ADR-016: Thinking block extraction 

Reasoning blocks from Claude, DeepSeek, Qwen.

ADR-017: SafeCastTrait 

PHPStan level 10 compliance for mixed input.

ADR-018: Model discovery 

Multi-provider model listing with fallback catalogs.

ADR-019: Internationalization 

XLIFF + locale-aware features with {lang} placeholders.

ADR-020: Output format rendering 

Client-side plain/markdown/HTML toggle.