# Specification: 007-chat-module-integration

## Status

| Field | Value |
|-------|-------|
| **Created** | 2026-02-09 |
| **Current Phase** | Implementation Plan Reviewed - Ready for Implementation |
| **Last Updated** | 2026-02-09 |

## Documents

| Document | Status | Notes |
|----------|--------|-------|
| product-requirements.md | completed | 13 features defined (8 Must, 3 Should, 2 Could), 5 Won't Have |
| solution-design.md | completed (reviewed) | 5 ADRs, path dependency strategy, dedicated chat Dio, composite state pattern. Codex-reviewed 2026-02-09 |
| implementation-plan.md | completed (reviewed) | 8 phases, ~130 tasks, TDD structure, parallel workstreams in P5/P6. Codex-reviewed 2026-02-09 |

**Status values**: `pending` | `in_progress` | `completed` | `skipped`

## Decisions Log

| Date | Decision | Rationale |
|------|----------|-----------|
| 2026-02-09 | Mentions are store-scoped (not cross-store) | API only supports per-store mentions query. Cross-store aggregation deferred to future API enhancement |
| 2026-02-09 | Read receipts are channel-level only (not per-message "seen by") | Current API exposes unreadCount per channel, not per-message reader lists. Per-message read receipts deferred |
| 2026-02-09 | Ably connections are logically separate (chat vs push) but SDK multiplexes internally | Different token scopes, different lifecycles. Ably SDK shares underlying TCP connection — minimal overhead |

## SDD Review (Codex) - 2026-02-09

### Key Findings

| Category | Count | Details |
|----------|-------|---------|
| **Blockers** | 3 | Mentions scope conflict, ADR checklist inconsistency, Ably connection strategy conflict |
| **Important** | 4 | Channel sorting unspecified, read receipts underspecified, PRD features missing design detail, analytics mapping incomplete |
| **Enhancements** | 1 | Glossary alignment |

### Blockers Resolved

1. **Mentions scope conflict**: Clarified as store-scoped (API limitation). Added explicit note in SDD State Management section.
2. **ADR checklist inconsistency**: Fixed checklist to show ADRs as pending user confirmation (was incorrectly marked as confirmed).
3. **Ably connection conflict**: Reconciled PRD risk table with SDD ADR-5. Added note explaining SDK-level multiplexing.

### Important Items Resolved

1. **Channel list sorting**: Added full "Channel List Sorting and Update Strategy" algorithm — pinned order, recency sort, real-time update rules, display specs.
2. **Read receipts**: Added "Read Receipts Design" section — channel-level scope, debounce strategy, badge behavior, deferred per-message seen-by.
3. **PRD features with missing design detail**: Added 5 new "Feature Detail" sections covering Channel Management (F9), Message Search (F10), Sound Feedback (F12), Attachment Display (F13), and Reaction Limits (F5).
4. **Analytics mapping**: Added complete "Analytics Event Mapping" table — all 13 PRD events mapped to trigger locations with payload fields.

### Architectural Decisions Confirmed

- ADR-1: Path dependency (pending user confirmation)
- ADR-2: Dedicated chat Dio instance (pending user confirmation)
- ADR-3: Single ChatNotifier with composite state (pending user confirmation)
- ADR-4: Adapt screens, don't copy (pending user confirmation)
- ADR-5: Separate Ably connection (pending user confirmation, reconciled with PRD)

### Items Not Changed (Rejected/Deferred)

| Suggestion | Decision | Rationale |
|-----------|----------|-----------|
| Cross-store mentions aggregation | Deferred | Requires new API endpoint not in current contract |
| Per-message "seen by" read receipts | Deferred | Requires new API endpoint; channel-level unread tracking covers PRD acceptance criteria |

## Implementation Plan Review (Codex) - 2026-02-09

### Key Findings

| Category | Count | Details |
|----------|-------|---------|
| **Blockers** | 2 | Missing message send rate limit (30/min + 429 Retry-After), missing message cache cap (100/channel) |
| **Important** | 6 | Store-not-selected empty state, search jump-to-outside-cache, attachment deps, channel settings permissions, polling/resync verification, pin reorder support |
| **Enhancements** | 2 | Global risk section per phase, routing consolidation note |

### Blockers Resolved

1. **Message send rate limit**: Added T2.2.31-32 (ChatNotifier tests for 30/min client-side enforcement + 429 Retry-After countdown), T4.3.8 (UI test for "Slow down" message). Added rate limit tracking to ChatNotifier implementation spec.
2. **Message cache cap**: Added T2.2.33 (test 100-message cap triggers reload-from-point). Added cache cap logic to ChatNotifier implementation spec.

### Important Items Resolved

1. **Pin reorder**: Added T1.2.6-7 (preferences service tests for ordered list + sound pref). Pin order persisted as ordered ID list — drag-reorder UI deferred to future enhancement; static pin ordering via pin/unpin sequence.
2. **Store-not-selected empty state**: Added T3.2.14 (widget test for null chatTypeNumProvider).
3. **Search jump-to-outside-cache**: Added T5.2.2.6 (test for reload-from-point when message outside 100-message window).
4. **Attachment dependencies**: Added T6.2.1.3 (verify `cached_network_image`, `url_launcher`, `share_plus` in pubspec). Added T6.2.2.5-6 (download + share tests).
5. **Channel settings permissions**: Added T5.1.2.9-10 (creator/owner-only settings, default channel restrictions).
6. **Polling fallback + resync verification**: Added T2.2.34-35 (verify AblyRealtimeService handles polling internally, test needsResync flag). Added resync handler to ChatNotifier spec.

### Enhancements Added

1. **Risk section**: Added global "Implementation Risks" table referencing SDD risks per phase.
2. **Routing consolidation note**: Added note about incremental route changes across P3-P7 with commit-per-phase strategy.

### Items Not Changed (Rejected/Deferred)

| Suggestion | Decision | Rationale |
|-----------|----------|-----------|
| Drag-reorder UI for pinned channels | Deferred | Pin order tracked via ordered ID list. Pin/unpin sequence establishes order. Drag UI is a polish item for a future iteration. |

## Context

Import the complete Chat module from the BuyerKiosk Team app (`../buyerkiosk-team`) into the Live app. The Team app already has a shared package (`packages/buyerkiosk_chat/`) with models, entities, mappers, services, repository, and Ably real-time integration. The Live app needs to integrate this package and build the presentation layer (screens, widgets, providers) adapted to the Live app's navigation and auth system.

### Key Facts from Team App Analysis
- **Shared package**: `packages/buyerkiosk_chat/` - models, entities, services, repository, mappers
- **19 API endpoints** under `/mobile/staff-chat/{typeNum}/`
- **Ably real-time** for WebSocket messaging with polling fallback
- **JWT authentication** (Live app already has unified JWT auth)
- **25+ derived Riverpod providers** in Team app
- **13 screens/widgets** for full chat UI
- **904 tests** in Team app (40 dedicated chat tests)
- **Features**: Channels, messages, reactions, mentions, read receipts, typing indicators, attachments (display-only), pinning, muting, search

---
*This file is managed by the specification-management skill.*