navidocs/ARCHITECTURE-SUMMARY.md

NaviDocs Architecture Summary

Status: Design Complete ✅
Next Phase: Implementation
Created: 2025-01-19

---

📋 What We've Built

A future-proof, multi-vertical document management platform for boat owners, marinas, and property managers.

---

🎯 Core Architectural Decisions

1. Hybrid Database Strategy

• SQLite for transactional data (users, boats, documents)
• Meilisearch for search-optimized queries
• Migration path to PostgreSQL when scaling requires it

Why: Search-first architecture. Every query is a search query, not a SQL JOIN.

2. Multi-Vertical Schema

• Designed for boats (v1.0)
• Expandable to marinas, properties, HOAs (v1.1+)
• Unified hierarchy: Organization → Entity → Sub-Entity → Component → Document

Why: Patterns are identical across verticals. Build once, reuse everywhere.

3. Security-First

• Tenant tokens (NOT master keys in client)
• Background queue for CPU-intensive OCR
• File safety pipeline (qpdf + ClamAV + validation)
• Rate limiting on all endpoints

Why: Expert panel identified these as production killers if skipped.

4. Offline-First PWA

• Service worker caches critical manuals
• Works 20 miles offshore with no cell signal
• IndexedDB for local state

Why: Boat owners need manuals when engines fail at sea.

5. Synonym-Rich Search

• 40+ boat terminology synonyms ("bilge" → "sump pump")
• Typo tolerance (Meilisearch built-in)
• Future: semantic search with embeddings

Why: Boat owners don't know technical jargon.

---

📊 Schema Design

SQLite Tables (13 tables)

Core: users, organizations, user_organizations
Entities: entities, sub_entities, components
Documents: documents, document_pages, ocr_jobs
Permissions: permissions, document_shares
UX: bookmarks

Meilisearch Index

Index: navidocs-pages
Documents: One per PDF page
Searchable: title, text, systems, categories, tags
Filterable: boatId, userId, make, model, year, etc
Synonyms: 40+ boat terminology mappings

Key Insight: Each PDF page is a separate Meilisearch document. No JOINs needed.

---

🚀 Technology Stack

Backend

• Node.js v20 (Express or Fastify)
• SQLite3 (better-sqlite3)
• Meilisearch v1.6.2
• BullMQ (or SQLite-based queue fallback)
• Tesseract.js (OCR)
• qpdf + ClamAV (file safety)

Frontend

• Vue 3 + Vite
• Tailwind CSS
• PDF.js (document viewer)
• Meilisearch-inspired design (clean, professional, SVG icons)
• PWA (offline support)

Security

• Helmet (CSP, HSTS headers)
• express-rate-limit
• JWT auth
• Tenant tokens (Meilisearch)

---

🎨 Design Philosophy

Inspired by: https://www.meilisearch.com/
Visual Language:

• Clean, spacious layouts
• Professional SVG icons (no emojis)
• Muted color palette (grays, blues, whites)
• Typography: SF Pro / Inter / Roboto
• Expensive, grown-up aesthetic

NOT: Playful, colorful, emoji-heavy consumer apps

---

📈 Scaling Strategy

Day 1 (MVP)

• SQLite (< 100k documents)
• Single Meilisearch instance
• Single-tenant (one user, multiple boats)

Month 6 (Growth)

• Still SQLite (works up to 1M documents)
• Meilisearch cluster (if > 10k searches/day)
• Multi-tenant (organizations)

Year 1 (Scale)

• Migrate to PostgreSQL
• Add pgvector for semantic search
• Cloudflare CDN for PDFs
• Separate OCR worker VPS

---

🔒 Security Hardening Checklist

• Never expose Meilisearch master key to client
• Use tenant tokens (1-hour TTL)
• Background queue for OCR (prevent CPU spikes)
• File safety: extension + magic byte + qpdf + ClamAV
• Rate limiting: 10 uploads/hour, 30 searches/minute
• Helmet security headers (CSP, HSTS)
• HTTPS only (no HTTP)
• Rotate API keys monthly

---

🧪 Testing Strategy

Unit Tests (Jest/Vitest)

• Database models
• Search service
• OCR pipeline
• File validation

Integration Tests

• Upload → OCR → Index → Search
• User auth flow
• Permission checks

E2E Tests (Playwright)

• Upload PDF
• Search and view results
• Offline mode
• Mobile responsive

---

📦 Expert Panel Consensus

47 minutes of debate:

• Database Architect: "Future-proof for Postgres migration"
• Search Engineer: "Search-first, not relational-first"
• DevOps: "Append-only schema, no breaking changes"
• Data Scientist: "Embedding field from day 1 (even if null)"
• Backend Lead: "Hybrid approach wins"

Result: SQLite + Meilisearch hybrid, designed for Postgres migration.

38 minutes with boating experts:

• Marine Surveyor: "Emergency scenarios = offline required"
• Marina Manager: "Shared component library (10 boats, same Volvo engine)"
• Yacht Broker: "Resale value = complete documentation history"

Result: Offline PWA, shared manuals, service tracking.

29 minutes with property/marina experts:

• Multi-entity hierarchy (XYZ Corp → Marina A → Dock 1 → Slip 42)
• Compliance tracking (inspections, certifications)
• Geo-search for physical assets

Result: Schema supports vertical expansion.

---

📂 Repository Structure

navidocs/
├── docs/
│   ├── debates/
│   │   └── 01-schema-and-vertical-analysis.md
│   ├── architecture/
│   │   ├── database-schema.sql
│   │   ├── meilisearch-config.json
│   │   └── hardened-production-guide.md
│   └── roadmap/
│       ├── v1.0-mvp.md
│       └── 2-week-launch-plan.md
├── server/          (TBD: Extract from lilian1)
├── client/          (TBD: Build from scratch)
├── README.md
└── ARCHITECTURE-SUMMARY.md (this file)

---

🎯 Success Criteria (MVP Launch)

Technical:

• Upload PDF → searchable in < 5 minutes
• Search latency < 100ms
• Synonym search works ("bilge" finds "sump")
• All fields display correctly
• Offline mode functional

Security:

• Zero master keys in client code
• Tenant tokens expire after 1 hour
• All PDFs sanitized
• Rate limits prevent abuse

User Experience:

• Upload success rate > 95%
• Search relevance 4/5+ rating
• Mobile usable without zooming

---

🚦 Next Steps

1. Analyze lilian1 - Extract clean code, identify Frank-AI junk
2. Bootstrap NaviDocs - Create server/ and client/ structure
3. Implement core features - Upload, OCR, Search
4. Playwright tests - E2E coverage
5. Local deployment - Test with real boat manuals
6. Beta launch - 5-10 boat owners

---

The war council has spoken. Time to build.