.. include:: /Includes.rst.txt .. _adr: .. _architecture-decision-records: ============================== Architecture Decision Records ============================== This section documents significant architectural decisions made during the development of the TYPO3 LLM Extension. .. _adr-symbol-legend: 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). .. _adr-decision-records: Decision records ================ .. _adr-foundation: Foundation ---------- .. card-grid:: :columns: 1 :columns-md: 2 :gap: 4 :card-height: 100 .. card:: ADR-001: Provider abstraction layer Unified interface for OpenAI, Claude, Gemini, Ollama, and more. .. card-footer:: :ref:`Read ` :button-style: btn btn-secondary stretched-link .. card:: ADR-002: Feature services architecture Translation, vision, embeddings, completion as injectable services. .. card-footer:: :ref:`Read ` :button-style: btn btn-secondary stretched-link .. card:: ADR-003: Typed response objects Immutable value objects for all LLM responses. .. card-footer:: :ref:`Read ` :button-style: btn btn-secondary stretched-link .. card:: ADR-007: Multi-provider strategy Fallback chains and provider selection logic. .. card-footer:: :ref:`Read ` :button-style: btn btn-secondary stretched-link .. card:: ADR-013: Three-level configuration Provider -> Model -> Configuration hierarchy. .. card-footer:: :ref:`Read ` :button-style: btn btn-secondary stretched-link .. _adr-integration: TYPO3 integration ----------------- .. card-grid:: :columns: 1 :columns-md: 2 :gap: 4 :card-height: 100 .. card:: ADR-004: PSR-14 event system Extension points via TYPO3 events. .. card-footer:: :ref:`Read ` :button-style: btn btn-secondary stretched-link .. card:: ADR-005: Caching framework Instance-default backend, ``nrllm`` cache group. .. card-footer:: :ref:`Read ` :button-style: btn btn-secondary stretched-link .. card:: ADR-012: API key encryption Superseded — now via nr-vault envelope encryption. .. card-footer:: :ref:`Read ` :button-style: btn btn-secondary stretched-link .. _adr-api-design: API design ---------- .. card-grid:: :columns: 1 :columns-md: 2 :gap: 4 :card-height: 100 .. card:: ADR-006: Option objects vs arrays Typed option objects for API calls. .. card-footer:: :ref:`Read ` :button-style: btn btn-secondary stretched-link .. card:: ADR-008: Error handling strategy Exception hierarchy and retry logic. .. card-footer:: :ref:`Read ` :button-style: btn btn-secondary stretched-link .. card:: ADR-009: Streaming implementation Chunked transfer for real-time output. .. card-footer:: :ref:`Read ` :button-style: btn btn-secondary stretched-link .. card:: ADR-010: Tool/function calling Provider-agnostic tool call abstraction. .. card-footer:: :ref:`Read ` :button-style: btn btn-secondary stretched-link .. card:: ADR-011: Object-only options API Removed array support, typed objects only. .. card-footer:: :ref:`Read ` :button-style: btn btn-secondary stretched-link .. _adr-modern: Modern architecture (v0.4+) ---------------------------- .. card-grid:: :columns: 1 :columns-md: 2 :gap: 4 :card-height: 100 .. card:: ADR-014: AI-powered wizard system Natural language -> structured configuration generation with fallback defaults. .. card-footer:: :ref:`Read ` :button-style: btn btn-secondary stretched-link .. card:: ADR-015: Type-safe domain models PHP 8.1+ enums, DTOs, and value objects. .. card-footer:: :ref:`Read ` :button-style: btn btn-secondary stretched-link .. card:: ADR-016: Thinking block extraction Reasoning blocks from Claude, DeepSeek, Qwen. .. card-footer:: :ref:`Read ` :button-style: btn btn-secondary stretched-link .. card:: ADR-017: SafeCastTrait PHPStan level 10 compliance for mixed input. .. card-footer:: :ref:`Read ` :button-style: btn btn-secondary stretched-link .. card:: ADR-018: Model discovery Multi-provider model listing with fallback catalogs. .. card-footer:: :ref:`Read ` :button-style: btn btn-secondary stretched-link .. card:: ADR-019: Internationalization XLIFF + locale-aware features with {lang} placeholders. .. card-footer:: :ref:`Read ` :button-style: btn btn-secondary stretched-link .. card:: ADR-020: Output format rendering Client-side plain/markdown/HTML toggle. .. card-footer:: :ref:`Read ` :button-style: btn btn-secondary stretched-link .. card:: ADR-037: Backend AJAX admin guard Shared trait requires a backend admin on every backend AJAX endpoint (403 otherwise). .. card-footer:: :ref:`Read ` :button-style: btn btn-secondary stretched-link .. _adr-skills: Skills ------ .. card-grid:: :columns: 1 :columns-md: 2 :gap: 4 :card-height: 100 .. card:: ADR-035: Skill ingest GitHub-hosted ``SKILL.md`` sources: host allowlist, SHA-pin + checksum, disabled-by-default review. .. card-footer:: :ref:`Read ` :button-style: btn btn-secondary stretched-link .. card:: ADR-036: Skill injection Attach skills to tasks/configurations; compose into the user prompt (text-gen only), budgeted and checksum-verified. .. card-footer:: :ref:`Read ` :button-style: btn btn-secondary stretched-link .. _adr-tools: Tools ----- .. card-grid:: :columns: 1 :columns-md: 2 :gap: 4 :card-height: 100 .. card:: ADR-038: Tool runtime DI-tagged tool registry + bounded agent loop on the config's vault key/model/pricing; allow-list gated, admin-only. .. card-footer:: :ref:`Read ` :button-style: btn btn-secondary stretched-link .. card:: ADR-039: Global tool availability Site-wide per-tool enable/disable override (``tx_nrllm_tool_state``, no TCA) intersected with every run's allow-list — a hard admin kill switch. .. card-footer:: :ref:`Read ` :button-style: btn btn-secondary stretched-link .. toctree:: :hidden: Adr001ProviderAbstractionLayer Adr002FeatureServicesArchitecture Adr003TypedResponseObjects Adr004Psr14EventSystem Adr005Typo3CachingFrameworkIntegration Adr006OptionObjectsVsArrays Adr007MultiProviderStrategy Adr008ErrorHandlingStrategy Adr009StreamingImplementation Adr010ToolFunctionCallingDesign Adr011ObjectOnlyOptionsApi Adr012ApiKeyEncryption Adr013ThreeLevelConfigurationArchitecture Adr014AiPoweredWizardSystem Adr015TypeSafeDomainModels Adr016ThinkingReasoningBlockExtraction Adr017SafeCastTrait Adr018MultiProviderModelDiscovery Adr019InternationalizationStrategy Adr020BackendOutputFormatRendering Adr021ProviderFallbackChain Adr022AttributeBasedProviderRegistration Adr023BackendCapabilityPermissions Adr024DashboardWidgets Adr025PerUserBudgets Adr026ProviderMiddlewarePipeline Adr027SplitTaskController Adr028PublicServicesPolicy Adr029UsageAnalyticsDashboard Adr030SpecializedServicesVaultMigration Adr031PromptSnippetLibrary Adr032SpecializedUsageAndPricingCatalog Adr033SpecializedModelRegistry Adr034RemoveExtensionConfigDefaultProvider Adr035SkillIngest Adr036SkillInjection Adr037BackendAjaxAdminGuard Adr038ToolRuntime Adr039GlobalToolAvailabilityState