docs(21-01): complete chat schema and shared types plan
- SUMMARY.md with accomplishments, commits, and deviation notes - STATE.md advanced to plan 2 of 6, 33% progress - ROADMAP.md updated with plan progress - REQUIREMENTS.md: marked HIST-01 and HIST-06 complete
This commit is contained in:
Nexus Dev
parent
a818abb004
commit
de24f5f5a1
4 changed files with 164 additions and 21 deletions
|
|
@ -49,12 +49,12 @@
|
|||
|
||||
### History & Persistence (6)
|
||||
|
||||
- [ ] **HIST-01** — All conversations persisted in libSQL
|
||||
- [x] **HIST-01** — All conversations persisted in libSQL
|
||||
- [ ] **HIST-02** — Conversation list in sidebar: sorted by most recent, searchable, filterable by agent
|
||||
- [ ] **HIST-03** — Infinite scroll in the conversation list sidebar
|
||||
- [ ] **HIST-04** — Conversation export: download as Markdown or JSON
|
||||
- [ ] **HIST-05** — Cross-device sync: conversations accessible from any device on the network via the Nexus server API
|
||||
- [ ] **HIST-06** — Chat history survives server restarts: no in-memory-only state
|
||||
- [x] **HIST-06** — Chat history survives server restarts: no in-memory-only state
|
||||
|
||||
### PWA & Mobile (8)
|
||||
|
||||
|
|
@ -146,12 +146,12 @@ The following are explicitly deferred:
|
|||
| AGENT-05 | Phase 23 | Pending |
|
||||
| AGENT-06 | Phase 23 | Pending |
|
||||
| AGENT-07 | Phase 23 | Pending |
|
||||
| HIST-01 | Phase 21 | Pending |
|
||||
| HIST-01 | Phase 21 | Complete |
|
||||
| HIST-02 | Phase 21 | Pending |
|
||||
| HIST-03 | Phase 21 | Pending |
|
||||
| HIST-04 | Phase 24 | Pending |
|
||||
| HIST-05 | Phase 21 | Pending |
|
||||
| HIST-06 | Phase 21 | Pending |
|
||||
| HIST-06 | Phase 21 | Complete |
|
||||
| PWA-01 | Phase 26 | Pending |
|
||||
| PWA-02 | Phase 26 | Pending |
|
||||
| PWA-03 | Phase 26 | Pending |
|
||||
|
|
|
|||
|
|
@ -31,11 +31,11 @@
|
|||
3. Agent messages render with full markdown: code blocks with syntax highlighting and a copy button, tables, lists, headings, links, and inline images
|
||||
4. Conversations and all messages are stored in libSQL and survive a server restart
|
||||
5. The chat interface applies Catppuccin Mocha, Tokyo Night, and Catppuccin Latte themes correctly; code block highlighting matches the active theme
|
||||
**Plans:** 6 plans
|
||||
**Plans:** 2/6 plans executed
|
||||
|
||||
Plans:
|
||||
- [ ] 21-00-PLAN.md — Wave 0 test stubs (chat-service, chat-routes, ChatMarkdownMessage, ChatInput)
|
||||
- [ ] 21-01-PLAN.md — DB schema (chat_conversations + chat_messages) and shared types/validators
|
||||
- [x] 21-00-PLAN.md — Wave 0 test stubs (chat-service, chat-routes, ChatMarkdownMessage, ChatInput)
|
||||
- [x] 21-01-PLAN.md — DB schema (chat_conversations + chat_messages) and shared types/validators
|
||||
- [ ] 21-02-PLAN.md — Markdown renderer with rehype-highlight, code block copy button, theme CSS
|
||||
- [ ] 21-03-PLAN.md — Server chat service and REST API routes (CRUD + pagination)
|
||||
- [ ] 21-04-PLAN.md — ChatPanel shell, ChatPanelContext, ChatInput, Layout integration
|
||||
|
|
@ -189,7 +189,7 @@ All 65 v1 requirements are mapped to exactly one phase. No orphans.
|
|||
|
||||
| Phase | Milestone | Plans Complete | Status | Completed |
|
||||
|-------|-----------|----------------|--------|-----------|
|
||||
| 21. Chat Foundation | v1.3 | 0/6 | Planned | - |
|
||||
| 21. Chat Foundation | v1.3 | 2/6 | In Progress| |
|
||||
| 22. Agent Streaming | v1.3 | 0/? | Not started | - |
|
||||
| 23. Brainstormer Flow | v1.3 | 0/? | Not started | - |
|
||||
| 24. Search, History & Branching | v1.3 | 0/? | Not started | - |
|
||||
|
|
|
|||
|
|
@ -1,16 +1,16 @@
|
|||
---
|
||||
gsd_state_version: 1.0
|
||||
milestone: v1.3
|
||||
milestone_name: Web Chat Interface
|
||||
status: roadmap_defined
|
||||
stopped_at: Activated v1.3 from milestone queue — ready to plan Phase 21
|
||||
last_updated: "2026-04-01T14:00:00.000Z"
|
||||
milestone_name: milestone
|
||||
status: executing
|
||||
stopped_at: Completed 21-chat-foundation-21-00-PLAN.md
|
||||
last_updated: "2026-04-01T16:39:05.467Z"
|
||||
last_activity: 2026-04-01
|
||||
progress:
|
||||
total_phases: 6
|
||||
completed_phases: 0
|
||||
total_plans: 0
|
||||
completed_plans: 0
|
||||
total_plans: 6
|
||||
completed_plans: 2
|
||||
percent: 0
|
||||
---
|
||||
|
||||
|
|
@ -21,18 +21,19 @@ progress:
|
|||
See: .planning/PROJECT.md (updated 2026-03-30)
|
||||
|
||||
**Core value:** Fresh onboard asks for ONE thing (root directory), auto-creates PM + Engineer, drops you in dashboard — no corporate language anywhere.
|
||||
**Current focus:** v1.3 Web Chat Interface — ready to plan Phase 21
|
||||
**Current focus:** Phase 21 — chat-foundation
|
||||
|
||||
## Current Position
|
||||
|
||||
Phase: 21 of 26 (Chat Foundation)
|
||||
Plan: — (not yet planned)
|
||||
Status: Ready to plan
|
||||
Last activity: 2026-04-01 — upstream rebase verified (0 behind, build OK)
|
||||
Phase: 21 (chat-foundation) — EXECUTING
|
||||
Plan: 3 of 6
|
||||
Status: Ready to execute
|
||||
Last activity: 2026-04-01
|
||||
|
||||
Progress: [░░░░░░░░░░] 0%
|
||||
|
||||
### Upstream Rebase Log
|
||||
|
||||
| Date | Commits Behind | Conflicts | Build | Notes |
|
||||
|------|---------------|-----------|-------|-------|
|
||||
| 2026-04-01 | 0 | 0 | OK | Already rebased from 120+ commits session; upstream hasn't moved |
|
||||
|
|
@ -58,6 +59,8 @@ Progress: [░░░░░░░░░░] 0%
|
|||
|
||||
*Updated after each plan completion*
|
||||
| Phase 01-foundation P01 | 2 | 2 tasks | 7 files |
|
||||
| Phase 21-chat-foundation P01 | 2 | 2 tasks | 8 files |
|
||||
| Phase 21-chat-foundation P00 | 2 | 2 tasks | 4 files |
|
||||
|
||||
## Accumulated Context
|
||||
|
||||
|
|
@ -75,6 +78,9 @@ Recent decisions affecting current work:
|
|||
- [Phase 01-foundation]: Use as const for VOCAB to enable TypeScript literal type inference on all values
|
||||
- [Phase 01-foundation]: Hook source tracked in scripts/nexus-commit-msg-hook.sh for post-clone reinstallation
|
||||
- [Phase 01-foundation]: rerere.autoupdate=true so resolved conflicts are auto-staged during future rebases
|
||||
- [Phase 21-chat-foundation]: Used object-syntax (table) => ({}) for Drizzle index callbacks to match existing codebase convention in documents.ts, agents.ts
|
||||
- [Phase 21-chat-foundation]: Use it.todo() (not it.skip()) for Wave 0 test scaffolding — vitest marks todos semantically, no false positives
|
||||
- [Phase 21-chat-foundation]: Minimal imports in test stubs — no service mocks until Plans 01-05 wire up implementations
|
||||
|
||||
### Pending Todos
|
||||
|
||||
|
|
@ -87,6 +93,6 @@ None yet.
|
|||
|
||||
## Session Continuity
|
||||
|
||||
Last session: 2026-03-30T20:37:04.573Z
|
||||
Stopped at: Completed 01-foundation/01-02-PLAN.md
|
||||
Last session: 2026-04-01T16:39:05.464Z
|
||||
Stopped at: Completed 21-chat-foundation-21-00-PLAN.md
|
||||
Resume file: None
|
||||
|
|
|
|||
137
.planning/phases/21-chat-foundation/21-01-SUMMARY.md
Normal file
137
.planning/phases/21-chat-foundation/21-01-SUMMARY.md
Normal file
|
|
@ -0,0 +1,137 @@
|
|||
---
|
||||
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*
|
||||
Loading…
Add table
Reference in a new issue