navidocs/ARCHITECTURE_INTEGRATION_ANALYSIS.md

NaviDocs Architecture Analysis & Integration Points

Analysis Date: 2025-11-13
Project: NaviDocs - Multi-vertical Document Management System
Scope: Yacht Sales & Marine Asset Documentation

---

EXECUTIVE SUMMARY

NaviDocs is a production-ready document management platform designed for multi-entity scenarios (boats, marinas, properties). The architecture supports:

• Multi-tenancy with organization/entity hierarchies
• Background processing for OCR and indexing
• Search-first design using Meilisearch
• Offline-capable PWA client (Vue 3)
• Granular access control with role-based permissions
• Extensible metadata for custom integrations

Gap Analysis: Currently NO external integrations (Home Assistant, MQTT, webhooks). Foundation exists for adding them.

---

1. DATABASE SCHEMA ANALYSIS

Location

• /home/setup/navidocs/server/db/schema.sql (primary)
• Migrations: /home/setup/navidocs/server/db/migrations/

Core Tables (13 total)

A. Tenant Structure

Table	Purpose	Key Fields
users	User authentication	id (UUID), email, password_hash, created_at
organizations	Multi-entity container	id, name, type (personal/commercial/hoa), metadata (JSON)
user_organizations	Membership + roles	user_id, organization_id, role (admin/manager/member/viewer)

B. Asset Hierarchy

Table	Purpose	Key Fields
entities	Boats, marinas, condos	id, organization_id, entity_type, name, boat-specific (hull_id, vessel_type, length_feet, make, model, year)
sub_entities	Systems, docks, units	id, entity_id, name, type, metadata
components	Engines, panels, appliances	id, sub_entity_id/entity_id, name, manufacturer, model_number, serial_number, install_date, warranty_expires

YACHT SALES RELEVANCE:

• Vessel specs: hull_id (HIN), vessel_type, length, make, model, year
• Component tracking: engines, electrical systems, HVAC by serial number
• Perfect for "as-built" documentation transfer at closing

C. Document Management

Table	Purpose	Key Fields
documents	File metadata	id, organization_id, entity_id (boat link!), sub_entity_id, component_id, title, document_type (owner-manual, component-manual, service-record, etc), status (processing/indexed/failed), file_hash (SHA256 for dedup)
document_pages	OCR results per page	id, document_id, page_number, ocr_text, ocr_confidence, ocr_language, meilisearch_id, metadata
ocr_jobs	Background processing queue	id, document_id, status (pending/processing/completed/failed), progress (0-100), error, timestamps

D. Access Control

Table	Purpose	Key Fields
permissions	Granular resource access	resource_type (document/entity/organization), resource_id, user_id, permission (read/write/share/delete/admin), granted_at, expires_at
document_shares	Simplified sharing	document_id, shared_by, shared_with, permission (read/write)

E. User Experience

Table	Purpose	Key Fields
bookmarks	Quick access pins	user_id, document_id, page_id, label, quick_access (bool)

Schema Design Strengths for Yacht Sales

1. Deduplication by Hash: SHA256 file hash prevents duplicate owner manuals when same boat model has same manual
2. Metadata Extensibility: JSON fields on entities, components, documents for custom data (broker notes, sale status, etc)
3. Temporal Tracking: created_at, updated_at, warranty_expires, install_date for compliance/history
4. Soft Deletes: status field + replaced_by support version history without losing data

Migration History

• 002_add_document_toc.sql - Table of Contents support
• 008_add_organizations_metadata.sql - Custom metadata column
• 009_permission_templates_and_invitations.sql - Invite workflow

---

2. API ENDPOINTS & CAPABILITIES

Location: /home/setup/navidocs/server/routes/

A. Authentication & Multi-Tenancy

Route: /api/auth

• POST /register - User signup with email verification
• POST /login - JWT + refresh token generation
• POST /refresh - Refresh access token
• POST /logout - Session revocation
• GET /me - Current user profile
• POST /password/reset-request - Email-based reset
• POST /password/reset - Reset with token
• POST /email/verify - Email verification

Auth Service: /server/services/auth.service.js

• bcrypt password hashing
• JWT token management (default: 7-day expiry)
• Audit logging on all auth events
• Device tracking (user-agent, IP, login timestamps)

B. Organization Management

Route: /api/organizations

• POST / - Create organization (with owner as member)
• GET / - List user's organizations
• GET /:id - Organization details (members, stats)
• PUT /:id - Update organization (name, metadata)
• DELETE /:id - Delete org (soft delete with audit trail)
• GET /:id/members - List organization members
• POST /:id/members - Invite user to org
• DELETE /:id/members/:userId - Remove user
• GET /:id/stats - Document count, storage usage

Authorization Checks:

• Organization admin role required for member management
• User membership verified before access
• Organization metadata supports custom fields

C. Document Management

Route: /api/documents

• GET /:id - Document metadata (with ownership check)
• GET ?organizationId=X&limit=50 - List documents with pagination
• DELETE /:id - Soft delete with file cleanup

Ownership Verification:

-- Access granted if:
1. User is in document's organization, OR
2. User uploaded the document, OR
3. Document was shared with user

D. File Upload & OCR Pipeline

Route: /api/upload

• POST / - Upload PDF (multipart/form-data)
  • Parameters: file, title, documentType, organizationId, entityId (optional), componentId (optional)
  • Response: { jobId, documentId, message }
  • File validation: .pdf only, magic bytes check, max 50MB
  • File safety: sanitized filename, SHA256 hash, no null bytes

Quick OCR Route: /api/upload/quick-ocr

• Fast OCR for preview/validation

Deduplication: SHA256 hash checks prevent uploading same file twice

E. Background Jobs

Route: /api/jobs

• GET /:id - Job status and progress (0-100%)
• GET ?status=completed&limit=50 - List jobs with filtering
• Response includes: documentId, status (pending/processing/completed/failed), progress, error message

Queue System: BullMQ with Redis backend

• 3 retry attempts with exponential backoff
• Job persistence for 24 hours (completed) / 7 days (failed)
• Progress updates via WebSocket-ready design

F. Search & Indexing

Route: /api/search

• POST /token - Generate Meilisearch tenant token (1-hour TTL, user-scoped)
• POST / - Server-side search (optional, for SSR)
  • Filters: documentType, entityId, language, custom fields
  • Response: hits, estimatedTotalHits, processingTimeMs
• GET /health - Meilisearch connectivity check

Security:

• Tenant tokens scoped to user + their organizations
• Row-level filtering injected at token generation
• Master key never exposed to client
• Fallback to search-only API key

G. Permissions Management

Route: /api/permissions

• Grant/revoke read/write/share/admin access
• Resource-level granularity (document, entity, organization)
• Time-bound permissions with expiration
• Audit trail of who granted what when

H. System Settings

Route: /api/admin/settings (admin-only)

• GET /public/app - Public app name (no auth)
• Settings management: OCR language, email config, feature flags
• Categories: app, email, ocr, security, integrations

I. Table of Contents

Route: /api/documents/:id/toc

• Extract and display document structure
• PDF heading hierarchy
• Section-based navigation

J. Images & Media

Route: /api/images

• Extract images from PDF pages
• Image search within documents
• Figure/diagram zoom capability

K. Statistics

Route: /api/stats

• Organization document count
• Storage usage
• OCR processing metrics
• User activity trends

---

3. FRONTEND ARCHITECTURE

Location: /home/setup/navidocs/client/src/

A. Core Views

View	Route	Purpose
HomeView	/	Dashboard, recent docs, quick access
LibraryView	/library	Document browser by entity/type
SearchView	/search	Full-text search with filters
DocumentView	/document/:id	PDF viewer with OCR results
AuthView	/auth/login, /register	Login/signup forms
AccountView	/account	User profile, organizations
JobsView	/jobs	Upload progress, OCR status

B. Reusable Components

Component	Purpose
UploadModal	Drag-drop file upload interface
TocSidebar	Document TOC navigation
TocEntry	Individual TOC item renderer
DocumentView	PDF.js viewer with search overlay
ImageOverlay	Full-screen image viewer
FigureZoom	Figure/diagram magnifier
ToastContainer	Notification system
ConfirmDialog	Action confirmation UI
CompactNav	Mobile-friendly navigation
LanguageSwitcher	UI language selection

C. Framework & Libraries

• Vue 3 with Composition API
• Vue Router for SPA navigation
• Tailwind CSS for styling (Meilisearch-inspired design)
• PDF.js for document rendering
• Meilisearch JS for client-side search
• IndexedDB for offline storage (PWA)

D. PWA Capabilities

• Service worker for offline mode
• Offline-first architecture (works 20+ miles offshore per design docs)
• Cached critical manuals
• IndexedDB for local document metadata

---

4. BACKGROUND WORKERS & SERVICES

Location: /home/setup/navidocs/server/workers/ and /server/services/

A. OCR Worker

File: ocr-worker.js Function: Background processing of document uploads

• BullMQ job processor (listens to Redis queue)
• PDF text extraction via Tesseract.js or Google Vision
• Page-by-page processing with progress updates (0-100%)
• Results saved to document_pages table
• Automatic indexing in Meilisearch upon completion
• Error handling: 3 retries, then marks job as failed

Flow:

1. User uploads PDF → Document stored, OCR job created
2. Worker picks up job from queue
3. Extract text per page (calls ocr-hybrid.js)
4. Save OCR results to document_pages
5. Index each page in Meilisearch (searchable_text)
6. Update document status: processing → indexed

B. Image Extractor

File: image-extractor.js Function: Extract images from PDF pages

• Called during OCR processing
• Stores images separately for search/zoom
• Supports figure detection and metadata

C. OCR Service

File: ocr.js, ocr-hybrid.js Options:

• Local: Tesseract.js (CPU-intensive, slow)
• Cloud: Google Vision API (fast, accurate, $)
• Hybrid: Local fallback if API fails
• Configuration via OCR_LANGUAGE, OCR_CONFIDENCE_THRESHOLD

D. File Safety Service

File: file-safety.js Validation:

1. Extension check (.pdf only)
2. MIME type via magic bytes
3. File size limit (50MB)
4. Filename sanitization (no path traversal, null bytes, special chars)
5. Hash calculation for deduplication

E. Search Service

File: search.js Features:

• Meilisearch index creation and configuration
• Tenant token generation with user scoping
• Row-level security filter injection
• Synonym mapping (boat terminology)
• Page-level indexing (each PDF page = searchable document)

Meilisearch Index Schema:

{
  "indexName": "navidocs-pages",
  "primaryKey": "id",
  "searchableAttributes": ["title", "text", "systems", "categories", "tags"],
  "filterableAttributes": ["boatId", "userId", "make", "model", "year", "documentType"],
  "sortableAttributes": ["createdAt", "pageNumber"],
  "synonyms": {
    "bilge": ["sump pump", "bilge pump"],
    "engine": ["motor", "powerplant"],
    ...40+ boat terms...
  }
}

F. Section Extractor

File: section-extractor.js Purpose: Extract document structure (chapters, headings, sections)

G. Authorization Service

File: authorization.service.js Provides:

• User organization list
• Entity-level permission checks
• Role validation (admin/manager/member/viewer)
• Hierarchical permission resolution

H. Queue Service

File: queue.js Implementation: BullMQ with Redis

// Job options:
- 3 retry attempts
- Exponential backoff (2s, 4s, 8s)
- Completed jobs kept for 24 hours
- Failed jobs kept for 7 days
- Job priority support

I. Audit Service

File: audit.service.js Tracks:

• User login/logout
• Document uploads
• Permission changes
• Organization modifications
• Failed access attempts
• Data exports

J. Organization Service

File: organization.service.js Features:

• Organization CRUD
• Member invitation workflows
• Permission template application
• Org statistics (doc count, storage)

K. Settings Service

File: settings.service.js Manages:

• System configuration (app name, email settings, OCR options)
• Feature flags
• Integration credentials (for webhooks, etc.)
• Environment-specific overrides

---

5. INTEGRATION POINTS IDENTIFIED

Current State: NO External Integrations

The system is architecturally ready for integrations but none are implemented.

A. Existing Hooks & Extension Points

1. Metadata Fields (JSON)

-- Organizations
metadata TEXT  -- Custom org-level data (e.g., {"broker_id": "123", "region": "SE"})

-- Entities (boats)
metadata TEXT  -- E.g., {"hull_cert_date": "2020-01-15", "survey_status": "valid"}

-- Components
metadata TEXT  -- E.g., {"last_service": "2024-06", "service_interval_months": 12}

-- Documents
metadata TEXT  -- E.g., {"sale_list_price": "450000", "condition_notes": "excellent"}

-- Document Pages
metadata TEXT  -- Bounding boxes, OCR confidence per region

Use for yacht sales: Store listing price, condition report status, broker notes, survey dates.

2. Settings Table

system_settings (key TEXT, value TEXT, category, encrypted)

Extensible for: API keys, webhook URLs, integrations config Currently used for: OCR language, email settings, feature flags

3. Status Enum Fields

documents.status -- 'processing' | 'indexed' | 'failed' | 'archived' | 'deleted'
ocr_jobs.status  -- 'pending' | 'processing' | 'completed' | 'failed'

Extensible with: 'sold', 'transferred', 'archived_due_to_sale', 'under_inspection'

4. Background Job System

Existing: BullMQ queue for OCR Extensible for: Webhook delivery, MQTT publishing, external API calls

B. Potential Integration Points for Yacht Sales

1. Home Assistant Integration

Where: /api/webhooks/home-assistant (needs creation) Purpose:

• Publish boat documentation availability to yacht's systems
• Trigger documentation reminders based on automation rules
• Log documentation access to home automation timeline

Database Changes Needed:

-- New table
CREATE TABLE webhooks (
  id TEXT PRIMARY KEY,
  organization_id TEXT,
  type TEXT ('homeassistant', 'mqtt', 'webhook_generic'),
  endpoint_url TEXT,
  auth_token TEXT (encrypted),
  events TEXT (JSON array: ['document.uploaded', 'document.indexed', 'ocr.completed']),
  active BOOLEAN,
  created_at INTEGER
);

-- Add to metadata
-- documents.metadata: {"ha_entity_id": "sensor.boat_name_docs_updated"}
-- entities.metadata: {"ha_boat_id": "yacht_123", "automations": [...]}

Webhook Events:

{
  "event": "document.indexed",
  "timestamp": 1699868400,
  "document": {
    "id": "...",
    "title": "Engine Manual",
    "documentType": "component-manual",
    "component": { "name": "Volvo Penta D6-400", "serialNumber": "..." }
  },
  "entity": {
    "id": "...",
    "name": "35ft Yacht",
    "hull_id": "..."
  }
}

2. MQTT Broker Integration

Where: New worker /server/workers/mqtt-publisher.js Purpose:

• Publish document metadata to boat's IoT network
• Subscribe to maintenance triggers
• Real-time documentation sync to onboard displays

Topic Schema:

navidocs/organizations/{org_id}/entities/{boat_id}/documents/{type}/{component}
navidocs/organizations/{org_id}/entities/{boat_id}/maintenance/triggers

3. Broker CRM Integration (e.g., Zillow, MLS)

Where: /api/integrations/broker-crm Purpose:

• Auto-tag documents by boat listing
• Sync sale status (pending, sold, withdrawn)
• Pull boat specs from MLS into system

Database Additions:

ALTER TABLE entities ADD COLUMN mls_id TEXT;
ALTER TABLE documents ADD COLUMN crm_external_id TEXT;
-- Use metadata for broker-specific fields
-- entities.metadata: {"mls_id": "...", "listing_agent": "...", "sale_price": "..."}

4. Document Storage Integration (S3, Backblaze)

Where: File path resolution in /routes/documents.js Current: Files stored in ./uploads directory Extensible to: Cloud storage with signed URLs

Implementation Pattern:

// Current
const filePath = path.join(UPLOAD_DIR, document.file_path);
fs.readFileSync(filePath);

// Future (with integration):
if (document.storage_type === 's3') {
  return await s3.getObject(document.file_path).promise();
} else if (document.storage_type === 'local') {
  return fs.readFileSync(filePath);
}

5. Survey & Inspection APIs

Where: /api/integrations/survey-provider Purpose:

• Link boat surveys from HagsEye, DNV, etc.
• Sync inspection status to document metadata
• Auto-generate compliance documents

Data Model:

-- Survey linking
ALTER TABLE entities ADD COLUMN survey_provider_id TEXT;
-- Status tracking
-- documents.status: could add 'survey-required', 'survey-pending', 'survey-complete'
-- metadata: {"survey_date": "2024-06-15", "surveyor": "...", "next_survey": "2025-06-15"}

6. Email/Notification Integration

Existing: Partial (email reset links) Extensible to:

• Document ready notifications (OCR complete)
• Access granted notifications
• Document expiration warnings (warranty dates, inspection due)

Table Already Exists:

-- system_settings can store email provider config
-- documents.metadata: {"notify_on_expiry": true, "expiry_date": "2025-01-01"}

7. Audit & Compliance Export

Where: /api/integrations/compliance-export Purpose: Export document chain-of-custody for yacht sale closing

Existing Foundation:

-- audit_logs table tracks all document access
-- permissions table tracks who granted what access
-- documents track uploaded_by + creation date

8. Sync to Cloud Directory

Where: /api/integrations/cloud-directory Purpose: Mirror documents to client's cloud account (Google Drive, OneDrive)

Services:

• Google Drive API (already referenced in code: ocr-google-drive.js)
• OneDrive API
• Dropbox API

Implementation Path:

// New worker
/server/workers/cloud-sync-worker.js
// On document indexed:
// 1. Convert to Google Drive folder structure
// 2. Upload PDF + OCR text file
// 3. Store sync metadata in documents table

C. Current Integration Status

Implemented:

• ✅ Google Vision API (optional OCR)
• ✅ Google Drive API (referenced in services)
• ✅ Redis (BullMQ job queue)
• ✅ Meilisearch (search engine)

Partially Implemented:

• ⚠️ JWT auth (core system, but no 3rd-party OAuth)
• ⚠️ Email (password reset, not general notifications)

Not Implemented (Gaps for Yacht Sales):

• ❌ Home Assistant webhook
• ❌ MQTT publisher
• ❌ Broker CRM sync
• ❌ Cloud storage (S3, Backblaze)
• ❌ Survey provider APIs
• ❌ OAuth (Google, Microsoft, Apple sign-in)
• ❌ Notification system (beyond email)
• ❌ Document expiration alerts

---

6. OFFLINE-FIRST PWA CAPABILITIES

Existing Infrastructure

Design Document: Architecture summary mentions offline-first PWA

• Service worker caching of critical manuals
• Works 20+ miles offshore (per design spec)
• IndexedDB for local state

Not Yet Fully Implemented

• Service worker registration code not found in client/src/
• Manifest.json not created yet
• Offline mode for boat emergencies needs completion

Enhancement Opportunity for Yacht Sales

Scenario: Buyer viewing yacht specs on boat during sea trial

1. Download critical manuals before leaving shore
2. Access offline on iPad while viewing systems
3. Sync back to server when WiFi available
4. Signature capture for inspection sign-off

---

7. SECURITY ARCHITECTURE

Implemented

• ✅ JWT Auth (7-day expiry, refresh tokens)
• ✅ Tenant Scoping (Meilisearch tenant tokens, 1-hour TTL)
• ✅ File Validation (extension, magic bytes, size)
• ✅ Role-Based Access Control (admin/manager/member/viewer)
• ✅ Permission Granularity (document/entity/organization level)
• ✅ Helmet Security Headers (CSP, HSTS, etc.)
• ✅ Rate Limiting (100 req/15min default)
• ✅ Password Hashing (bcrypt)
• ✅ Audit Logging (all auth events, document access)
• ✅ Prepared Statements (SQL injection prevention)

Not Yet Fully Implemented

• ⚠️ Email verification workflow (scaffolding exists)
• ⚠️ 2FA/MFA
• ⚠️ IP whitelisting for organizations
• ⚠️ API keys for machine-to-machine auth

---

8. CURRENT CAPABILITIES VS. YACHT SALES USE CASE

Strengths

1. Multi-entity Management ✅

   • Multiple boats per broker/agency
   • Components tracked (engines, systems)
   • Hierarchical organization

2. Document Search ✅

   • Full-text OCR + Meilisearch
   • Synonym mapping (boat terms)
   • Metadata filtering (vessel type, make, model)

3. Access Control ✅

   • Share docs with buyers
   • Broker/agent team collaboration
   • Granular permissions

4. Offline Access ✅ (Design complete, implementation partial)

   • Critical manuals cached
   • Offline PWA mode

5. Compliance Tracking ✅

   • Document creation date + uploader
   • Warranty date tracking (components)
   • Survey/inspection metadata via JSON

6. Multi-tenancy ✅

   • Brokers manage multiple boats
   • Team member roles
   • Organization-level statistics

Gaps for Yacht Sales

1. No Listing Integration ❌

   • Not linked to MLS/YachtWorld data
   • Broker CRM sync not implemented

2. No Sale Workflow ❌

   • No "as-built" package generation
   • No closing checklist
   • No transfer-of-ownership flow

3. No Signature Capture ❌

   • Buyers can't sign off on receipt
   • No e-signature integration

4. Limited Notifications ❌

   • No alerts for expiring surveys/certificates
   • No "buyer accessed doc" notifications
   • No OCR completion alerts to user

5. No Media Support (Video) ❌

   • System built for documents
   • No walkthrough video links
   • No marina tour videos

6. No Real-Time Collaboration ❌

   • No commenting on specific pages
   • No annotation tools
   • No comment notifications

---

9. FILE STRUCTURE REFERENCE

/home/setup/navidocs/
├── server/
│   ├── db/
│   │   ├── schema.sql                    ← Database schema (13 tables)
│   │   ├── migrations/                   ← Schema evolution
│   │   └── db.js                         ← Connection singleton
│   │
│   ├── routes/                           ← API endpoints (12 route files)
│   │   ├── auth.routes.js                ← Login, register, password reset
│   │   ├── organization.routes.js        ← Multi-tenancy management
│   │   ├── permission.routes.js          ← Access control
│   │   ├── settings.routes.js            ← System configuration
│   │   ├── documents.js                  ← Document CRUD + ownership check
│   │   ├── upload.js                     ← File upload + OCR queue
│   │   ├── jobs.js                       ← OCR job status
│   │   ├── search.js                     ← Meilisearch tokens + search
│   │   ├── organization.routes.js        ← Org member management
│   │   ├── toc.js                        ← Table of contents
│   │   ├── images.js                     ← Image extraction from PDFs
│   │   ├── stats.js                      ← Usage statistics
│   │   └── quick-ocr.js                  ← Fast OCR endpoint
│   │
│   ├── services/
│   │   ├── auth.service.js               ← User registration, login, token refresh
│   │   ├── authorization.service.js      ← Permission checking
│   │   ├── organization.service.js       ← Org CRUD operations
│   │   ├── audit.service.js              ← Event logging
│   │   ├── settings.service.js           ← Config management
│   │   ├── queue.js                      ← BullMQ job queue
│   │   ├── search.js                     ← Meilisearch indexing
│   │   ├── file-safety.js                ← File validation
│   │   ├── ocr.js                        ← Tesseract OCR client
│   │   ├── ocr-google-vision.js          ← Google Vision API
│   │   ├── ocr-hybrid.js                 ← Fallback OCR strategy
│   │   ├── section-extractor.js          ← Document structure extraction
│   │   └── toc-extractor.js              ← TOC generation
│   │
│   ├── workers/
│   │   ├── ocr-worker.js                 ← Background OCR processor (Redis queue)
│   │   └── image-extractor.js            ← Image extraction from PDFs
│   │
│   ├── middleware/
│   │   └── auth.middleware.js            ← JWT validation + org checks
│   │
│   ├── config/
│   │   ├── db.js                         ← SQLite config
│   │   ├── meilisearch.js                ← Search engine config
│   │   └── redis.js                      ← Job queue config
│   │
│   ├── index.js                          ← Express server + route mounting
│   └── package.json
│
├── client/
│   ├── src/
│   │   ├── views/                        ← Page components
│   │   │   ├── HomeView.vue              ← Dashboard
│   │   │   ├── LibraryView.vue           ← Document browser
│   │   │   ├── SearchView.vue            ← Full-text search
│   │   │   ├── DocumentView.vue          ← PDF viewer
│   │   │   ├── AuthView.vue              ← Login/signup
│   │   │   ├── AccountView.vue           ← User profile
│   │   │   └── JobsView.vue              ← Upload progress
│   │   │
│   │   ├── components/                   ← Reusable UI components
│   │   │   ├── UploadModal.vue           ← Drag-drop upload
│   │   │   ├── DocumentView.vue          ← PDF.js viewer
│   │   │   ├── TocSidebar.vue            ← TOC navigation
│   │   │   ├── ImageOverlay.vue          ← Full-screen images
│   │   │   ├── ToastContainer.vue        ← Notifications
│   │   │   └── ... (8 more components)
│   │   │
│   │   ├── router.js                     ← Vue Router configuration
│   │   ├── App.vue                       ← Root component
│   │   └── main.js                       ← Entry point
│   │
│   └── package.json
│
└── docs/
    ├── ARCHITECTURE-SUMMARY.md           ← Design overview
    ├── DESIGN_AUTH_MULTITENANCY.md       ← Auth system spec
    ├── API_SUMMARY.md                    ← API documentation
    └── [39 other analysis/design docs]

---

10. RECOMMENDED INTEGRATION ROADMAP

Phase 1: Quick Wins (Week 1-2)

1. Settings UI for Webhook Configuration

   • Store Home Assistant webhook URL in system_settings
   • Enable/disable per organization
   • Test webhook delivery

2. Metadata Templates for Yacht Sales

   • Add "vessel_specs" template (HIN, survey date, condition notes)
   • Add "sale_info" template (list price, broker ID, showings)
   • Add "buyer_info" template (name, contact, purchase contingencies)

3. Status Enhancements

   • Extend document.status to include 'sale-package', 'transferred'
   • Add document.expiry_date for survey/inspection tracking

Phase 2: Core Integrations (Week 3-4)

1. Home Assistant Webhook Handler

   • /api/webhooks/home-assistant endpoint
   • Publish document indexed/uploaded events
   • Subscribe to boat status changes

2. Notification System

   • Email notifications when docs ready
   • Expiration warnings (surveys, warranties)
   • Access notifications to seller/broker

3. Cloud Storage Option

   • S3/Backblaze as alternative to local disk
   • Signed URL generation for downloads

Phase 3: Automation (Week 5-6)

1. As-Built Package Generator

   • Collect all boat documents
   • Generate PDF with index
   • Auto-upload to Google Drive for buyer

2. Broker CRM Sync (if connecting to external CRM)

   • Sync boat data from MLS
   • Tag documents by listing
   • Update sale status in NaviDocs

3. MQTT Integration

   • Publish doc metadata to boat's IoT network
   • Real-time sync for onboard displays

---

11. DATABASE MIGRATION PLAN

To support integrations without breaking changes:

-- New table for external integrations
CREATE TABLE integrations (
  id TEXT PRIMARY KEY,
  organization_id TEXT NOT NULL,
  type TEXT NOT NULL,  -- 'webhook', 'mqtt', 'crm', 'cloud_storage'
  name TEXT,
  config TEXT NOT NULL,  -- JSON: {url, auth, events_enabled, etc}
  active BOOLEAN DEFAULT 1,
  created_at INTEGER,
  updated_at INTEGER,
  FOREIGN KEY (organization_id) REFERENCES organizations(id) ON DELETE CASCADE
);

-- Track integration events
CREATE TABLE integration_events (
  id TEXT PRIMARY KEY,
  integration_id TEXT NOT NULL,
  event_type TEXT,  -- 'document.uploaded', 'document.indexed', etc
  document_id TEXT,
  payload TEXT,  -- JSON: full event data
  status TEXT,  -- 'pending', 'delivered', 'failed'
  retry_count INTEGER DEFAULT 0,
  created_at INTEGER,
  FOREIGN KEY (integration_id) REFERENCES integrations(id) ON DELETE CASCADE,
  FOREIGN KEY (document_id) REFERENCES documents(id) ON DELETE SET NULL
);

-- Extend documents for sale workflow
ALTER TABLE documents ADD COLUMN sale_package_id TEXT;  -- Links related docs
ALTER TABLE documents ADD COLUMN requires_signature BOOLEAN DEFAULT 0;
ALTER TABLE documents ADD COLUMN signature_metadata TEXT;  -- {signer, timestamp, ip}

---

12. SUMMARY: READY FOR INTEGRATION

✅ Foundation Complete

• Multi-tenancy architecture solid
• API design extensible
• Service layer pattern established
• Background job system in place
• Metadata fields support custom data

⚠️ Needs Implementation

• Integration management UI
• Webhook delivery system
• Home Assistant/MQTT publishers
• Notification queue
• E-signature support
• Sale workflow automation

🎯 Yacht Sales Specific

The schema is PERFECT for boat documentation because:

1. Entities = individual boats with full specs
2. Components = engines, systems, equipment (trackable by serial #)
3. Document types support all manuals, service records, surveys
4. Metadata allows custom broker fields (price, condition, showings)
5. Multi-tenancy supports broker teams + multiple boats
6. Offline PWA supports sea trial scenarios
7. Access control handles buyer access management

Next Steps:

1. Add Home Assistant integration (highest ROI for smart yacht ecosystem)
2. Build yacht sales-specific metadata templates
3. Create "as-built package" generator for closing
4. Add notification system for time-sensitive docs (surveys, warranties)