---
phase: 21-chat-foundation
plan: 03
subsystem: api
tags: [express, drizzle-orm, postgres, rest-api, chat, cursor-pagination, soft-delete]

requires:
  - phase: 21-chat-foundation/21-01
    provides: chat_conversations and chat_messages Drizzle schema tables

provides:
  - chatService factory with 7 CRUD methods (createConversation, listConversations, getConversation, updateConversation, softDeleteConversation, listMessages, addMessage)
  - chatRoutes factory with 7 REST endpoints mounted on Express app
  - Chat schema validators exported from @paperclipai/shared

affects:
  - 21-04 (chat panel UI needs these REST endpoints)
  - 21-05 (conversation list sidebar uses listConversations pagination)
  - 22+ (agent integration adds messages via addMessage)

tech-stack:
  added: []
  patterns:
    - "chatService(db) factory pattern matching documentService, activityService conventions"
    - "cursor-based pagination using limit+1 trick with hasMore boolean"
    - "soft-delete via deletedAt IS NULL filter in WHERE clause"
    - "auto-title idempotency: WHERE title IS NULL guard on UPDATE"

key-files:
  created:
    - server/src/services/chat.ts
    - server/src/routes/chat.ts
    - server/src/__tests__/chat-service.test.ts (replaced stubs)
    - server/src/__tests__/chat-routes.test.ts (replaced stubs)
  modified:
    - server/src/app.ts
    - packages/shared/src/index.ts

key-decisions:
  - "Pitfall 3 (updatedAt bump): addMessage always updates chatConversations.updatedAt after inserting — ensures conversation list sort order stays correct"
  - "Pitfall 5 (auto-title idempotency): WHERE title IS NULL guard makes auto-title set safe to call multiple times"
  - "Missing export fix: createConversationSchema/updateConversationSchema/createMessageSchema were in validators/chat.ts but not re-exported from shared/src/index.ts"

patterns-established:
  - "Route factory pattern: function chatRoutes(db: Db): Router"
  - "Service factory pattern: function chatService(db: Db) returning methods object"
  - "Cursor pagination: fetch limit+1, slice to limit, set hasMore=true if extra row found"

requirements-completed: [CHAT-04, CHAT-05, CHAT-06, HIST-05]

duration: 6min
completed: 2026-04-01
---

# Phase 21 Plan 03: Chat Service and REST API Summary

**Express REST API for conversation+message CRUD with cursor pagination, soft-delete, auto-title, and updatedAt bumping**

## Performance

- **Duration:** ~6 min
- **Started:** 2026-04-01T16:46:00Z
- **Completed:** 2026-04-01T16:52:30Z
- **Tasks:** 2
- **Files modified:** 6

## Accomplishments

- `chatService` factory with 7 methods covering full conversation lifecycle and message CRUD
- `chatRoutes` factory with 7 REST endpoints gated by `assertBoard`/`assertCompanyAccess`
- Routes mounted in `app.ts` as `api.use(chatRoutes(db))`
- 32 vitest tests passing (21 service, 11 route)

## Task Commits

1. **Task 1: Create chat service** - `4c344d46` (feat)
2. **Task 2: Create chat routes and mount in app.ts** - `563442e5` (feat)

## Files Created/Modified

- `server/src/services/chat.ts` - chatService factory with 7 CRUD methods
- `server/src/routes/chat.ts` - chatRoutes factory with 7 REST endpoints
- `server/src/__tests__/chat-service.test.ts` - 21 unit tests for chatService
- `server/src/__tests__/chat-routes.test.ts` - 11 integration tests for chatRoutes
- `server/src/app.ts` - Added chatRoutes import and `api.use(chatRoutes(db))`
- `packages/shared/src/index.ts` - Added chat schema exports

## Decisions Made

- Cursor pagination uses `limit+1` fetch pattern with `hasMore` boolean and `nextCursor` ISO string
- `listConversations` default limit 30/max 100; `listMessages` default limit 50/max 200
- Auto-title: `content.slice(0, 60)` with `WHERE title IS NULL` guard (idempotent)
- `updateConversation` accepts `pinnedAt`/`archivedAt` as ISO strings and converts to Date objects

## Deviations from Plan

### Auto-fixed Issues

**1. [Rule 2 - Missing Critical] Chat validator schemas not exported from @paperclipai/shared**
- **Found during:** Task 2 (chat-routes.test.ts returning 500 on POST routes)
- **Issue:** `createConversationSchema`, `updateConversationSchema`, and `createMessageSchema` existed in `packages/shared/src/validators/chat.ts` and were re-exported from `validators/index.ts` but were missing from the main `packages/shared/src/index.ts`. Any import of these from `@paperclipai/shared` would silently fail at runtime.
- **Fix:** Added explicit named exports for all three schemas and their types to `packages/shared/src/index.ts`
- **Files modified:** `packages/shared/src/index.ts`
- **Verification:** Tests pass; no TypeScript errors in shared package
- **Committed in:** `563442e5` (Task 2 commit)

---

**Total deviations:** 1 auto-fixed (1 missing critical export)
**Impact on plan:** Critical fix — without this, all POST/PATCH chat routes would throw runtime errors in production. No scope creep.

## Issues Encountered

None beyond the auto-fixed deviation above.

## User Setup Required

None — no external service configuration required.

## Next Phase Readiness

- Chat REST API fully operational; UI in Plan 04 can consume these endpoints
- Conversation and message CRUD all working with proper auth gates
- Pagination pattern established for Plan 05 (infinite scroll sidebar)
- No blockers

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