---
phase: 24-search-history-branching
plan: "01"
subsystem: api
tags: [postgres, drizzle-orm, tsvector, fts, express, bookmarks, branching, export]

requires:
  - phase: 24-00
    provides: "DB schema for chat_message_bookmarks, parentConversationId/branchFromMessageId in chatConversations, content_search tsvector column, searchMessagesSchema/branchConversationSchema validators, ChatMessageSearchResult/ChatBookmark types"

provides:
  - "searchMessages: tsvector FTS with ts_rank ranking, company-scoped via conversation join"
  - "toggleBookmark: transactional insert-or-delete bookmark"
  - "getBookmarks: paginated bookmarks with message and conversation join"
  - "branchConversation: copies messages up to branch point into new child conversation"
  - "listBranches: queries child conversations by parentConversationId"
  - "exportConversation: Markdown and JSON export with agent name resolution"
  - "Six Express route handlers: search, bookmark toggle, bookmark list, branch create, branch list, export download"

affects:
  - "24-02 (UI hooks and API client wiring)"
  - "24-03 (UI components for search/bookmark/branch)"

tech-stack:
  added: []
  patterns:
    - "chatService(db) factory extended with new methods — same pattern as existing listConversations, addMessage"
    - "tsvector FTS via raw sql`` template — content_search column is Postgres-generated stored, not in Drizzle schema"
    - "Export route sets Content-Disposition + Content-Type headers, uses res.send(content)"
    - "Transaction for bookmark toggle ensures atomicity of read-then-write"

key-files:
  created: []
  modified:
    - "server/src/services/chat.ts"
    - "server/src/routes/chat.ts"

key-decisions:
  - "Used this.getConversation() reference in exportConversation to reuse existing notFound guard — avoids duplicate query logic"
  - "searchMessages returns early with empty items when query is blank after trim — avoids FTS error on empty tsquery"

patterns-established:
  - "Pattern: LEFT JOIN agents ON chatMessages.agentId = agents.id for agent name resolution in export"
  - "Pattern: branchConversation uses lte(createdAt) to include branch point message in copy"

requirements-completed:
  - CHAT-07
  - CHAT-13
  - CHAT-14
  - HIST-04
  - HIST-09
  - HIST-10
  - HIST-11
  - PERF-04

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

# Phase 24 Plan 01: Search, Bookmarks, Branching, and Export Service + Routes Summary

**Six service methods and six route handlers for full-text search (tsvector/ts_rank), bookmark toggle/list, conversation branching with message copy, and Markdown/JSON export with agent name resolution**

## Performance

- **Duration:** 12 min
- **Started:** 2026-04-01T22:30:00Z
- **Completed:** 2026-04-01T22:42:00Z
- **Tasks:** 2
- **Files modified:** 2

## Accomplishments

- searchMessages uses tsvector FTS with `plainto_tsquery` and `ts_rank` ordering, company-scoped via inner join to chatConversations
- toggleBookmark runs in a transaction: checks for existing bookmark then either deletes (returns bookmarked: false) or inserts (returns bookmarked: true)
- getBookmarks joins bookmarks with messages and conversations, returning full ChatBookmarkWithMessage shape
- branchConversation copies all messages up to and including the branch point into a new child conversation with parentConversationId and branchFromMessageId set
- listBranches queries chatConversations by parentConversationId with deletedAt IS NULL guard
- exportConversation LEFT JOINs agents for name resolution; user messages use "You" as speaker; Markdown and JSON formats with sanitized filename slug
- All six route handlers use assertBoard guard; search validates with ZodError 400 response; export sets Content-Disposition and Content-Type headers

## Task Commits

1. **Task 1: Service methods** - `5170fc3e` (feat)
2. **Task 2: Express routes** - `9f9c9e32` (feat)

## Files Created/Modified

- `server/src/services/chat.ts` - Added 6 service methods: searchMessages, toggleBookmark, getBookmarks, branchConversation, listBranches, exportConversation
- `server/src/routes/chat.ts` - Added 6 route handlers: message search, bookmark toggle, bookmark list, branch create, branch list, export download

## Decisions Made

- Used `this.getConversation()` inside `exportConversation` to reuse the existing notFound guard without duplicating query logic
- `searchMessages` returns early with `{ items: [] }` when `query.trim()` is empty to avoid PostgreSQL error on an empty tsquery
- `branchConversation` uses `lte(chatMessages.createdAt, branchMsg.createdAt)` so the branch point message itself is included in the copy

## Deviations from Plan

None - plan executed exactly as written.

## Issues Encountered

Pre-existing TypeScript errors in `server/src/services/plugin-host-services.ts` and plugin-related files caused the full `tsc` build to report failures, but these are unrelated to this plan's scope. Verified with targeted `tsc --noEmit | grep chat` — no errors in chat files.

## User Setup Required

None - no external service configuration required.

## Next Phase Readiness

- All six service methods and route handlers are implemented and TypeScript-clean
- API client and React Query hooks (Plan 24-02) can wire against these endpoints
- UI components (Plan 24-03) can consume the hooks built in 24-02

---
*Phase: 24-search-history-branching*
*Completed: 2026-04-01*