UI Feedback Session¶

Date: 2025-12-27 Time: 17:13 EST Reviewer: Don McCarty Session Focus: Comprehensive UI review across all major pages

Global Issues¶

GLOB-001: Supported File Types Communication¶

Issue: Users are not informed which document types are supported before attempting upload. Current State: Error only shown after rejected upload attempt. Recommendation: Display supported file types in every upload scenario: - In drag-drop zones: "Drop PDF, images, Word, Excel, or CSV files here" - In file picker accept attribute (already implemented) - In upload error messages (already implemented) - Consider a small "?" icon near upload areas with tooltip listing all supported types

Supported Types: PDF, JPG, JPEG, PNG, GIF, WEBP, DOC, DOCX, XLS, XLSX, CSV, TXT

Test Required: Yes - verify file type hints appear in all upload scenarios

GLOB-002: Icon Tooltips Standard¶

Issue: Many icons lack hover tooltips explaining their function. Recommendation: Establish standard that ALL icons must have descriptive tooltips. Affected Areas: - Sidebar icons (when collapsed) - Document status icons (green checkmark = "Processed") - Action icons throughout the system - KPI cards on dashboard

Test Required: Yes - audit all icons for tooltip presence

GLOB-003: "Coming Soon" Pattern¶

Issue: Need consistent pattern for disabled/future features. Recommendation: Create a standard "Coming Soon" indicator: - Grey out the control - Add a small clock or calendar icon - Tooltip on hover: "Coming Soon in a future release" - Use consistently across: Send Portal Invite, Create Engagement Letter, Send Welcome Email

Test Required: Yes - verify consistent Coming Soon pattern

GLOB-004: Centralized Icon Component Library¶

Issue: Icons may be implemented inconsistently across pages, leading to bugs. Recommendation: Create centralized icon components in @tax-practice/ui:

packages/ui/src/components/icons/
  - StatusIcon.tsx (processed, pending, error states)
  - ActionIcon.tsx (edit, delete, view, upload, move)
  - DocumentTypeIcon.tsx (PDF, Word, Excel, etc.)

This ensures consistent behavior and easier bug fixes.

Best Practice: Yes - component libraries should centralize repeated UI elements.

GLOB-005: Document Status Terminology¶

Issue: "Processed" badge appears immediately on upload, but nothing has been processed yet. Current Meaning: File successfully stored Recommended Terminology: - uploaded or stored - File received and stored - processing - AI/OCR extraction in progress - processed - Data extracted and verified - review_needed - Anomalies detected - verified - Human reviewed and confirmed

Scope: Database schema, API responses, all UI displays

Test Required: Yes - verify correct status terminology throughout

GLOB-006: Non-Displayable Document Handling¶

Issue: DOCX, XLSX files trigger download instead of preview. Need consistent UX. Recommendation: For non-viewable documents: 1. Show placeholder in viewer: "Preview not available for [filename]" 2. Offer Download button 3. Consider adding viewers for common formats: - DOCX: Use mammoth.js or similar - XLSX: Use SheetJS/xlsx library - TXT: Already viewable 4. Add pop-out icon for all viewable documents to open in new window

Test Required: Yes - verify all document types handled gracefully

Dashboard Page¶

URL: http://localhost:3001/

DASH-001: Clickable KPI Cards¶

Issue: KPI cards are static; could provide quick filtering. Recommendation: Make KPI cards clickable filters: - Click "Total Clients" → Show all clients (same as current) - Click "Returns in Progress" → Filter to clients with active returns - Click "Pending Actions" → Filter to clients needing attention - Visual indicator when filter active (highlighted border, "Filtered by: X" label) - Click again to deactivate filter - Title changes: "Recent Clients" → "Clients: [Filter Name]"

Workflow Enhancement: This reduces clicks to find relevant clients from 3+ to 1.

Test Required: Yes - add KPI filter interaction tests

DASH-002: View Button Icon¶

Issue: "View" text button could be an icon for cleaner UI. Recommendation: Replace with eye icon (lucide-react: Eye or ExternalLink) Tooltip: "View client details"

Test Required: Yes - verify icon and tooltip

DASH-003: Additional Client Actions¶

Issue: Is "View" the only relevant action? Analysis: For a dashboard quick-access list, additional options could include: - Quick call (phone icon) - if phone number exists - Quick email (mail icon) - if email exists - Create new return (plus icon)

Recommendation: Keep dashboard simple with just View. Additional actions belong on ClientDetailPage.

DASH-004: Column Widths¶

Issue: Acct # too narrow, Email too wide, Phone too narrow. Recommendation: Adjust column proportions: - Account #: Increase from ~10% to ~15% - Email: Decrease from ~25% to ~20% - Phone: Increase to accommodate full phone numbers with formatting

Test Required: Yes - verify column content not truncated

DASH-005: Status Filters¶

Test Required: Yes - add status filter tests (currently no search tests exist)

Issue: When sidebar collapsed, icons have no labels. Recommendation: Add tooltips to all sidebar icons when collapsed: - Dashboard, Clients, Queue, Settings, etc.

Test Required: Yes - verify sidebar tooltip behavior

New Client Page¶

URL: http://localhost:3001/clients/new

NEW-001: Welcome Email Coming Soon¶

Issue: "Send welcome email" checkbox enabled but feature not implemented. Recommendation: - Grey out checkbox - Add Coming Soon indicator (per GLOB-003) - Tooltip: "Portal access coming in a future release"

Test Required: Yes - verify disabled state and tooltip

NEW-002: Request Failed Error¶

Issue: Filling out all fields and clicking Create results in "Request Failed". Root Cause: Need to investigate API call - likely validation or DB issue. Priority: HIGH - blocks core functionality

Test Required: Yes - add create client success/failure tests

Client Detail Page¶

URL: http://localhost:3001/clients/:clientId

CLI-001: Edit Icons Location¶

Issue: Edit Client button in Actions card; should be inline with content. Recommendation: - Add pencil icon next to "Contact Information" header - Add pencil icon next to "Account Details" header - Remove separate "Edit Client" button from Actions - Follow UI pattern: edit controls near content they modify

Test Required: Yes - verify edit icon placement and function

CLI-002: Action Icon Placement¶

Issue: If using icons, should they be left of client name? Analysis: Power users benefit from consistent icon positions on the left (eyes track left-to-right). Recommendation: For return list rows: - Left side: Status icon, Action icons (Open, Upload, Delete) - Right side: Metadata (date, doc count)

CLI-003: Consistent Icon Actions¶

Issue: Upload is icon, Open is text - inconsistent. Recommendation: Standardize all actions as icons with tooltips: - Open/View: Eye icon - Upload: Upload icon - Delete: Trash icon - Edit: Pencil icon

Apply this standard across entire application.

Test Required: Yes - verify consistent icon usage

CLI-004: Edit Dialog Save Button¶

Issue: Save Changes button does nothing after editing phone number. Priority: HIGH - core functionality broken

Test Required: Yes - add edit client save tests

CLI-005: Email/Phone Hyperlinks¶

Issue: Email and phone appear as links but do nothing. Expected Behavior: - Email: mailto: link to open email client - Phone: tel: link (useful on mobile, optional on desktop)

Recommendation: Implement proper mailto: and tel: links. On desktop, phone can optionally be plain text or copy-to-clipboard.

Test Required: Yes - verify hyperlink behavior

CLI-006: Coming Soon Actions¶

Issue: Send Portal Invite, Create Engagement Letter need Coming Soon treatment. Recommendation: Apply GLOB-003 pattern

Analysis Dashboard Page¶

URL: http://localhost:3001/returns/:returnId/analysis

RET-001: Responsive Panel Sizing¶

Issue: Chat window and viewer don't shrink with browser; document list does. Recommendation: - All panels should respect minimum widths - Below breakpoint: collapse to single-panel view with tab navigation - Document action icons: collapse to "..." overflow menu when space constrained

UI Best Practice: Material Design recommends overflow menus when horizontal space insufficient for all actions.

Test Required: Yes - add responsive layout tests

RET-002: Panel Toggle Download Bug¶

Issue: Collapsing/expanding document viewer triggers download of first document. Root Cause: Same as previous auto-download bug - non-displayable file selected. Action Required: COMPREHENSIVE FIX - audit ALL code paths that set selectedDocId: - Initial page load - Panel toggle - Document deletion - Document upload - Navigation to page - Query refetch

Must ensure isDisplayable() check applied everywhere.

Test Required: Yes - add panel toggle tests

Issue: Green checkmark has no tooltip. Recommendation: Add tooltip: "Processed" (or appropriate status per GLOB-005)

Test Required: Yes - included in GLOB-002 audit

RET-004: Delete Dialog Document Name¶

Issue: Dialog says "this document" instead of filename. Recommendation: "Are you sure you want to delete '[filename]'?"

Test Required: Yes - verify delete dialog content

RET-005: Upload Rejection Feedback¶

Issue: SQL file rejected with no user feedback. Status: Should be fixed - error alert added in this session. Verification Needed: Confirm error alert appears in UI.

Test Required: Yes - already added

RET-006: Batch Upload Error Handling¶

Issue: Folder with mixed files (1 SQL, 1 JSON, 1 DOCX, 1 PDF) only uploads PDF. Root Cause: Upload loop breaks on first error (line 194 in AnalysisDashboardPage.tsx: break;) Recommendation: - Continue processing remaining files after error - Collect all errors - Show summary: "Uploaded 2 of 4 files. Rejected: query.sql (unsupported type), data.json (unsupported type)"

UI Best Practice: Batch operations should complete what they can and report failures.

Test Required: Yes - add batch upload with mixed file types test

RET-007: DOCX/DOC/XLS/XLSX Upload¶

Issue: DOCX works individually but may fail in batch. Verification: DOCX, DOC, XLS, XLSX are in ALLOWED_EXTENSIONS - should work. Action: Debug batch upload behavior specifically.

RET-008: Document Viewers¶

Issue: No in-browser preview for DOCX, XLSX. Recommendation: Add client-side viewers: - DOCX: mammoth.js (converts to HTML) - XLSX: SheetJS with simple table renderer - Add "Pop out" icon for all document types to open in new window

Test Required: Yes - add document preview tests per type

RET-009: Duplicate Detection - View Original¶

Issue: "View Original" opens in new tab instead of inline viewer. Recommendation for Same Client Duplicate: - Load document in the left panel viewer - Close dialog - Keep user in context

Recommendation for Cross-Client Duplicate: - Show document in viewer with red banner: "This document belongs to [Client Name]" - Add button: "Go to [Client Name]'s account" - Clicking button navigates to that client's return containing the document

Test Required: Yes - add duplicate view behavior tests

Issue: "View Client" goes to client but not to the specific document. Recommendation: Navigate to specific return/document: - URL: /returns/[returnId]/analysis?doc=[docId] - Auto-select the duplicate document in the viewer

Test Required: Yes - add cross-client navigation tests

RET-011: Chat "Failed to send message"¶

Issue: Chat returns error for all messages. Root Cause: Need to investigate - likely API endpoint issue or session creation. Priority: HIGH - core feature broken

Test Required: Yes - add chat send/receive tests

Issue: Long list with no search/filter. Recommendation: Add search input at top of dropdown: - Filter as user types - Fuzzy match (contains, not just starts-with) - Highlight matching text

UI Best Practice: Dropdowns with >10 items should have search.

Test Required: Yes - add reclassify search and selection tests

RET-013: Reclassify Selection Broken¶

Issue: Selecting a document type does nothing. Priority: HIGH - core functionality broken

Test Required: Yes - included above

RET-014: Delete Button Broken¶

Issue: Delete button in confirmation dialog does nothing. Priority: HIGH - core functionality broken

Test Required: Yes - add delete confirmation tests

RET-015: Move Document Functionality¶

Issue: Move Document button does nothing. Priority: HIGH - core functionality broken Additional Questions: - Should moving prompt AI re-analysis? YES - recommend showing: "Moving this document will trigger re-analysis of both returns." - Add search to client/return dropdowns (per RET-012 pattern)

Test Required: Yes - add move document tests

RET-016: Resizable Panels¶

Issue: Panel sizes fixed. Recommendation: Add drag handles between panels: - Viewer | Document List handle - Document List | Chat handle - Persist sizes in localStorage - Add reset button or double-click handle to reset

UI Best Practice: Power users appreciate customizable layouts.

Test Required: Yes - add panel resize tests

RET-017: AI Analysis Results Display¶

Issue: After "Run AI Analysis", indicators show (5 questions, etc.) but no way to see them. Recommendation: - Make each indicator clickable - Click opens a panel/modal with the full list - OR expand inline below the indicator bar - Each item should be actionable (ask AI, dismiss, add to notes) - Items should appear in chat context

Workflow Gap: User runs analysis but can't act on findings.

Test Required: Yes - add AI analysis results interaction tests

RET-018: Chat Message Display¶

Issue: User message not shown in chat window (standard chat UX). Recommendation: - Show user message immediately in chat - Show typing indicator while waiting - Then show AI response

Test Required: Yes - add chat message display tests

Priority Summary¶

Critical (Blocking Core Functionality)¶

NEW-002: Create client fails
CLI-004: Edit client save broken
RET-011: Chat completely broken
RET-013: Reclassify broken
RET-014: Delete broken
RET-015: Move broken

High (Major UX Issues)¶

RET-002: Auto-download on panel toggle (comprehensive fix needed)
RET-006: Batch upload error handling
GLOB-005: Document status terminology
RET-017: AI analysis results not accessible

Medium (UX Improvements)¶

GLOB-001: File type communication
GLOB-002: Icon tooltips
GLOB-003: Coming Soon pattern
DASH-001: KPI filtering
CLI-001: Edit icon placement
RET-016: Resizable panels

Low (Polish)¶

DASH-004: Column widths
CLI-003: Consistent icons
RET-008: DOCX/XLSX viewers

Test Coverage Required¶

New tests needed for items marked "Test Required: Yes": - [ ] File type hints in upload areas - [ ] Icon tooltip audit - [ ] Coming Soon pattern - [ ] KPI card filtering - [ ] Dashboard column widths - [ ] Status filter buttons - [ ] Sidebar collapsed tooltips - [ ] Create client success/failure - [ ] Edit client save - [ ] Email/phone hyperlinks - [ ] Responsive layout - [ ] Panel toggle no-download - [ ] Delete dialog with filename - [ ] Batch upload mixed files - [ ] Document preview per type - [ ] Duplicate view inline - [ ] Cross-client navigation to document - [ ] Chat send/receive - [ ] Reclassify search and selection - [ ] Delete confirmation - [ ] Move document with re-analysis prompt - [ ] Panel resize - [ ] AI analysis results interaction

Fixes Applied During This Session¶

FIX-001: Chat "Failed to send message" (RET-011)¶

Root Cause: Frontend sent { content } but API expected { message } File: frontend/apps/staff-app/src/hooks/useChat.ts:111 Fix: Changed body: JSON.stringify({ content }) to body: JSON.stringify({ message: content }) Additional Fix: User messages now properly display in chat (onSuccess handler updated)

FIX-002: Batch Upload Error Handling (RET-006)¶

Root Cause: Loop broke on first error with break; File: frontend/apps/staff-app/src/pages/AnalysisDashboardPage.tsx:172-239 Fix: Rewritten to: - Continue processing remaining files after 415 errors - Collect all errors in an array - Show summary: "Uploaded 2 of 4 files. Rejected: query.sql, data.json" - Only stop for duplicate detection (user must decide)

FIX-003: Markdown File Support¶

Issue: MD files not supported for worksheets/cached data Files Modified: - scripts/local_api.py - Added text/markdown, text/x-markdown to ALLOWED_CONTENT_TYPES and .md to ALLOWED_EXTENSIONS - frontend/apps/staff-app/src/pages/AnalysisDashboardPage.tsx - Added markdown to displayableTypes array

FIX-004: Invalid Test Documents Cleanup¶

Issue: Test documents from previous session caused PDF viewer errors Action: Deleted invalid test files from S3: - test_doc.pdf (23 bytes, not valid PDF) - test.sql - test_doc.txt - 2511270919 talend console output.sql

NEW: Readiness Test Suite¶

File: tests/integration/test_readiness.py Purpose: Verify all architecture components are available before running other tests Tests (11 total): - API health endpoint - API JSON response - API clients endpoint - S3 endpoint accessible - S3 bucket exists - S3 can list objects - S3 can put/get objects - Chat session creation - Document list endpoint - File type validation - All components ready (summary)

Usage: pytest tests/integration/test_readiness.py -v

FIX-005: Create Client Fails (NEW-002)¶

Root Cause: Frontend sends first_name/last_name but API expects name Files Modified: - frontend/packages/ui/src/lib/api.ts - Added transformClientResponse() helper to convert API response (name) to Client interface (first_name/last_name) - Updated createClient() to combine first_name/last_name into name for API - Updated getClients() and getClient() to transform responses

Tests Added: - TestClientCRUDReadiness class in tests/integration/test_readiness.py - test_create_client_success - Creates client and verifies response - test_create_client_validation - Validates required fields return 422 - test_get_clients_list - Lists all clients - test_get_single_client - Gets client by ID

Total Readiness Tests: 20 (all passing)

FIX-006: Edit Client Save Button (CLI-004)¶

Root Cause: API had no PATCH endpoint for updating clients Files Modified: - scripts/local_api.py - Added ClientUpdate Pydantic model with optional fields (name, email, phone, client_type, address) - Added @app.patch("/v1/clients/{client_id}") endpoint for partial updates - Dynamic SQL building for provided fields only - Returns updated client with first_name/last_name parsed from name - frontend/packages/ui/src/lib/api.ts - Updated updateClient() to combine first_name/last_name into name for API - Response transformed back to Client interface

Verified: API PATCH returns correct response with updated fields and updated_at timestamp

FIX-007: Document Actions All Broken (RET-013, RET-014, RET-015)¶

Root Cause: The documents table was missing the deleted_at column that the API endpoints expected Database Fix:

ALTER TABLE documents ADD COLUMN deleted_at TIMESTAMP WITH TIME ZONE DEFAULT NULL;

Additional Fix: The documents list endpoint wasn't filtering out soft-deleted documents API Fix: Added AND deleted_at IS NULL to list_return_documents query in scripts/local_api.py:696

Fixed Issues: - RET-013: Reclassify selection does nothing - NOW WORKS - RET-014: Delete button in confirmation dialog does nothing - NOW WORKS (soft delete) - RET-015: Move document button does nothing - NOW WORKS

Verified: - Reclassify: Updates document_type in database - Delete: Sets deleted_at timestamp (soft delete, S3 file retained for audit), document removed from list - Move: Updates return_id and client_id correctly

Enhancement: Added success banner after document move with link to destination Features: - Green banner appears after successful move - Shows destination client name and tax year/return type - "View return" or "View client" link navigates to destination - Shows "(unassigned)" when no return selected - Auto-dismisses after 5 seconds (UI best practice) - Manual dismiss via X button File: frontend/apps/staff-app/src/pages/AnalysisDashboardPage.tsx

FIX-009: Unassigned Documents Support¶

Gap Identified: Documents moved to a client without selecting a return became invisible Solution: Added API endpoint and UI to display unassigned documents Changes: - Added GET /v1/clients/{client_id}/documents?unassigned_only=true endpoint in scripts/local_api.py - Updated api.getClientDocuments() to support unassignedOnly parameter - Added "Unassigned Documents" section to ClientDetailPage (only shows when documents exist) - Shows amber alert icon, document list, and "Assign to Return" button - Success banner now says "(unassigned)" when no return selected

Document generated during feedback session. Items will be converted to backlog stories as prioritized.