feat: Phase 2 - Add TimescaleDB optimizations to Prisma schema

- Add comprehensive TimescaleDB documentation to AgentEvent model
- Replace single-column indexes with composite indexes for better performance
  - sessionId + timestamp (DESC) for session timeline queries
  - projectId + timestamp (DESC) for project timeline queries
- Add GIN index for JSONB data field queries
- Add inline comments explaining purpose of each index
- Create migration for index changes
- Add Phase 2 implementation documentation

Co-authored-by: tikazyq <[email protected]>

Author: Copilot

prisma/migrations/20251101000000_add_timescaledb_composite_indexes/migration.sql

@@ -0,0 +1,31 @@
+-- Migration: Add TimescaleDB-optimized composite indexes for agent_events
+-- Phase 2 of Database Architecture Specification (specs/20251031/001-database-architecture)
+--
+-- This migration adds composite indexes for optimal TimescaleDB query performance:
+-- 1. session_id + timestamp (DESC) - for session timeline queries
+-- 2. project_id + timestamp (DESC) - for project timeline queries
+-- 3. GIN index on data JSONB field - for flexible JSON queries
+--
+-- These indexes complement the existing single-column indexes and improve
+-- performance for time-range queries filtered by session or project.
+
+-- Drop existing single-column indexes that will be replaced by composite indexes
+DROP INDEX IF EXISTS "agent_events_session_id_idx";
+DROP INDEX IF EXISTS "agent_events_project_id_idx";
+
+-- Create composite index for session timeline queries
+-- Optimizes: SELECT * FROM agent_events WHERE session_id = ? AND timestamp > ?
+CREATE INDEX "agent_events_session_id_timestamp_idx" ON "agent_events"("session_id", "timestamp" DESC);
+
+-- Create composite index for project timeline queries
+-- Optimizes: SELECT * FROM agent_events WHERE project_id = ? AND timestamp > ?
+CREATE INDEX "agent_events_project_id_timestamp_idx" ON "agent_events"("project_id", "timestamp" DESC);
+
+-- Create GIN index for JSONB data field
+-- Optimizes: SELECT * FROM agent_events WHERE data @> '{"key": "value"}'::jsonb
+CREATE INDEX "agent_events_data_idx" ON "agent_events" USING GIN ("data");
+
+-- Note: The `data` field uses the default GIN operator class (jsonb_ops),
+-- which supports containment queries (@>, @?, etc.) but uses more storage.
+-- Alternative: jsonb_path_ops uses less storage but only supports @> operator.
+-- The default is chosen for maximum query flexibility.

prisma/schema.prisma

@@ -303,6 +303,20 @@ model ChatMessage {
 // ============================================================================
 
 // Agent Events - Individual actions (TimescaleDB hypertable)
+//
+// NOTE: This table is converted to a TimescaleDB hypertable for time-series optimization.
+// The conversion is performed by scripts/enable-timescaledb.sql which:
+// - Creates a hypertable partitioned by timestamp (1-day chunks)
+// - Enables compression after 7 days (70-90% storage reduction)
+// - Sets up automatic retention policy (1 year)
+// - Creates continuous aggregates for hourly and daily statistics
+//
+// Performance characteristics:
+// - Write throughput: 50-100K events/sec
+// - Query latency: 30-50ms P95 for time-range queries
+// - Storage: 200-500 bytes per event after compression
+//
+// See: specs/20251031/001-database-architecture/README.md for details
 model AgentEvent {
   id           String   @id @default(uuid()) @db.Uuid
   timestamp    DateTime @db.Timestamptz
@@ -333,13 +347,15 @@ model AgentEvent {
   session ChatSession @relation(fields: [sessionId], references: [sessionId], onDelete: Cascade)
   project Project     @relation(fields: [projectId], references: [id], onDelete: Cascade)
 
-  @@index([timestamp(sort: Desc)])
-  @@index([sessionId])
-  @@index([agentId])
-  @@index([eventType])
-  @@index([projectId])
-  @@index([tags])
-  @@index([severity])
+  // Indexes optimized for TimescaleDB time-series queries
+  @@index([timestamp(sort: Desc)]) // Primary time-series index
+  @@index([sessionId, timestamp(sort: Desc)]) // Session timeline queries (composite)
+  @@index([projectId, timestamp(sort: Desc)]) // Project timeline queries (composite)
+  @@index([agentId]) // Filter by agent type
+  @@index([eventType]) // Filter by event type
+  @@index([tags]) // Array index for tag filtering
+  @@index([severity]) // Filter by severity level
+  @@index([data]) // GIN index for JSONB field queries (created in migration)
   @@map("agent_events")
 }