---
phase: 21-chat-foundation
plan: "01"
subsystem: database
tags: [drizzle, postgres, zod, typescript, schema, migration]

# Dependency graph
requires: []
provides:
  - chatConversations Drizzle table (packages/db/src/schema/chat_conversations.ts)
  - chatMessages Drizzle table (packages/db/src/schema/chat_messages.ts)
  - Migration SQL 0047_nebulous_klaw.sql with full DDL, FK constraints, and indexes
  - ChatConversation, ChatConversationListItem, ChatMessage TypeScript interfaces
  - createConversationSchema, updateConversationSchema, createMessageSchema Zod validators
  - All types/validators re-exported from @paperclipai/shared barrel files
affects: [21-02, 21-03, 21-04, 21-05, 21-06]

# Tech tracking
tech-stack:
  added: []
  patterns:
    - "Drizzle pgTable with object-syntax index callback (table) => ({...}) — matches existing codebase convention"
    - "Shared types as TypeScript interfaces with string timestamps (not Date objects)"
    - "Zod validators with type exports in same validators file"

key-files:
  created:
    - packages/db/src/schema/chat_conversations.ts
    - packages/db/src/schema/chat_messages.ts
    - packages/db/src/migrations/0047_nebulous_klaw.sql
    - packages/shared/src/types/chat.ts
    - packages/shared/src/validators/chat.ts
  modified:
    - packages/db/src/schema/index.ts
    - packages/shared/src/types/index.ts
    - packages/shared/src/validators/index.ts

key-decisions:
  - "Used object-syntax (table) => ({...}) for Drizzle index callbacks — matches documents.ts, agents.ts pattern (plan suggested array syntax but existing code uses object syntax)"
  - "Added TypeScript infer types (CreateConversation, UpdateConversation, CreateMessage) to validators file for completeness"

patterns-established:
  - "Chat schema tables follow same FK pattern as documents.ts (companyId FK, agentId FK with set null)"
  - "chatMessages uses onDelete: cascade for FK to chatConversations — messages are child records"

requirements-completed: [HIST-01, HIST-06]

# Metrics
duration: 2min
completed: 2026-04-01
---

# Phase 21 Plan 01: Chat Foundation — Database Schema and Shared Types Summary

**Two Drizzle tables (chat_conversations, chat_messages) with migration SQL, plus TypeScript interfaces and Zod validators exported from @paperclipai/shared**

## Performance

- **Duration:** 2 min
- **Started:** 2026-04-01T16:36:03Z
- **Completed:** 2026-04-01T16:38:38Z
- **Tasks:** 2
- **Files modified:** 8

## Accomplishments

- Created chatConversations Drizzle table with companyId FK, optional agentId FK (set null on delete), pinned/archived/deleted timestamp columns, and two composite indexes
- Created chatMessages Drizzle table with conversationId FK (cascade delete), role/content text columns, and conversation+createdAt index
- Generated migration 0047_nebulous_klaw.sql containing correct DDL, FK constraints, and indexes
- Created shared TypeScript interfaces (ChatConversation, ChatConversationListItem, ChatMessage, list response types) in @paperclipai/shared
- Created Zod validators (createConversationSchema, updateConversationSchema, createMessageSchema) with inferred types

## Task Commits

Each task was committed atomically:

1. **Task 1: Create Drizzle schema files and generate migration** - `9d45d01b` (feat)
2. **Task 2: Create shared types and Zod validators for chat** - `075de0df` (feat)

**Plan metadata:** (docs commit — see below)

## Files Created/Modified

- `packages/db/src/schema/chat_conversations.ts` - chatConversations Drizzle table definition
- `packages/db/src/schema/chat_messages.ts` - chatMessages Drizzle table definition with cascade FK
- `packages/db/src/migrations/0047_nebulous_klaw.sql` - Generated migration SQL with full DDL
- `packages/db/src/schema/index.ts` - Added chatConversations and chatMessages exports
- `packages/shared/src/types/chat.ts` - ChatConversation, ChatConversationListItem, ChatMessage, list response interfaces
- `packages/shared/src/validators/chat.ts` - createConversationSchema, updateConversationSchema, createMessageSchema validators
- `packages/shared/src/types/index.ts` - Added export * from "./chat.js"
- `packages/shared/src/validators/index.ts` - Added export * from "./chat.js"

## Decisions Made

- Used object-syntax `(table) => ({...})` for Drizzle index callbacks — the plan suggested array syntax but the existing codebase (documents.ts, agents.ts, companies.ts) consistently uses object syntax. Matched existing convention.
- Added `CreateConversation`, `UpdateConversation`, `CreateMessage` inferred types to validators file — follows the pattern established in company.ts and other validators.

## Deviations from Plan

### Minor Adaptation

**1. [Rule 1 - Convention] Used object index syntax instead of array syntax in Drizzle tables**
- **Found during:** Task 1 (Create Drizzle schema files)
- **Issue:** Plan suggested `(table) => [index(...)]` array syntax, but all existing schema files (documents.ts, agents.ts, companies.ts) use `(table) => ({...})` object syntax
- **Fix:** Used object syntax to match codebase convention — functionally identical, just different notation
- **Files modified:** packages/db/src/schema/chat_conversations.ts, packages/db/src/schema/chat_messages.ts
- **Verification:** Migration generated successfully with correct indexes

**2. [Minor] Migration uses lowercase `cascade` keyword**
- **Found during:** Task 1 verification
- **Issue:** Drizzle generates `ON DELETE cascade` (lowercase) in SQL; plan acceptance criteria said `ON DELETE CASCADE` (uppercase)
- **Fix:** No fix needed — SQL keywords are case-insensitive; this is Drizzle's standard output
- **Impact:** None — migration is functionally correct

---

**Total deviations:** 2 minor adaptations
**Impact on plan:** Both are cosmetic/style differences with no functional impact. Plan executed as specified.

## Issues Encountered

None — both tasks executed cleanly.

## User Setup Required

None — no external service configuration required. Migration runs automatically at server start via `pnpm db:migrate`.

## Next Phase Readiness

- Database schema and shared types are ready for Plan 02 (chat API routes)
- Both tables will be created on next server start via migration
- Types and validators are importable from `@paperclipai/shared` for use in server routes and UI
- No blockers for subsequent plans

---
*Phase: 21-chat-foundation*
*Completed: 2026-04-01*