ADR-011: Introduce Pluggable AI Infrastructure Layer

Context

AI capabilities are being introduced into OneCMS (e.g., content enhancement and metadata generation).

The current production implementation integrates OpenAI directly within route handlers.
This mixes infrastructure concerns (provider calls) with business logic (prompt construction, field selection, parsing).

Without a dedicated AI layer, future expansion (multiple providers, org-level configuration, AI management UI) would require refactoring routes and business modules.

A structural boundary is required before AI becomes a first-class capability in the system.

Decision

Introduce a dedicated AI infrastructure layer under:

src/lib/ai

This layer will be divided into:

• core/ – provider-agnostic runtime primitives
• providers/ – concrete AI provider implementations and resolver logic
• domain/ – AI task-aware logic (e.g., content enhancement) - ADR-012

The core layer will expose a single runtime entry:

aiRuntime.complete()

The infrastructure layer will be:

• Stateless in v1
• Provider-pluggable
• Independent of CMS data access
• Independent of database writes

Routes and modules must not call provider SDKs directly.

Consequences

Enables

• Clean separation of infrastructure and business logic
• Future provider expansion without refactoring domain modules
• Org-level provider selection in future AI Management section
• AI as a foundational system capability rather than route-level utility

Restricts

• No direct OpenAI usage outside lib/ai
• No CMS-specific logic inside infrastructure layer
• No task abstraction inside runtime

Trade-offs Accepted

• v1 supports a single provider (OpenAI)
• No caching or streaming in initial version
• Prompt logic remains domain-level, not infrastructure-level

Notes

Future ADRs will define:

• Domain separation from CMS data access
• Stateless generation approach
• Schema enforcement strategy