Context
AI generation introduces questions around state management and acceptance flow:
- Should AI generations be cached server-side?
- Should AI own draft persistence?
- Should acceptance be a backend-controlled workflow?
- How should AI usage be tracked?
A fully stateful workflow (caching generations, server-controlled accept, draft persistence inside AI layer) increases complexity and couples AI to content lifecycle.
At the same time, complete frontend-only handling would make AI usage invisible to the backend, preventing auditability and future analytics.
A balanced decision is required.
Decision
AI generation in v1 will be stateless, with explicit audit logging.
Generation
- AI generation does not create server-side draft state.
- Generated suggestions are returned directly to the client.
- The backend records an audit entry for each generation event.
Acceptance
- Acceptance is handled on the frontend by updating form state (e.g., RHF fields).
- Content persistence occurs through the existing content update handler.
- A separate API call records an audit entry for accepted AI suggestions.
- AI does not directly write content to the database.
- Audit writes can be toggled using feature flags
The AI layer remains independent from content lifecycle management.
Consequences
Enables
- Stateless generation flow
- No cache invalidation complexity
- Clear separation between AI and content persistence
- Full audit trace of:
- Generation events
- Acceptance events
- Future AI usage analytics and reporting
- Minimal coupling between AI and content modules
Restricts
- No server-side persistence of intermediate generations
- No tamper-resistant storage of AI outputs in v1
- No AI-controlled draft workflow
- Regeneration always invokes a fresh AI call
Trade-offs Accepted
- Acceptance relies on frontend-driven content updates.
- AI does not validate content hash during accept.
- Audit captures metadata only (not full generated content).
- Advanced features (draft persistence, streaming, multi-step workflows) are postponed.
Notes
- Audit entries must not store full generated content.
- Future ADR may introduce an AI Draft Persistence Layer if required.
- AI remains a transformation engine, not a content lifecycle controller.