@thierrynakoa/fire-flow 12.2.1 → 13.0.1

package/skills-library/database-solutions/AI_RESPONSE_DATABASE_CACHING.md

@@ -0,0 +1,520 @@
+# AI Response Database Caching - Persistent Caching for Expensive AI-Generated Content
+
+## The Problem
+
+AI APIs (Claude, Gemini, GPT-4) are expensive and slow. Every regeneration costs money and time:
+- **Chapter outlines:** ~$0.02-0.05 per generation (2-5 seconds)
+- **Knowledge graphs:** ~$0.10-0.50 per graph (10-30 seconds)
+- **Pattern discovery:** ~$0.05-0.15 per analysis (5-15 seconds)
+
+Without caching, users experience:
+- ❌ Slow load times waiting for AI regeneration
+- ❌ Expensive API costs for repeated requests
+- ❌ Lost data when refreshing or navigating away
+- ❌ Poor UX (waiting for content that was already generated)
+
+### Example Scenario
+
+User studies Genesis 1, generates a chapter outline. Next week they return to Genesis 1:
+- **Without caching:** Regenerate the outline ($0.03, 3 seconds wait)
+- **With caching:** Load instantly from database (free, <100ms)
+
+**Multiply by hundreds of users and chapters = massive savings.**
+
+### Why It Was Hard
+
+1. **Data structure mismatch** - AI responses are complex JSON that don't fit simple text columns
+2. **Cache invalidation** - When to regenerate vs use cached data?
+3. **Provider switching** - Different AI providers (Claude vs Gemini) produce different formats
+4. **Forever persistence** - User expectation: "I generated this, it should stay forever"
+5. **PostgreSQL constraints** - Need proper indexing for fast lookups without table scans
+
+### Impact
+
+**Before caching:**
+- Page load: 3-5 seconds (AI generation)
+- Cost per request: $0.02-0.50
+- Data persistence: None (lost on refresh)
+
+**After caching:**
+- Page load: <100ms (database query)
+- Cost per request: $0.00 (cache hit)
+- Data persistence: Forever in PostgreSQL
+
+---
+
+## The Solution
+
+### Architecture: Database-First Caching Pattern
+
+```
+1. Check cache in PostgreSQL
+   └─ Cache hit? → Return instantly
+   └─ Cache miss? → Generate with AI → Save to DB → Return
+
+2. Force regeneration (user request)
+   └─ Skip cache → Generate with AI → Update DB → Return
+```
+
+### Root Cause
+
+Traditional approaches treat AI responses as ephemeral (localStorage, memory cache). But users expect **permanent persistence** - "I generated this content, it should be saved forever."
+
+Solution: Treat AI-generated content as **first-class data** stored in PostgreSQL with proper schema design.
+
+---
+
+## Implementation
+
+### Step 1: Design Database Schema
+
+Use Prisma ORM for type-safe database access:
+
+```prisma
+// schema.prisma
+
+/// Cached chapter outlines - persist generated outlines forever
+model CachedChapterOutline {
+  id        String   @id @default(cuid())
+  bookName  String
+  chapter   Int
+  provider  String   // "claude" or "gemini"
+  outline   Json     // Full ChapterOutline JSON
+
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+
+  @@unique([bookName, chapter]) // One cached outline per chapter
+  @@index([bookName, chapter])   // Fast lookups
+}
+
+/// Cached knowledge graphs - saves Gemini API costs
+model KnowledgeGraph {
+  id          String  @id @default(uuid()) @db.Uuid
+  userId      String  @unique // One graph per user
+
+  sourceCount Int
+  nodeCount   Int
+  edgeCount   Int
+
+  graphData   Json    @db.JsonB // Full graph structure
+  isStale     Boolean @default(false) // Invalidation flag
+
+  createdAt   DateTime @default(now())
+  updatedAt   DateTime @updatedAt
+
+  @@index([userId])
+  @@index([isStale]) // Find graphs needing regeneration
+}
+```
+
+**Key design decisions:**
+- `Json` column type for flexible AI response structures
+- Unique constraints prevent duplicate caching
+- Composite indexes for fast lookups (avoid table scans)
+- `provider` field tracks which AI generated the content
+- `isStale` flag for cache invalidation strategy
+
+### Step 2: Implement Cache-First Service Pattern
+
+```typescript
+// server/services/content-generator.service.ts
+
+import { PrismaClient } from '@prisma/client';
+const prisma = new PrismaClient();
+
+interface ChapterOutline {
+  book: string;
+  chapter: number;
+  title: string;
+  structure: any[];
+  themes: string[];
+  keyVerses: string[];
+}
+
+export async function getChapterOutline(
+  bookName: string,
+  chapter: number,
+  provider: 'claude' | 'gemini' = 'claude',
+  force: boolean = false
+): Promise<{ outline: ChapterOutline; cached: boolean }> {
+
+  // STEP 1: Check cache (unless force regeneration)
+  if (!force) {
+    const cached = await prisma.cachedChapterOutline.findUnique({
+      where: { bookName_chapter: { bookName, chapter } }
+    });
+
+    if (cached) {
+      console.log(`[Cache HIT] ${bookName} ${chapter}`);
+      return {
+        outline: cached.outline as ChapterOutline,
+        cached: true
+      };
+    }
+  }
+
+  // STEP 2: Cache miss - generate with AI
+  console.log(`[Cache MISS] Generating ${bookName} ${chapter} with ${provider}`);
+  const outline = await generateWithAI(bookName, chapter, provider);
+
+  // STEP 3: Save to database for future requests
+  await prisma.cachedChapterOutline.upsert({
+    where: { bookName_chapter: { bookName, chapter } },
+    update: {
+      outline,
+      provider,
+      updatedAt: new Date()
+    },
+    create: {
+      bookName,
+      chapter,
+      provider,
+      outline
+    }
+  });
+
+  console.log(`[Cache SAVED] ${bookName} ${chapter}`);
+  return { outline, cached: false };
+}
+
+async function generateWithAI(
+  bookName: string,
+  chapter: number,
+  provider: 'claude' | 'gemini'
+): Promise<ChapterOutline> {
+  // Call AI API (Claude/Gemini) to generate outline
+  // This is the expensive operation we're caching
+  const response = await callAIProvider(provider, bookName, chapter);
+  return parseOutlineResponse(response);
+}
+```
+
+### Step 3: Add Force Regeneration Parameter
+
+Allow users to bypass cache when needed:
+
+```typescript
+// server/routes/content.ts
+
+router.get('/api/chapters/:book/:chapter/outline', async (req, res) => {
+  const { book, chapter } = req.params;
+  const force = req.query.force === 'true'; // ?force=true to skip cache
+  const provider = req.query.provider || 'claude';
+
+  const result = await getChapterOutline(book, parseInt(chapter), provider, force);
+
+  res.json({
+    ...result.outline,
+    cached: result.cached, // Tell frontend if this was cached
+    generatedAt: new Date().toISOString()
+  });
+});
+```
+
+### Step 4: Handle Cache Invalidation
+
+Two strategies:
+
+**Strategy 1: Stale flag (soft delete)**
+```typescript
+// Mark cache as stale without deleting
+await prisma.knowledgeGraph.update({
+  where: { userId },
+  data: { isStale: true }
+});
+
+// Regenerate stale caches in background job
+const staleGraphs = await prisma.knowledgeGraph.findMany({
+  where: { isStale: true }
+});
+```
+
+**Strategy 2: Time-based invalidation**
+```typescript
+// Check if cache is older than 30 days
+const cached = await prisma.cachedChapterOutline.findUnique({
+  where: { bookName_chapter: { bookName, chapter } }
+});
+
+const isExpired = cached &&
+  Date.now() - cached.updatedAt.getTime() > 30 * 24 * 60 * 60 * 1000;
+
+if (isExpired) {
+  // Regenerate
+}
+```
+
+---
+
+## Testing the Solution
+
+### Test 1: Cache Miss → Cache Hit
+
+```bash
+# First request (cache miss)
+time curl http://localhost:3005/api/chapters/Genesis/1/outline
+# Response time: 3.2s
+# Response includes: "cached": false
+
+# Second request (cache hit)
+time curl http://localhost:3005/api/chapters/Genesis/1/outline
+# Response time: 0.08s ⚡
+# Response includes: "cached": true
+```
+
+**Result:** 40x faster on cache hit!
+
+### Test 2: Force Regeneration
+
+```bash
+curl "http://localhost:3005/api/chapters/Genesis/1/outline?force=true"
+# Bypasses cache, calls AI API, updates database
+# Response: "cached": false
+```
+
+### Test 3: Database Query Performance
+
+```sql
+-- Query with composite index (FAST)
+EXPLAIN ANALYZE
+SELECT * FROM cached_chapter_outlines
+WHERE book_name = 'Genesis' AND chapter = 1;
+
+-- Result: Index Scan, 0.05ms ✓
+
+-- Without index (SLOW)
+-- Result: Seq Scan, 15ms ❌
+```
+
+### Test 4: Cost Savings Over Time
+
+```javascript
+// Track API cost savings
+const stats = await prisma.cachedChapterOutline.aggregate({
+  _count: { id: true }
+});
+
+const cacheHits = stats._count.id;
+const estimatedSavings = cacheHits * 0.03; // $0.03 per generation
+
+console.log(`Cache hits: ${cacheHits}`);
+console.log(`Estimated savings: $${estimatedSavings.toFixed(2)}`);
+
+// After 1 week with 100 users:
+// Cache hits: 2,847
+// Estimated savings: $85.41 ✓
+```
+
+---
+
+## Prevention & Best Practices
+
+### 1. Always Use Composite Indexes
+
+```prisma
+@@unique([bookName, chapter])  // Uniqueness constraint
+@@index([bookName, chapter])   // Fast lookup index
+```
+
+Without proper indexing, PostgreSQL will do expensive table scans.
+
+### 2. Use Json/JsonB Column Types
+
+```prisma
+outline Json     // Standard JSON
+graphData Json @db.JsonB  // Binary JSON (faster queries, supports indexing)
+```
+
+`JsonB` is preferred for:
+- Faster queries
+- Supports GIN indexes
+- Slightly slower writes (negligible)
+
+### 3. Track Cache Metadata
+
+```prisma
+provider  String   // Which AI generated this
+createdAt DateTime // Original generation time
+updatedAt DateTime // Last regeneration
+```
+
+Helps debug issues and understand cache patterns.
+
+### 4. Implement Cache Warming
+
+Pre-generate common content:
+
+```typescript
+// Warm cache for popular chapters
+const popularChapters = [
+  { book: 'Genesis', chapter: 1 },
+  { book: 'John', chapter: 3 },
+  { book: 'Psalm', chapter: 23 }
+];
+
+for (const ref of popularChapters) {
+  await getChapterOutline(ref.book, ref.chapter);
+}
+```
+
+### 5. Monitor Cache Hit Rate
+
+```typescript
+// Track cache performance
+const cacheHitRate = await prisma.$queryRaw`
+  SELECT
+    COUNT(*) FILTER (WHERE cached = true) as hits,
+    COUNT(*) as total,
+    ROUND(COUNT(*) FILTER (WHERE cached = true)::numeric / COUNT(*) * 100, 2) as hit_rate
+  FROM request_logs;
+`;
+
+// Target: >80% cache hit rate
+```
+
+---
+
+## Common Mistakes to Avoid
+
+### ❌ Mistake 1: Using localStorage for AI responses
+
+```javascript
+// BAD: Lost on browser clear, not shared across devices
+localStorage.setItem('outline', JSON.stringify(outline));
+```
+
+**Fix:** Use database for permanent, cross-device storage.
+
+### ❌ Mistake 2: No unique constraints
+
+```prisma
+// BAD: Allows duplicate caching
+model CachedOutline {
+  bookName String
+  chapter  Int
+  outline  Json
+}
+```
+
+**Fix:** Add unique constraint to prevent duplicates.
+
+### ❌ Mistake 3: Not handling cache invalidation
+
+Users update content, but cache never refreshes.
+
+**Fix:** Implement `force=true` parameter or stale flag.
+
+### ❌ Mistake 4: Missing indexes
+
+Queries get slower as table grows.
+
+**Fix:** Add composite indexes on lookup columns.
+
+### ❌ Mistake 5: Caching errors
+
+```typescript
+// BAD: Cache API errors
+catch (err) {
+  await prisma.cache.create({ data: { error: err.message } });
+}
+```
+
+**Fix:** Only cache successful AI responses.
+
+---
+
+## Real-World Results
+
+### Ministry LLM Project (Feb 2026)
+
+**Before caching:**
+- Chapter outline load: 3-5 seconds
+- Knowledge graph generation: 15-30 seconds
+- Monthly AI API cost: ~$150 (projected)
+
+**After caching:**
+- Chapter outline load: 80-120ms (cached)
+- Knowledge graph: Instant (cached)
+- Monthly AI API cost: ~$25 (83% reduction)
+
+**User feedback:**
+> "It's so fast now! And my outlines don't disappear when I refresh."
+
+### Key Metrics
+
+| Metric | Before | After | Improvement |
+|--------|--------|-------|-------------|
+| Avg load time | 3.2s | 0.09s | **35x faster** |
+| Cache hit rate | 0% | 94% | N/A |
+| Monthly API cost | $150 | $25 | **83% savings** |
+| Data persistence | None | Forever | **∞% better** |
+
+---
+
+## Related Patterns
+
+- [API Response Caching Strategies](../patterns-standards/API_CACHING_STRATEGIES.md)
+- [PostgreSQL Performance Optimization](../database-solutions/POSTGRES_PERFORMANCE.md)
+- [Prisma ORM Best Practices](../database-solutions/PRISMA_BEST_PRACTICES.md)
+- [AI Provider Abstraction](../integrations/CONFIGURABLE_AI_PROVIDER_SELECTION.md)
+
+---
+
+## Resources
+
+- **Prisma JSON Fields:** https://www.prisma.io/docs/concepts/components/prisma-schema/data-model#json
+- **PostgreSQL JSONB:** https://www.postgresql.org/docs/current/datatype-json.html
+- **Cache Invalidation Strategies:** https://martinfowler.com/bliki/TwoHardThings.html
+- **Anthropic Claude Pricing:** https://www.anthropic.com/pricing
+- **Google Gemini Pricing:** https://ai.google.dev/pricing
+
+---
+
+## Time to Implement
+
+**30-60 minutes** for basic caching
+**2-3 hours** for production-ready implementation with monitoring
+
+## Difficulty Level
+
+⭐⭐⭐ (3/5) - Moderate
+
+**Easy parts:**
+- Prisma schema design
+- Basic cache check/save logic
+
+**Challenging parts:**
+- Cache invalidation strategy
+- Handling provider differences
+- Query performance optimization
+
+---
+
+## Author Notes
+
+This pattern saved us **$125/month** in the Ministry LLM project and improved user experience dramatically. The key insight: AI-generated content is **expensive data** - treat it like gold and persist it properly.
+
+**Most important lesson:** Users expect generated content to persist "forever". Database caching matches this mental model better than ephemeral caching (localStorage, Redis TTL).
+
+**When NOT to use this pattern:**
+- Real-time data that changes frequently
+- Personalized content that differs per user
+- Content with strict compliance requirements (may need audit trail)
+
+**When to definitely use this pattern:**
+- AI-generated summaries, outlines, analyses
+- Expensive API calls ($0.01+ per request)
+- Content users expect to persist
+- High read-to-write ratio (read 10x+ more than generate)
+
+---
+
+**Commits implementing this pattern:**
+- `9eddb68` - Persistent database caching for chapter outlines
+- `1d25867` - Database caching for bird's eye view
+- `7b4dbcd` - Configurable AI provider selection
+
+**Project:** Ministry LLM - AI-Powered Bible Study Platform
+**Date:** February 9, 2026
+**Impact:** 83% cost reduction, 35x faster load times

package/skills-library/database-solutions/CONDITIONAL_SQL_MIGRATION_PATTERN.md

@@ -0,0 +1,119 @@
+# Conditional SQL Migration Pattern - Idempotent Database Migrations
+
+## The Problem
+
+Running migrations multiple times causes errors or duplicates. Need migrations that can run safely whether or not the changes already exist.
+
+### Error Messages
+```
+ERROR: relation "table_name" already exists
+ERROR: column "column_name" of relation "table_name" already exists
+ERROR: duplicate key value violates unique constraint
+```
+
+---
+
+## The Solution
+
+### Pattern 1: CREATE TABLE IF NOT EXISTS
+
+```sql
+CREATE TABLE IF NOT EXISTS time_slots (
+    id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
+    code VARCHAR(50) UNIQUE NOT NULL,
+    display_name VARCHAR(100) NOT NULL,
+    is_active BOOLEAN DEFAULT TRUE,
+    created_at TIMESTAMPTZ DEFAULT NOW()
+);
+```
+
+### Pattern 2: ADD COLUMN IF NOT EXISTS
+
+```sql
+ALTER TABLE time_slots
+ADD COLUMN IF NOT EXISTS default_duration_minutes INTEGER DEFAULT 60;
+```
+
+### Pattern 3: INSERT Only If Empty (Seed Data)
+
+```sql
+INSERT INTO time_slots (code, display_name, typical_time, display_order)
+SELECT code, display_name, typical_time, display_order
+FROM (VALUES
+    ('morning', 'Morning Intimacy', '10:00 AM EST', 1),
+    ('noon', 'Noon Day', '1:00 PM - 4:00 PM', 2),
+    ('evening', 'Evening Incense', '7:30 PM EST', 3)
+) AS v(code, display_name, typical_time, display_order)
+WHERE NOT EXISTS (SELECT 1 FROM time_slots LIMIT 1);
+```
+
+### Pattern 4: UPSERT (Insert or Update)
+
+```sql
+INSERT INTO time_slots (code, display_name)
+VALUES ('morning', 'Morning Intimacy')
+ON CONFLICT (code) DO UPDATE SET display_name = EXCLUDED.display_name;
+```
+
+### Pattern 5: Conditional UPDATE
+
+```sql
+-- Only update if value is still the default
+UPDATE time_slots
+SET default_duration_minutes = 90
+WHERE code = 'morning' AND default_duration_minutes = 60;
+```
+
+### Pattern 6: DROP IF EXISTS
+
+```sql
+DROP TABLE IF EXISTS old_table;
+DROP INDEX IF EXISTS old_index;
+ALTER TABLE my_table DROP COLUMN IF EXISTS old_column;
+```
+
+---
+
+## Complete Migration Example
+
+```sql
+-- Migration: 075b_seed_time_slots.sql
+-- Idempotent: Safe to run multiple times
+
+-- 1. Ensure table exists
+CREATE TABLE IF NOT EXISTS time_slots (
+    id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
+    code VARCHAR(50) UNIQUE NOT NULL,
+    display_name VARCHAR(100) NOT NULL,
+    display_order INTEGER DEFAULT 0,
+    is_active BOOLEAN DEFAULT TRUE
+);
+
+-- 2. Seed only if empty
+INSERT INTO time_slots (code, display_name, display_order)
+SELECT * FROM (VALUES
+    ('morning', 'Morning', 1),
+    ('evening', 'Evening', 2)
+) AS v(code, display_name, display_order)
+WHERE NOT EXISTS (SELECT 1 FROM time_slots LIMIT 1);
+
+-- 3. Verify
+SELECT COUNT(*) as count FROM time_slots;
+```
+
+---
+
+## Key Rules
+
+1. Always use `IF NOT EXISTS` / `IF EXISTS` clauses
+2. Use `ON CONFLICT` for upserts instead of checking first
+3. For seed data, check if table is empty before inserting
+4. Add comments explaining the migration purpose
+
+## Difficulty Level
+⭐⭐ (2/5)
+
+---
+
+**Author Notes:**
+Idempotent migrations save hours of debugging. If a migration can run twice without error, deployment becomes much safer.