navidocs/server/docs/TECHNICAL_DECISIONS_SUMMARY.md

# Technical Decisions Summary

**Project**: Document Viewer Search Improvements
**Date**: 2025-10-21
**Status**: Approved Design

## Key Decisions Matrix

### 1. Component Architecture

| Decision | Chosen Approach | Rationale | Alternatives Considered |
|----------|----------------|-----------|------------------------|
| **Search Results Component** | Unified `SearchResults.vue` shared by DocumentView and SearchView | DRY principle, consistent UX, easier maintenance | Separate components per view (rejected: code duplication) |
| **Result Card** | Extract to `SearchResultCard.vue` | Reusable across dropdown and full-page views | Inline template (rejected: hard to test) |
| **Dropdown Container** | Separate `SearchDropdown.vue` with Teleport | Clean separation of concerns, portal for z-index | Inline in DocumentView (rejected: messy code) |
| **Navigation Controls** | `CompactNavControls.vue` component | Encapsulates nav logic, reusable | Mix with DocumentView (rejected: poor separation) |

**Decision**: Component-based architecture with clear responsibilities

---

### 2. State Management

| Decision | Chosen Approach | Rationale | Alternatives Considered |
|----------|----------------|-----------|------------------------|
| **Global State** | NO global store (Pinia/Vuex) | Search is ephemeral, component-scoped state sufficient | Pinia store (rejected: unnecessary complexity) |
| **Composables** | `useDocumentSearch.js`, `useSearchResults.js` | Composition API pattern, code reuse without coupling | Mixin-based (rejected: Vue 3 deprecates mixins) |
| **Search Caching** | In-memory Map with 5-min TTL | Fast repeat queries, automatic cleanup | localStorage (rejected: not sensitive data) |
| **Result Grouping** | Computed property in composable | Reactive, declarative, no manual updates | Manual state management (rejected: error-prone) |

**Decision**: Composition API with reactive composables, no global store

---

### 3. API Design

| Decision | Chosen Approach | Rationale | Alternatives Considered |
|----------|----------------|-----------|------------------------|
| **Document Scoping** | Add `currentDocumentId` param to existing `/api/search` | Backward compatible, single endpoint | New `/api/search/scoped` endpoint (rejected: fragmentation) |
| **Grouping Metadata** | Return `grouping` object in response | Frontend can display counts without recalculation | Client-side grouping only (rejected: missed optimization) |
| **Result Prioritization** | Backend adds `_isCurrentDoc` flag | Single source of truth, less client logic | Client-only sorting (rejected: duplicates logic) |
| **Pagination** | Existing `limit`/`offset` params | Already implemented, works well | Cursor-based (rejected: overkill) |

**Decision**: Extend existing API with minimal changes, maintain backward compatibility

**API Contract**:
```json
POST /api/search
Request: {
  "q": "query",
  "currentDocumentId": "doc-123",  // NEW (optional)
  "limit": 50
}

Response: {
  "hits": [...],
  "grouping": {                     // NEW
    "currentDocument": { "hitCount": 8 },
    "otherDocuments": { "hitCount": 12, "documentCount": 3 }
  }
}
```

---

### 4. CSS/Positioning Strategy

| Decision | Chosen Approach | Rationale | Alternatives Considered |
|----------|----------------|-----------|------------------------|
| **Navigation Bar** | `position: sticky; top: 0` | Smooth scroll behavior, no JS needed | `position: fixed` (rejected: layout jumps) |
| **Search Dropdown** | `position: fixed` + Teleport to body | Overlays content, no z-index issues | Absolute position (rejected: overflow issues) |
| **Backdrop Blur** | CSS `backdrop-filter: blur(16px)` | Native browser support, GPU accelerated | JS blur library (rejected: performance cost) |
| **Transitions** | CSS transitions only | 60fps, hardware accelerated | JS animation libraries (rejected: bundle size) |
| **Mobile Layout** | Full-screen modal (< 768px), dropdown (> 768px) | Better touch UX, more space on mobile | Same dropdown everywhere (rejected: poor mobile UX) |

**Decision**: Modern CSS features (sticky, backdrop-filter) with progressive enhancement

**Browser Support**:
- Chrome/Edge 90+
- Firefox 88+
- Safari 14+
- All features have 95%+ browser support as of 2025

---

### 5. Search UX Pattern

| Decision | Chosen Approach | Rationale | Alternatives Considered |
|----------|----------------|-----------|------------------------|
| **DocumentView Search** | Dropdown results | Non-intrusive, keeps context | Full-page (rejected: disrupts reading), Sidebar (rejected: screen space) |
| **Result Grouping** | "This Document" first, then "Other Documents" | Users prioritize current doc 80% of time | Flat list (rejected: poor scannability) |
| **Debounce Delay** | 300ms | Balance between responsiveness and API load | 500ms (rejected: feels slow), 100ms (rejected: too many requests) |
| **Results Per Group** | 5 current doc, 5 other docs, "Show more" button | Compact, shows variety, infinite scroll option | Show all (rejected: overwhelming), 3 per group (rejected: too few) |
| **Keyboard Navigation** | Arrow keys, Enter, Escape | Power user efficiency | Mouse-only (rejected: poor accessibility) |

**Decision**: Google-like dropdown with intelligent grouping

**UX Flow**:
```
User types → 300ms debounce → API call → Dropdown renders
  ↓
"This Document (8)"     ← Always first
  Page 12: ...
  Page 15: ...
  [5 results max]

"Other Documents (4)"   ← Collapsed by default on mobile
  Engine Manual p8: ...
  [Show 8 more]

Click result → Navigate to page → Dropdown closes
```

---

### 6. Performance Optimizations

| Decision | Chosen Approach | Rationale | Alternatives Considered |
|----------|----------------|-----------|------------------------|
| **Search Debouncing** | `useDebounceFn` from @vueuse/core | Battle-tested, TypeScript support | Custom debounce (rejected: reinventing wheel) |
| **Result Caching** | 5-minute in-memory cache | Repeat searches instant | IndexedDB (rejected: overkill), No cache (rejected: poor UX) |
| **Virtual Scrolling** | Only if > 100 results | Most searches return < 50 results | Always virtual scroll (rejected: complexity), Never (rejected: performance) |
| **Image Lazy Loading** | `IntersectionObserver` API | Native, no library needed | Eager loading (rejected: slow), Library (rejected: bundle size) |
| **Bundle Splitting** | Code split search components | Faster initial load | Single bundle (rejected: larger initial load) |

**Decision**: Pragmatic optimizations based on real-world usage

**Performance Targets**:
- Search input → API response: < 100ms (p90)
- API response → Dropdown render: < 50ms
- Dropdown open/close: 60fps (16ms per frame)
- Total (type to see results): < 400ms

---

### 7. Accessibility

| Decision | Chosen Approach | Rationale | Alternatives Considered |
|----------|----------------|-----------|------------------------|
| **ARIA Roles** | `role="combobox"`, `role="listbox"`, `role="option"` | WCAG 2.1 AA compliance | No ARIA (rejected: fails screen readers) |
| **Keyboard Navigation** | Full keyboard support (Tab, Arrow, Enter, Escape) | Power users, accessibility requirement | Mouse-only (rejected: excludes users) |
| **Focus Management** | Trap focus in dropdown, restore on close | Prevents keyboard users getting lost | No focus trap (rejected: poor UX) |
| **Color Contrast** | 7:1 for text, 4.5:1 for highlights (AAA) | Readable for low vision users | 4.5:1 everywhere (rejected: not AAA) |
| **Screen Reader** | Live regions for result count announcements | Blind users know search completed | Silent (rejected: no feedback) |

**Decision**: WCAG 2.1 AAA where feasible, AA minimum

**ARIA Structure**:
```html
<div role="combobox" aria-expanded="true" aria-owns="results-listbox">
  <input role="searchbox" aria-label="Search documents" />
</div>
<ul id="results-listbox" role="listbox" aria-label="Search results">
  <li role="option" aria-selected="false">...</li>
</ul>
<div aria-live="polite">8 results found</div>
```

---

### 8. Testing Strategy

| Decision | Chosen Approach | Rationale | Alternatives Considered |
|----------|----------------|-----------|------------------------|
| **Unit Tests** | Vitest | Fast, Vue-native, Vite integration | Jest (rejected: slower setup) |
| **Component Tests** | @vue/test-utils | Official Vue testing library | Testing Library (rejected: different philosophy) |
| **E2E Tests** | Playwright | Modern, reliable, cross-browser | Cypress (rejected: fewer browsers), Selenium (rejected: slow) |
| **Coverage Target** | 80% for new code | Pragmatic balance | 100% (rejected: diminishing returns), None (rejected: risky) |
| **CI Integration** | GitHub Actions on PR | Automated, free for OSS | Manual testing (rejected: error-prone) |

**Decision**: Comprehensive testing with pragmatic coverage goals

**Test Pyramid**:
```
     /\
    /  \     E2E (10 tests)
   /____\    - Search flow
  /      \   - Navigation
 /________\  - Mobile UX

/          \ Integration (30 tests)
/__________\ - Component interactions
             - Composable logic

/            \ Unit (60 tests)
/______________\ - SearchResults.vue
                 - useDocumentSearch.js
                 - Result grouping logic
```

---

### 9. Security

| Decision | Chosen Approach | Rationale | Alternatives Considered |
|----------|----------------|-----------|------------------------|
| **XSS Prevention** | Vue auto-escaping + `v-html` only for Meilisearch responses | Meilisearch sanitizes HTML | DOMPurify library (rejected: Meilisearch already safe) |
| **Query Sanitization** | 200 char limit, strip `<>` characters | Prevent injection attacks | No sanitization (rejected: vulnerable) |
| **Row-Level Security** | Existing tenant tokens + org filtering | Already implemented | Client-side filtering only (rejected: data leak) |
| **Rate Limiting** | Debounce (300ms) + server-side rate limit | Prevent abuse | No limit (rejected: DoS vulnerable) |

**Decision**: Leverage existing security model, minimal additional code

---

### 10. Migration & Rollout

| Decision | Chosen Approach | Rationale | Alternatives Considered |
|----------|----------------|-----------|------------------------|
| **Rollout Strategy** | Phased: DocumentView → SearchView → HomeView | Test each integration point | Big bang (rejected: risky), Feature flag (rejected: complexity) |
| **Backward Compatibility** | Keep old components until full rollout | Safe rollback | Delete old code immediately (rejected: no rollback) |
| **Database Migrations** | None needed | No schema changes | Add search history table (rejected: Phase 2 feature) |
| **Deployment** | Standard CI/CD pipeline | No special process | Blue-green deployment (rejected: overkill for this change) |

**Decision**: Low-risk phased rollout with rollback capability

**Timeline**:
```
Week 1: Foundation components (can test in isolation)
Week 2: DocumentView integration (feature works end-to-end)
Week 3: SearchView refactor (remove duplication)
Week 4: HomeView polish + final QA
```

---

## Decision Ownership

| Area | Owner | Reviewer | Status |
|------|-------|----------|--------|
| Component Architecture | Tech Lead | Senior Engineer | ✅ Approved |
| API Design | Backend Lead | Tech Lead | ✅ Approved |
| UX Design | Product Designer | UX Lead | ✅ Approved |
| Performance | Tech Lead | DevOps | ✅ Approved |
| Accessibility | Frontend Lead | Accessibility Specialist | ✅ Approved |
| Testing | QA Lead | Tech Lead | ✅ Approved |

---

## Trade-offs Acknowledged

### 1. No Pinia/Vuex Store
**Trade-off**: Each view has its own search instance
**Benefit**: Simpler code, no global state pollution
**Cost**: Can't share search results between views
**Mitigation**: HTTP cache makes repeat queries fast anyway

### 2. Component-based vs. Renderless
**Trade-off**: `SearchResults.vue` has markup (not renderless)
**Benefit**: Easier to understand, faster to implement
**Cost**: Less flexible for advanced customization
**Mitigation**: Props allow sufficient customization for our needs

### 3. CSS Sticky vs. Fixed
**Trade-off**: Sticky doesn't overlay content
**Benefit**: Smoother scroll behavior, no layout shift
**Cost**: Scrolls out of view on long documents
**Mitigation**: Users rarely scroll far with search open

### 4. Dropdown vs. Modal
**Trade-off**: Dropdown has limited space
**Benefit**: Non-intrusive, keeps context
**Cost**: May truncate results on small screens
**Mitigation**: Full-screen modal on mobile (< 768px)

---

## Success Metrics (KPIs)

| Metric | Baseline | Target | Measurement |
|--------|----------|--------|-------------|
| Search response time | 150ms (p90) | < 100ms (p90) | Server logs |
| Time to first result | N/A (no search) | < 400ms | Lighthouse |
| Search success rate | 60% (estimate) | 80% | Analytics |
| Keyboard navigation usage | 0% | 15% | Event tracking |
| Accessibility violations | Unknown | 0 (axe-core) | CI pipeline |
| Bundle size increase | 0 KB | < 50 KB (gzipped) | Webpack stats |
| Test coverage | 0% (new code) | 80% | Vitest report |

---

## Risk Assessment

| Risk | Likelihood | Impact | Mitigation |
|------|-----------|--------|-----------|
| **Performance degradation** | Low | High | Benchmarks before/after, load testing |
| **Accessibility issues** | Medium | High | Automated testing (axe-core), manual audit |
| **Cross-browser bugs** | Medium | Medium | Playwright tests on Chrome, Firefox, Safari |
| **Mobile UX problems** | Low | Medium | Responsive design from day 1, mobile testing |
| **API breaking changes** | Low | High | Backward compatible API, versioning |
| **Code duplication** | Medium | Low | Shared component library, code review |

**Overall Risk**: **LOW** (well-defined scope, incremental rollout)

---

## Open Questions (Deferred to Phase 2)

1. **Search History**: Store recent searches in localStorage?
   - Decision: Phase 2 feature
   - Reasoning: Nice-to-have, not critical for MVP

2. **Search Suggestions**: Auto-complete while typing?
   - Decision: Phase 2 feature
   - Reasoning: Requires additional Meilisearch config

3. **Advanced Filters**: Filter by document type, date, etc.?
   - Decision: Phase 2 feature
   - Reasoning: SearchView already has basic filters

4. **Search Analytics**: Track queries for insights?
   - Decision: Phase 2 feature
   - Reasoning: Privacy considerations, analytics setup

5. **Offline Search**: IndexedDB for offline mode?
   - Decision: Phase 2 feature (PWA enhancement)
   - Reasoning: Requires service worker, complex sync

---

## Final Recommendation

**APPROVED** for implementation with the following conditions:

1. ✅ **Phased rollout**: Start with DocumentView, validate before continuing
2. ✅ **Test coverage**: 80% minimum for new code
3. ✅ **Performance**: Maintain < 100ms search latency (p90)
4. ✅ **Accessibility**: Zero violations in axe-core audit
5. ✅ **Rollback plan**: Keep old components until full deployment

**Next Steps**:
1. Create GitHub issues for each phase
2. Assign to frontend engineer
3. Schedule design review after Phase 1
4. Schedule QA after Phase 3
5. Deploy to production after Phase 4

---

**Document Version**: 1.0
**Last Updated**: 2025-10-21
**Status**: Ready for Implementation

---

## Appendix: Technology Stack

| Layer | Technology | Version | Purpose |
|-------|-----------|---------|---------|
| **Frontend Framework** | Vue 3 | 3.5.0 | UI components |
| **Composition API** | @vueuse/core | Latest | Utilities (debounce, etc.) |
| **Search Engine** | Meilisearch | 0.41.0 | Full-text search |
| **HTTP Client** | Fetch API | Native | API calls |
| **Router** | Vue Router | 4.4.0 | Navigation |
| **Build Tool** | Vite | 5.0.0 | Bundler |
| **CSS Framework** | Tailwind CSS | 3.4.0 | Styling |
| **PDF Rendering** | PDF.js | 4.0.0 | Document viewer |
| **Testing** | Vitest + Playwright | Latest | Unit + E2E tests |
| **Backend** | Express.js | Latest | API server |
| **Database** | SQLite | Latest | Metadata storage |