Context
When designing the AI infrastructure layer, there are two architectural patterns:
- A thin runtime exposing a single completion method (e.g.,
complete()). - A task-based runtime (e.g.,
runTask("content-enhancement")) where infrastructure becomes aware of business-level tasks.
A task-based runtime centralizes logic but introduces coupling between infrastructure and domain concerns.
As OneCMS introduces AI capabilities, it must preserve clear separation between:
- Infrastructure (provider abstraction)
- Domain logic (prompt construction, schema enforcement)
A decision is required to prevent task abstraction from leaking into the infrastructure layer.
Decision
The AI infrastructure layer will expose a single public runtime method:
aiRuntime.complete()
Infrastructure will not:
- Define AI tasks
- Register domain-level operations
- Provide
runTask()abstractions - Contain prompt-building logic
Domain-specific orchestration (e.g., content enhancement, draft generation) will live inside lib/ai/domain.
The runtime remains a thin execution layer responsible only for:
- Resolving provider
- Executing completion
- Returning normalized response
Consequences
Enables
- Clean separation between infrastructure and domain logic
- Provider-swapping without affecting task logic
- Reduced abstraction complexity
- Easier reasoning about runtime behavior
- Stable public API surface
Restricts
- No centralized task registry in infrastructure
- Domain modules must orchestrate prompts explicitly
- Slight duplication across domains if similar tasks emerge
Trade-offs Accepted
- Infrastructure remains intentionally minimal.
- Future cross-domain task abstractions, if needed, will be introduced explicitly via new ADR.
- Avoids premature generalization of AI task orchestration.
Notes
If future requirements introduce repeated AI workflows across multiple domains, a separate task abstraction layer may be considered. That decision will require its own ADR.