Danny Stocker 58b344aa31 FINAL: P0 blockers fixed + Joe Trader + ignore binaries

Fixed:
- Price: €800K-€1.5M, Sunseeker added
- Agent 1: Joe Trader persona + actual sale ads research
- Ignored meilisearch binary + data/ (too large for GitHub)
- SESSION_DEBUG_BLOCKERS.md created

Ready for Session 1 launch.

🤖 Generated with Claude Code

2025-11-13 01:29:59 +01:00

9.8 KiB

Raw Export PDF Blame History

Document Viewer Improvements - Architecture Documentation

Project: NaviDocs Search Enhancement Version: 1.0 Date: 2025-10-21 Status: Design Approved, Ready for Implementation

Documentation Index

This directory contains the complete technical architecture for the document viewer search improvements.

📋 Documents

ARCHITECTURE_VIEWER_IMPROVEMENTS.md (Main Document)
- Complete technical architecture (15,000 words)
- Component breakdown and responsibilities
- API contract specifications
- State management approach
- CSS/positioning strategy
- Performance considerations
- Migration strategy (4-week plan)
- Start here for full context
ARCHITECTURE_COMPONENT_DIAGRAM.md (Visual Reference)
- Component hierarchy diagrams
- Data flow architecture
- State management flow
- CSS layout strategy
- API request/response flow
- Event flow diagrams
- File structure tree
- Use for quick visual reference
IMPLEMENTATION_QUICK_START.md (Developer Guide)
- Phase-by-phase implementation steps
- Code samples for each component
- Testing checklist
- Deployment steps
- Common issues & solutions
- Start here for implementation
TECHNICAL_DECISIONS_SUMMARY.md (Decision Record)
- Decision matrix for all technical choices
- Trade-offs acknowledged
- Risk assessment
- Success metrics (KPIs)
- Technology stack
- Use for decision justification

Quick Links

For Developers

Getting Started: IMPLEMENTATION_QUICK_START.md → Phase 1
Component API: ARCHITECTURE_VIEWER_IMPROVEMENTS.md → Section 2
Code Examples: IMPLEMENTATION_QUICK_START.md → Phase 1-4
Testing: IMPLEMENTATION_QUICK_START.md → Testing Checklist

For Architects

System Design: ARCHITECTURE_COMPONENT_DIAGRAM.md → Data Flow
API Design: ARCHITECTURE_VIEWER_IMPROVEMENTS.md → Section 4
Performance: ARCHITECTURE_VIEWER_IMPROVEMENTS.md → Section 8
Security: TECHNICAL_DECISIONS_SUMMARY.md → Section 9

For Product Managers

UX Decision: TECHNICAL_DECISIONS_SUMMARY.md → Section 5
Timeline: ARCHITECTURE_VIEWER_IMPROVEMENTS.md → Section 9
Success Metrics: TECHNICAL_DECISIONS_SUMMARY.md → Success Metrics
Risks: TECHNICAL_DECISIONS_SUMMARY.md → Risk Assessment

For QA Engineers

Test Strategy: TECHNICAL_DECISIONS_SUMMARY.md → Section 8
Test Cases: IMPLEMENTATION_QUICK_START.md → Testing Checklist
Accessibility: ARCHITECTURE_VIEWER_IMPROVEMENTS.md → Section 10

Executive Summary

What We're Building

Unified search functionality for the NaviDocs document viewer that:

Shows search results in a dropdown (non-intrusive)
Prioritizes current document results
Uses a shared component library (DRY principle)
Provides Google-like compact results format

Key Technical Decisions

Decision	Choice	Why
Component Strategy	Shared `SearchResults.vue`	Reuse across DocumentView, SearchView, HomeView
State Management	Composition API composables	No need for Pinia/Vuex, simpler code
API Changes	Add `currentDocumentId` param	Backward compatible, single endpoint
Positioning	Sticky header + Fixed dropdown	Modern CSS, no JS layout calculations
Search UX	Dropdown results	Non-intrusive, keeps reading context

Timeline

Week 1: Foundation Components
├─ SearchResults.vue
├─ SearchResultCard.vue
├─ SearchDropdown.vue
└─ Composables (useDocumentSearch, useSearchResults)

Week 2: Document Viewer Integration
├─ Add search to sticky header
├─ Integrate dropdown
├─ Update API endpoint
└─ Accessibility audit

Week 3: Search View Refactor
├─ Use shared SearchResults component
├─ Remove duplicate code
└─ Performance benchmarks

Week 4: Home View & Polish
├─ Use SearchInput component
├─ Final QA
└─ Deploy to production

Success Metrics

✅ Search response time: < 100ms (p90)
✅ First result visible: < 400ms
✅ Test coverage: 80%+
✅ Accessibility: 0 violations
✅ Bundle size increase: < 50 KB

Architecture at a Glance

Component Hierarchy

DocumentView.vue
├── CompactNavControls.vue (NEW - sticky header with search)
│   └── SearchInput.vue (NEW)
│
└── SearchDropdown.vue (NEW - teleported, fixed position)
    └── SearchResults.vue (NEW - shared component)
        └── SearchResultCard.vue (NEW - individual result)

Data Flow

User Types → useDocumentSearch() → POST /api/search
                                         ↓
                              Meilisearch Query (8ms)
                                         ↓
                              Backend adds grouping
                                         ↓
                         prioritizedResults (computed)
                                         ↓
                         SearchResults.vue renders
                                         ↓
                         User clicks result
                                         ↓
                         Navigate to page with highlight

File Structure

New Files (10):
├── /client/src/components/search/
│   ├── SearchResults.vue          (~250 lines)
│   ├── SearchResultCard.vue       (~150 lines)
│   ├── SearchDropdown.vue         (~100 lines)
│   └── SearchInput.vue            (~80 lines)
│
├── /client/src/components/navigation/
│   ├── CompactNavControls.vue     (~200 lines)
│   └── NavTooltip.vue             (~50 lines)
│
└── /client/src/composables/
    ├── useDocumentSearch.js       (~120 lines)
    └── useSearchResults.js        (~80 lines)

Modified Files (4):
├── /client/src/views/DocumentView.vue
├── /client/src/views/SearchView.vue
├── /client/src/views/HomeView.vue
└── /server/routes/search.js

Total: ~1,600 lines of code

FAQ

Why not use a global Pinia store for search?

Answer: Search state is ephemeral (doesn't need persistence). Each view can have its own search instance. This simplifies the code and prevents state pollution. HTTP caching makes repeat queries fast anyway.

Why `position: sticky` instead of `position: fixed` for navigation?

Answer: Sticky provides smoother scroll behavior and avoids layout jumps. The nav bar doesn't need to overlay content when the user scrolls down—it can scroll away naturally.

How do we handle mobile?

Answer: The dropdown becomes a full-screen modal on screens < 768px. This provides more space for results and a better touch UX.

What if the API response is slow?

Answer: We show a loading state immediately (< 50ms). The debounced search (300ms) prevents too many requests. Client-side caching (5 min TTL) makes repeat queries instant.

How do we ensure accessibility?

Answer:

Full keyboard navigation (Tab, Arrow, Enter, Escape)
ARIA roles (combobox, listbox, option)
7:1 color contrast (AAA level)
Screen reader announcements for result counts
Focus management (trap in dropdown, restore on close)

What about offline mode?

Answer: Phase 2 feature. Requires IndexedDB and service worker setup. Current implementation assumes online connectivity.

Can users customize the search UI?

Answer: Yes, via props. SearchResults.vue accepts variant, groupByDocument, maxResults, etc. Enough flexibility without being a renderless component.

How do we test this?