lcbp3/specs/200-fullstacks/237-unified-prompt-management-ux-ui/research.md

Research: Unified Prompt Management UX/UI

Feature: 237-unified-prompt-management-ux-ui
Date: 2026-06-14
Purpose: Resolve technical unknowns and document decisions for implementation

Research Topics

1. Context Config Schema Structure

Question: What JSON structure should context_config use in ai_prompts table?

Decision: Use flat JSON object with these fields:

{
  "filter": {
    "projectId": "uuid|null",
    "contractId": "uuid|null"
  },
  "pageSize": 3,
  "language": "th",
  "outputLanguage": "th"
}

Rationale:

• Follows ADR-030 context-aware prompt template structure
• Matches existing OCR extraction prompt context_config from ADR-029
• Flat structure simplifies validation and UI binding
• Filter object allows null values for "all projects/contracts"

Alternatives Considered:

• Nested structure with separate sections (rejected: too complex for simple use case)
• Array-based filter (rejected: single project/contract filter is sufficient)

---

2. Runtime Parameters Storage

Question: Should runtime parameters be stored in a new ai_execution_profiles table or as part of ai_prompts?

Decision: Store in new ai_execution_profiles table (global per profile, not per prompt version)

Rationale:

• Runtime parameters control AI model behavior (temperature, topP) which applies globally across all prompt types
• Separates concerns: Runtime Parameters = AI behavior, Context Config = data context
• Allows admins to test different parameter sets in sandbox without affecting prompts
• Follows ADR-036 unified AI model architecture

Alternatives Considered:

• Store in ai_prompts per version (rejected: would duplicate same parameters across versions)
• Store in Redis only (rejected: no persistence, lost on restart)

---

3. Sandbox RAG Prep Implementation

Question: How should RAG Prep sandbox endpoint integrate with existing infrastructure?

Decision:

• Create new BullMQ job type: "sandbox-rag-prep" in ai-realtime queue
• Reuse existing OllamaService for semantic chunking (typhoon2.5-np-dms)
• Reuse existing embedding service (BGE-M3 via sidecar)
• Return chunks + vectors in sandbox result for display

Rationale:

• Consistent with existing sandbox OCR and AI Extract patterns
• Leverages existing ADR-023A infrastructure (2-model stack, BullMQ queues)
• Allows testing of full production pipeline before deployment
• Follows ADR-035 AI pipeline flow architecture

Alternatives Considered:

• Inline processing without BullMQ (rejected: blocks request thread, no retry)
• Separate queue for RAG Prep (rejected: ai-realtime queue already handles sandbox jobs)

---

4. Context Config Validation

Question: How should invalid context config references (e.g., non-existent project ID) be handled?

Decision:

• Validate project/contract IDs against database on save
• Allow null values (meaning "all projects/contracts")
• Return validation error with user-friendly message if ID doesn't exist
• Do not block activation if context config is valid at save time

Rationale:

• Prevents orphaned references that would cause production failures
• User-friendly error messages align with ADR-007 error handling
• Null values are valid for "unfiltered" context
• Validation at save time is sufficient (no need to re-validate on activation)

Alternatives Considered:

• Allow invalid references and handle at runtime (rejected: production failures)
• Re-validate on activation (rejected: unnecessary if validated at save)

---

5. Placeholder Validation Strategy

Question: How should required placeholders (e.g., {{ocr_text}}) be validated?

Decision:

• Define required placeholders per prompt type:
  • ocr_extraction: {{ocr_text}}, {{master_data_context}}
  • rag_query_prompt: {{query}}, {{context}}
  • rag_prep_prompt: {{text}}
  • classification_prompt: {{document_text}}
• Validate on save: template must contain all required placeholders
• Return validation error listing missing placeholders
• Allow additional optional placeholders

Rationale:

• Prevents production failures from missing placeholders
• Clear error messages help admins understand requirements
• Flexible enough for future placeholder additions
• Aligns with ADR-029 dynamic prompt management

Alternatives Considered:

• Validate at runtime (rejected: production failures)
• No validation (rejected: too error-prone)

---

6. Version Numbering Strategy

Question: How should version numbers be incremented across prompt types?

Decision:

• Version numbers are per prompt_type (independent counters)
• Each prompt_type has its own sequence: ocr_extraction v1, v2, v3; rag_query_prompt v1, v2, etc.
• Auto-increment on save: MAX(version_number) + 1 for that prompt_type
• Display version number in format: "v{number} ({prompt_type})"

Rationale:

• Clear separation between prompt types
• No confusion about which version belongs to which type
• Auto-increment prevents manual errors
• Consistent with ADR-029 versioning approach

Alternatives Considered:

• Global version counter across all types (rejected: confusing which version is for which type)
• Manual version entry (rejected: error-prone)

---

7. Sandbox State Management

Question: How should sandbox state (OCR text, extracted metadata) be passed between steps?

Decision:

• Store sandbox job results in Redis with TTL 1 hour
• Use job ID as key: sandbox:job:{jobId}
• Each step (OCR, AI Extract, RAG Prep) writes its result to the same key
• Frontend polls job status using job ID
• Results cleared after TTL or manual "Clear Sandbox" action

Rationale:

• Stateless API design (no session state in backend)
• Redis is already available for BullMQ
• TTL prevents memory leaks
• Allows multi-step workflow without passing large payloads in requests
• Consistent with existing sandbox patterns

Alternatives Considered:

• Pass results in request/response (rejected: large payloads, complexity)
• Store in database (rejected: unnecessary persistence, cleanup overhead)

---

8. Frontend Component Architecture

Question: How should the unified prompt management page be structured?

Decision:

• Single page at /admin/ai/prompt-management
• 3-panel layout: Left (Version History), Center (Prompt Editor + Context Config), Right (Sandbox)
• PromptTypeDropdown at top of page (global state)
• Use React Hook Form for Context Config Editor (validation, type safety)
• Use TanStack Query for data fetching (version history, active version)
• Use shadcn/ui components (consistent with existing admin pages)

Rationale:

• Consistent with ADR-027 single page layout
• 3-panel layout maximizes screen real estate
• RHF + Zod for form validation (best practice)
• TanStack Query for caching and optimistic updates
• shadcn/ui for consistent styling

Alternatives Considered:

• Multi-page design (rejected: violates ADR-027 single page constraint)
• 2-panel layout (rejected: insufficient space for sandbox)

---

Summary

All technical unknowns resolved. Key decisions:

1. Context config uses flat JSON with filter object
2. Runtime parameters in new ai_execution_profiles table
3. Sandbox RAG Prep uses existing BullMQ infrastructure
4. Context config validated on save against database
5. Placeholder validation per prompt type
6. Version numbers per prompt_type (independent counters)
7. Sandbox state in Redis with TTL 1 hour
8. Frontend: 3-panel single page with RHF + TanStack Query + shadcn/ui