navidocs/CLOUD_SESSION_4_IMPLEMENTATION_PLANNING.md

Cloud Session 4: Implementation Planning

NaviDocs Sticky Engagement Features - 4-Week Sprint

Session Type: Project Manager + DevOps Specialist Lead Agent: Sonnet (planning + coordination) Swarm Size: 10 Haiku agents Token Budget: $15 (7.5K Sonnet + 50K Haiku) Output: Sprint plan for inventory tracking + cameras + maintenance + contacts + search UX

---

Mission Statement

Create detailed 4-week implementation plan with task breakdown, dependencies, acceptance criteria, and testing strategy for NaviDocs yacht sales features.

---

Context (Read First)

Prerequisites:

1. Read intelligence/session-2/session-2-architecture.md
2. Read intelligence/session-2/session-2-sprint-plan.md
3. Read server/db/schema.sql - Current database structure
4. Read server/routes/*.js - Existing API patterns

Technical Constraints:

• Backend: Express.js (must maintain compatibility)
• Database: SQLite (migration-friendly approach)
• Queue: BullMQ (extend existing workers)
• Frontend: Vue 3 (add new components, don't break existing)

Team Size: 1 developer (solo sprint) Working Hours: 6-8 hours/day Timeline: 4 weeks (Nov 13 - Dec 10)

---

Agent Identity & Check-In Protocol

YOU ARE: Sonnet coordinator for Session 4 (Implementation Planning)

YOUR HAIKU SWARM: You have 10 Haiku agents available. Use as many as needed (not required to use all 10).

AGENT IDENTITY SYSTEM: When spawning a Haiku agent, assign it an identity: S4-H01 through S4-H10 Each agent MUST:

1. Check in at start: "I am S4-H03, assigned to [task name]"
2. Reference their task by searching this document for "Agent 3:" (matching their number)
3. Retain identity throughout execution
4. Report completion with identity: "S4-H03 complete: [deliverable summary]"

TASK DEPENDENCIES:

• Most agents can run in parallel
• Agent 10 typically synthesizes results from Agents 1-9 (must wait for completion)

---

Your Tasks (Spawn 10 Haiku Agents in Parallel)

Agent 1: Week 1 Task Breakdown

AGENT ID: S4-H01 ** Create:

• Day-by-day tasks for foundation week
• Database migrations (warranty tracking, webhooks, notifications)
• Event bus implementation (IF.bus pattern)
• Security fixes (5 vulnerabilities from handover doc)
• Time estimates per task (granular, 2-4 hour blocks)

Deliverable: Week 1 detailed schedule with dependencies

Agent 2: Week 2 Task Breakdown

AGENT ID: S4-H02 ** Create:

• Day-by-day tasks for core integrations
• Warranty tracking APIs (CRUD + expiration alerts)
• Home Assistant webhook integration
• Background job for expiration checks
• Time estimates + dependency mapping

Deliverable: Week 2 detailed schedule

Agent 3: Week 3 Task Breakdown

AGENT ID: S4-H03 ** Create:

• Day-by-day tasks for automation features
• Sale workflow (as-built package generator)
• Notification system (email, SMS, in-app)
• Offline mode (service worker, critical manual caching)
• Time estimates + dependencies

Deliverable: Week 3 detailed schedule

Agent 4: Week 4 Task Breakdown

AGENT ID: S4-H04 ** Create:

• Day-by-day tasks for polish & deployment
• MLS integration (YachtWorld, Boat Trader APIs)
• E2E testing suite
• Security audit
• Production deployment checklist

Deliverable: Week 4 detailed schedule

Agent 5: Acceptance Criteria Writer

AGENT ID: S4-H05 ** Define:

• Feature-level acceptance criteria (Given/When/Then format)
• API endpoint acceptance tests
• UI component acceptance criteria
• Performance benchmarks (load times, query speeds)

Deliverable: Acceptance criteria document (all features)

Agent 6: Testing Strategy Designer

AGENT ID: S4-H06 ** Create:

• Unit test plan (service layer, utilities)
• Integration test plan (API endpoints, database)
• E2E test plan (critical user flows)
• Test data generation strategy

Deliverable: Testing strategy document with tooling recommendations

Agent 7: Dependency Mapper

AGENT ID: S4-H07 ** Analyze:

• Task dependencies (Gantt chart format)
• Critical path identification
• Parallel work opportunities
• Risk areas (blockers, unknowns)

Deliverable: Dependency graph (Mermaid Gantt or visual)

Agent 8: API Specification Writer

AGENT ID: S4-H08 ** Document:

• All new API endpoints (OpenAPI 3.0 format)
• Request/response schemas
• Error codes and handling
• Authentication requirements

Deliverable: OpenAPI spec file (api-spec.yaml)

Agent 9: Database Migration Planner

AGENT ID: S4-H09 ** Create:

• Migration scripts (up/down for each change)
• Data backups strategy
• Rollback procedures
• Migration testing plan

Deliverable: Migration scripts + rollback guide

Agent 10: Deployment Checklist Creator

AGENT ID: S4-H10 ** Compile:

• Pre-deployment checklist (backups, tests, env vars)
• Deployment steps (zero-downtime strategy)
• Post-deployment validation (smoke tests)
• Rollback procedure (if deployment fails)

Deliverable: Deployment runbook

---

Intra-Agent Communication Protocol (IF.bus)

Based on: InfraFabric S² multi-swarm coordination (3,563x faster than git polling)

IFMessage Schema

Every agent-to-agent message follows this structure:

{
  "performative": "inform",  // FIPA-ACL: inform, request, query-if, confirm, disconfirm, ESCALATE
  "sender": "if://agent/session-4/haiku-Y",
  "receiver": ["if://agent/session-4/haiku-Z"],
  "conversation_id": "if://conversation/navidocs-session-4-2025-11-13",
  "content": {
    "claim": "[Week N deliverables/blockers]",
    "evidence": ["[Task completion status, test results]"],
    "confidence": 0.85,  // 0.0-1.0
    "cost_tokens": 1247
  },
  "citation_ids": ["if://citation/uuid"],
  "timestamp": "2025-11-13T10:00:00Z",
  "sequence_num": 1
}

Speech Acts (Performatives)

inform: Share week deliverables with next week's agent

• Example: "S4-H01 informs S4-H02: Week 1 foundation complete (DB migrations, Event Bus tested)"

request: Ask about dependencies before proceeding

• Example: "S4-H02 requests S4-H01: Confirm DB migrations deployed and tested"

confirm: Validate previous week's work

• Example: "S4-H02 confirms S4-H01: Database migrations executed successfully on dev"

disconfirm: Flag blockers from previous week

• Example: "S4-H02 disconfirms: Event Bus tests failing - need S4-H01 to investigate"

ESCALATE: Flag critical timeline risk

• Example: "S4-H03 ESCALATES: Week 2 not complete, blocks Week 3 sale workflow"

Communication Flow (This Session)

S4-H01 (Week 1) ──→ S4-H02 (Week 2) ──→ S4-H03 (Week 3) ──→ S4-H04 (Week 4) ──→ S4-H10
   ↓ handoff         ↓ handoff         ↓ handoff         ↓ handoff

Key Patterns:

1. Sequential Handoffs: Week N agent sends deliverables + blockers to Week N+1
2. Dependency Validation: Week N checks if Week N-1 unblocks their tasks
3. Progress Tracking: Each agent tracks token cost + time spent
4. Agent 10 Synthesis: Ensures 4-week roadmap is coherent and on-track

Week Handoff Example

# End of Week 1 (S4-H01)
S4-H01: "inform" → content:
  week: 1
  status: "COMPLETE"
  deliverables: [
    "DB migrations: warranty_tracking, webhooks, notification_templates",
    "Event bus service: IF.bus messaging system",
    "Security fixes: DELETE endpoint protection, auth enforcement",
    "Background jobs: warranty expiration worker"
  ]
  tests_passed: 23/23
  blockers: []
  ready_for_week_2: true

# S4-H02 validates Week 1 and confirms readiness
S4-H02: "confirm" → content:
  week: 1
  validation: "All migrations tested on dev. Event bus ready for Week 2 warranty APIs."
  week_2_dependencies: [
    "DB migrations (ready)",
    "Event bus service (ready)",
    "Security fixes (ready)"
  ]
  can_start_week_2: true

# S4-H02 executes Week 2 and reports progress
S4-H02: "inform" → content:
  week: 2
  status: "IN_PROGRESS"
  progress: "Warranty APIs 60% complete (CRUD done, expiring endpoint 80%)"
  blockers: ["Home Assistant integration needs webhook URL format validation"]

Critical Path Conflict Example

# S4-H03 (Week 3) reports blocker
S4-H03: "disconfirm" → content:
  week: 3
  blocker: "Sale workflow requires DB schema from Week 2, but S4-H02 incomplete"
  missing: "webhooks table not migrated yet"
  impact: "Cannot implement sale_workflows table migration"
  estimated_delay: "1-2 days"

# S4-H10 escalates to coordinator
S4-H10: "ESCALATE" → content:
  critical_blocker: "Week 2 delays cascading to Week 3"
  chain_affected: ["Week 3", "Week 4"]
  recommendation: "Prioritize webhooks table migration immediately (2-hour task)"

# Sonnet coordinator responds
Coordinator: "request" → S4-H02: "Prioritize webhooks migration today (deadline noon)"

# S4-H02 confirms
S4-H02: "confirm" → content:
  priority_shift: "Moved webhooks migration to top of queue"
  eta: "9am completion"
  unblocks: "S4-H03 can start sale workflow design by noon"

Token Cost Tracking (IF.optimise)

Every handoff message includes cost tracking:

S4-H01: "inform" → content:
  tokens_used: 8750
  tokens_budgeted: 12500
  efficiency: 70%
  cost_usd: 0.14
  remaining_budget: 3750

IF.TTT Compliance

Every message MUST include:

• citation_ids: Links to task specs, test results
• confidence: Explicit score on deliverable completeness (0.0-1.0)
• evidence: Test counts, git commits, code reviews
• cost_tokens: Token consumption (IF.optimise tracking)

---

Week 1: Foundation (Nov 13-19)

Day 1 (Nov 13): Database Migrations

Morning (4 hours):

• Create warranty_tracking table
  • Columns: id, boat_id, item_name, provider, purchase_date, warranty_period_months, expiration_date, coverage_amount, claim_instructions, status
  • Indexes: boat_id, expiration_date, status
  • Migration script: migrations/20251113_add_warranty_tracking.sql

Afternoon (3 hours):

• Create sale_workflows table
  • Columns: id, boat_id, initiated_by, buyer_email, status, transfer_date, documents_generated
  • Migration script: migrations/20251113_add_sale_workflows.sql
• Create webhooks table
  • Columns: id, organization_id, url, topics (JSON), secret, status, created_at
  • Migration script: migrations/20251113_add_webhooks.sql

Testing:

• Run migrations on dev database
• Verify rollback scripts work
• Check indexes created correctly

Acceptance Criteria:

• Given new tables created, When querying schema, Then all columns and indexes exist
• Given migration rollback executed, When checking schema, Then tables removed cleanly

Day 2 (Nov 13): Event Bus Implementation

Morning (4 hours):

• Create server/services/event-bus.service.js
  • Redis pub/sub integration
  • Topic-based routing (WARRANTY_EXPIRING, DOCUMENT_UPLOADED, etc.)
  • Event logging to audit trail
  • Error handling (retry logic)

Afternoon (3 hours):

• Create server/services/webhook.service.js
  • HTTP POST to external URLs
  • Exponential backoff retry (3 attempts)
  • Webhook delivery status tracking
  • Signature generation (HMAC-SHA256)

Testing:

• Unit tests for event publishing
• Unit tests for webhook delivery
• Integration test: event → webhook delivery

Acceptance Criteria:

• Given event published, When subscribers listening, Then event delivered within 100ms
• Given webhook URL fails, When retry triggered, Then exponential backoff applied (1s, 2s, 4s)

Day 3 (Nov 14): Security Fixes

Morning (4 hours):

• Fix DELETE endpoint protection

  • Add ownership verification (user can only delete own boats)
  • Add soft delete (mark as deleted, don't remove)
  • Update server/routes/boat.routes.js

• Enforce auth on all routes

  • Audit server/routes/*.js for missing authenticateToken middleware
  • Add auth to stats endpoint (server/routes/stats.routes.js)

Afternoon (2 hours):

• Fix stats endpoint tenant isolation
  • Filter stats by organization_id
  • Add integration test (user can't see other org stats)

Testing:

• Security tests (unauthorized access attempts)
• Tenant isolation tests (cross-organization data leaks)

Acceptance Criteria:

• Given unauthorized user, When attempting DELETE, Then return 403 Forbidden
• Given user from Org A, When requesting stats, Then only Org A data returned

Day 4 (Nov 15): Notification Templates

Morning (3 hours):

• Create notification_templates table
  • Columns: id, type (email/sms/push), event_type, subject, body, variables (JSON)
  • Seed templates: WARRANTY_EXPIRING (90/30/14 day variants)

Afternoon (4 hours):

• Create server/services/notification.service.js
  • Email sending (Nodemailer integration)
  • Template rendering (variable substitution)
  • Notification queue (BullMQ job)

Testing:

• Unit test: template rendering with variables
• Integration test: email sent via queue

Acceptance Criteria:

• Given WARRANTY_EXPIRING event, When notification triggered, Then email sent with correct warranty details

Day 5 (Nov 16): Background Jobs

Morning (4 hours):

• Create server/workers/warranty-expiration.worker.js
  • Daily job: check warranties expiring in 90/30/14 days
  • Publish WARRANTY_EXPIRING events
  • Mark notifications sent (avoid duplicates)

Afternoon (3 hours):

• Register worker with BullMQ
  • Update server/index.js to start worker
  • Add worker health check endpoint

Testing:

• Integration test: worker finds expiring warranties
• Integration test: events published correctly

Acceptance Criteria:

• Given warranty expires in 30 days, When worker runs, Then WARRANTY_EXPIRING event published
• Given notification already sent, When worker runs again, Then duplicate not sent

---

Week 2: Core Integrations (Nov 20-26)

Day 1-2 (Nov 20-21): Warranty Tracking APIs

Day 1 Morning (4 hours):

• Create server/routes/warranty.routes.js
  • POST /api/warranties (create)
  • GET /api/warranties/:id (read)
  • PUT /api/warranties/:id (update)
  • DELETE /api/warranties/:id (soft delete)

Day 1 Afternoon (3 hours):

• Create server/services/warranty.service.js
  • Business logic: calculate expiration dates
  • Validation: warranty period constraints
  • Database operations (CRUD)

Day 2 Morning (4 hours):

• Create GET /api/warranties/expiring endpoint
  • Query params: days (90/30/14), boat_id (filter)
  • Return warranties + days until expiration
  • Sort by expiration date (ascending)

Day 2 Afternoon (3 hours):

• Create GET /api/boats/:id/warranties endpoint
  • Return all warranties for specific boat
  • Include expired warranties (flagged)
  • Total coverage amount calculation

Testing:

• API integration tests (all endpoints)
• Authorization tests (tenant isolation)

Acceptance Criteria:

• Given authenticated user, When POST /api/warranties, Then warranty created with calculated expiration
• Given boat with 3 warranties, When GET /api/boats/:id/warranties, Then all 3 returned with total coverage

Day 3-5 (Nov 22-24): Home Assistant Integration

Day 3 Morning (4 hours):

• Create server/routes/integrations.routes.js
  • POST /api/integrations/home-assistant (register webhook)
  • GET /api/integrations/home-assistant (get config)
  • DELETE /api/integrations/home-assistant (remove)

Day 3 Afternoon (3 hours):

• Create server/services/home-assistant.service.js
  • Webhook URL validation (reachability check)
  • Event forwarding (NaviDocs event → HA webhook)
  • Retry logic (exponential backoff)

Day 4 Morning (4 hours):

• Create Home Assistant automation examples
  • YAML config: warranty expiration → notification
  • YAML config: document uploaded → log entry
  • Documentation: docs/home-assistant-integration.md

Day 4 Afternoon (3 hours):

• MQTT integration (optional stretch goal)
  • Research MQTT.js library
  • Design topic structure (navidocs/boat/{id}/warranty/expiring)
  • Prototype event publishing to MQTT broker

Day 5 (7 hours):

• Camera system integration (optional stretch goal)
  • Research Home Assistant camera APIs
  • Design snapshot storage (link to NaviDocs documents)
  • Prototype: camera snapshot → upload to NaviDocs

Testing:

• Integration test: NaviDocs event → HA webhook delivery
• Manual test: HA automation triggered by NaviDocs event

Acceptance Criteria:

• Given HA webhook registered, When WARRANTY_EXPIRING event, Then HA receives POST with event data
• Given MQTT broker configured, When document uploaded, Then MQTT topic published

---

Week 3: Automation (Nov 27 - Dec 3)

Day 1-2 (Nov 27-28): Sale Workflow

Day 1 Morning (4 hours):

• Create server/services/sale-workflow.service.js
  • POST /api/sales (initiate sale)
  • GET /api/sales/:id (get sale status)
  • POST /api/sales/:id/generate-package (as-built package)

Day 1 Afternoon (3 hours):

• As-built package generator
  • Gather all boat documents (registration, surveys, warranties)
  • Generate cover letter (template with boat details)
  • Create ZIP archive with organized folders

Day 2 Morning (4 hours):

• Document transfer workflow
  • POST /api/sales/:id/transfer (mark documents transferred)
  • Send buyer access email (with download link)
  • Log transfer event (audit trail)

Day 2 Afternoon (3 hours):

• Buyer handoff notification
  • Email template: "Your yacht documentation package"
  • Include warranty summary, important dates
  • Download link (expiring in 30 days)

Testing:

• Integration test: sale initiated → package generated
• E2E test: full sale workflow (initiate → generate → transfer)

Acceptance Criteria:

• Given boat with 10 documents, When generate package, Then ZIP contains all docs in organized folders
• Given sale transferred, When buyer receives email, Then download link works and expires in 30 days

Day 3-4 (Nov 29-30): Notification System

Day 3 Morning (4 hours):

• Email service implementation
  • Nodemailer configuration (SMTP settings)
  • Template system (Handlebars or EJS)
  • Email queue (BullMQ job)

Day 3 Afternoon (3 hours):

• SMS gateway integration (Twilio or similar)
  • Research SMS provider APIs
  • Design SMS template system
  • Implement sending logic

Day 4 Morning (4 hours):

• In-app notification center
  • Create notifications table (id, user_id, type, message, read, created_at)
  • GET /api/notifications (user's notifications)
  • PUT /api/notifications/:id/read (mark as read)

Day 4 Afternoon (3 hours):

• Push notifications (PWA)
  • Service worker push subscription
  • Web Push API integration
  • Notification permission request UI

Testing:

• Email delivery test (dev SMTP server)
• In-app notification test (create + read)

Acceptance Criteria:

• Given WARRANTY_EXPIRING event, When notification sent, Then email delivered within 5 minutes
• Given user logged in, When notification created, Then appears in notification center

Day 5 (Dec 1): Offline Mode

Morning (4 hours):

• Service worker caching strategy
  • Cache-first for static assets (/_next/, /assets/)
  • Network-first for API calls
  • Offline fallback page

Afternoon (3 hours):

• Critical manual pre-caching
  • Engine manuals (PDF files)
  • Safety documents (emergency procedures)
  • Offline sync queue (IndexedDB)

Testing:

• Offline test: disconnect network, verify cached content loads
• Sync test: reconnect network, verify queued uploads process

Acceptance Criteria:

• Given offline mode, When user accesses critical manuals, Then PDFs load from cache
• Given offline edits made, When network restored, Then changes sync automatically

---

Week 4: Polish & Deploy (Dec 4-10)

Day 1-2 (Dec 4-5): MLS Integration

Day 1 Morning (4 hours):

• Research YachtWorld API
  • Authentication (API key vs OAuth)
  • Listing endpoints (create, update, get)
  • Documentation upload endpoints

Day 1 Afternoon (3 hours):

• Create server/services/yachtworld.service.js
  • API client setup
  • Listing sync (NaviDocs boat → YachtWorld listing)
  • Document attachment (warranties, surveys)

Day 2 Morning (4 hours):

• Research Boat Trader API (similar to YachtWorld)
• Design unified MLS abstraction layer
  • Interface: IMLSProvider (create, update, sync methods)
  • Implementations: YachtWorldProvider, BoatTraderProvider

Day 2 Afternoon (3 hours):

• MLS sync background job
  • Daily job: sync boat data to configured MLS platforms
  • Update listing status (sold, pending, available)

Testing:

• Integration test: NaviDocs boat → YachtWorld listing created
• Manual test: verify listing appears on YachtWorld website

Acceptance Criteria:

• Given boat marked for sale, When MLS sync runs, Then YachtWorld listing created with documents

Day 3 (Dec 6): E2E Testing

Morning (4 hours):

• Set up Playwright or Cypress
• E2E test: user registration → boat creation → document upload
• E2E test: warranty tracking → expiration alert → claim package

Afternoon (3 hours):

• E2E test: sale workflow (initiate → generate package → transfer)
• E2E test: Home Assistant integration (event → webhook delivery)

Acceptance Criteria:

• Given E2E test suite, When run against demo environment, Then all tests pass

Day 4 (Dec 7): Security Audit

Morning (3 hours):

• Run OWASP dependency check
• SQL injection testing (parameterized queries verified)
• XSS testing (input sanitization verified)

Afternoon (4 hours):

• Authentication audit (JWT expiration, refresh tokens)
• Authorization audit (tenant isolation, role-based access)
• Secrets management (env vars, no hardcoded keys)

Acceptance Criteria:

• Given security audit, When vulnerabilities found, Then all high/critical issues fixed

Day 5 (Dec 8-10): Production Deployment

Dec 8 Morning (4 hours):

• Pre-deployment checklist
  • Database backup (SQLite file copy)
  • Environment variables configured
  • SSL certificate valid

Dec 8 Afternoon (3 hours):

• Deploy to production
  • Stop server
  • Run database migrations
  • Deploy new code (git pull + npm install)
  • Restart server

Dec 9 (7 hours):

• Post-deployment validation
  • Smoke tests (critical endpoints functional)
  • Performance testing (load times, query speeds)
  • Monitor error logs (first 24 hours)

Dec 10 (7 hours):

• Riviera Plaisance pilot setup
  • Create demo account
  • Import sample boat data
  • Configure Home Assistant webhook
  • Train Sylvain on system

Acceptance Criteria:

• Given production deployment, When smoke tests run, Then all critical flows functional
• Given Riviera pilot account, When Sylvain logs in, Then demo boat with warranties visible

---

Acceptance Criteria (Master List)

Warranty Tracking Feature

Feature: Warranty Expiration Tracking

Scenario: Create warranty with automatic expiration calculation
  Given authenticated user
  And boat with id "boat-123"
  When POST /api/warranties with:
    | boat_id | item_name | purchase_date | warranty_period_months |
    | boat-123 | Engine | 2023-01-15 | 24 |
  Then warranty created with expiration_date "2025-01-15"
  And response status 201

Scenario: Expiration alert triggered 30 days before
  Given warranty expires on "2025-12-13"
  And current date is "2025-11-13"
  When warranty expiration worker runs
  Then WARRANTY_EXPIRING event published
  And notification sent to boat owner

Scenario: Claim package generation
  Given warranty expiring in 14 days
  When POST /api/warranties/:id/generate-claim-package
  Then ZIP file returned containing:
    | warranty document |
    | purchase invoice |
    | claim form (jurisdiction-specific) |

Home Assistant Integration

Feature: Home Assistant Webhook Integration

Scenario: Register Home Assistant webhook
  Given authenticated user
  When POST /api/integrations/home-assistant with:
    | url | topics |
    | https://ha.example.com/api/webhook/navidocs | ["WARRANTY_EXPIRING", "DOCUMENT_UPLOADED"] |
  Then webhook registered
  And reachability check passed

Scenario: Event forwarding to Home Assistant
  Given HA webhook registered for "WARRANTY_EXPIRING"
  When WARRANTY_EXPIRING event published
  Then POST sent to HA webhook within 5 seconds
  And HA webhook receives event with warranty details

Sale Workflow

Feature: Yacht Sale Workflow

Scenario: Generate as-built package
  Given boat with 10 documents
  When POST /api/sales/:id/generate-package
  Then ZIP file created with organized folders:
    | Registration |
    | Surveys |
    | Warranties |
    | Engine Manuals |
  And generation time < 30 seconds

Scenario: Transfer documents to buyer
  Given sale with generated package
  When POST /api/sales/:id/transfer with buyer_email
  Then buyer receives email with download link
  And link expires in 30 days
  And transfer logged in audit trail

---

Testing Strategy

Unit Tests (Target: 70% Coverage)

Tools: Mocha + Chai Scope:

• Service layer functions (warranty calculations, validation)
• Utility functions (date helpers, string formatting)
• Middleware (auth, error handling)

Example:

// test/services/warranty.service.test.js
describe('WarrantyService', () => {
  describe('calculateExpirationDate', () => {
    it('should add warranty period to purchase date', () => {
      const purchaseDate = '2023-01-15';
      const warrantyMonths = 24;
      const result = warrantyService.calculateExpirationDate(purchaseDate, warrantyMonths);
      expect(result).to.equal('2025-01-15');
    });
  });
});

Integration Tests (Target: 50% Coverage)

Tools: Supertest + SQLite in-memory Scope:

• API endpoints (request/response validation)
• Database operations (CRUD, migrations)
• Background jobs (worker execution)

Example:

// test/routes/warranty.routes.test.js
describe('POST /api/warranties', () => {
  it('should create warranty with valid data', async () => {
    const response = await request(app)
      .post('/api/warranties')
      .set('Authorization', `Bearer ${validToken}`)
      .send({
        boat_id: 'boat-123',
        item_name: 'Engine',
        purchase_date: '2023-01-15',
        warranty_period_months: 24
      });

    expect(response.status).to.equal(201);
    expect(response.body.expiration_date).to.equal('2025-01-15');
  });
});

E2E Tests (Target: 10 Critical Flows)

Tools: Playwright Scope:

• User registration → boat creation → warranty tracking
• Warranty expiration alert → claim package generation
• Sale initiation → package generation → buyer transfer
• Home Assistant webhook registration → event delivery

Example:

// e2e/warranty-tracking.spec.js
test('warranty expiration alert flow', async ({ page }) => {
  await page.goto('https://demo.navidocs.app');
  await page.fill('#email', 'demo@example.com');
  await page.fill('#password', 'password');
  await page.click('#login-button');

  // Navigate to boat with expiring warranty
  await page.click('text=Azimut 55S');

  // Verify warranty alert badge
  await expect(page.locator('.warranty-alert')).toHaveText('Expires in 28 days');

  // Generate claim package
  await page.click('#generate-claim-package');
  await expect(page.locator('.download-link')).toBeVisible();
});

---

Dependency Graph (Gantt Chart)

gantt
    title NaviDocs 4-Week Sprint
    dateFormat  YYYY-MM-DD
    section Week 1
    DB Migrations           :done, w1d1, 2025-11-13, 1d
    Event Bus               :done, w1d2, 2025-11-13, 1d
    Security Fixes          :w1d3, 2025-11-14, 1d
    Notification Templates  :w1d4, 2025-11-15, 1d
    Background Jobs         :w1d5, after w1d4, 1d

    section Week 2
    Warranty APIs           :w2d1, 2025-11-20, 2d
    Home Assistant          :w2d3, after w2d1, 3d

    section Week 3
    Sale Workflow           :w3d1, 2025-11-27, 2d
    Notification System     :w3d3, after w3d1, 2d
    Offline Mode            :w3d5, after w3d3, 1d

    section Week 4
    MLS Integration         :w4d1, 2025-12-04, 2d
    E2E Testing             :w4d3, after w4d1, 1d
    Security Audit          :w4d4, after w4d3, 1d
    Production Deploy       :w4d5, after w4d4, 3d

Critical Path: DB Migrations → Event Bus → Background Jobs → Warranty APIs → E2E Testing → Deploy

Parallel Opportunities:

• Week 2: Home Assistant work can run parallel to Warranty APIs (if different developer)
• Week 3: Offline Mode can run parallel to Notification System
• Week 4: MLS Integration is optional (can defer to Week 5 if needed)

---

API Specification (OpenAPI 3.0)

openapi: 3.0.0
info:
  title: NaviDocs Yacht Sales API
  version: 1.0.0
  description: Warranty tracking, sale workflow, and integrations for yacht documentation

servers:
  - url: https://api.navidocs.app/v1
    description: Production
  - url: http://localhost:3000/api
    description: Development

paths:
  /warranties:
    post:
      summary: Create warranty
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - boat_id
                - item_name
                - purchase_date
                - warranty_period_months
              properties:
                boat_id:
                  type: string
                  example: "boat-123"
                item_name:
                  type: string
                  example: "Engine"
                provider:
                  type: string
                  example: "Caterpillar"
                purchase_date:
                  type: string
                  format: date
                  example: "2023-01-15"
                warranty_period_months:
                  type: integer
                  example: 24
                coverage_amount:
                  type: number
                  example: 50000
      responses:
        '201':
          description: Warranty created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Warranty'
        '401':
          description: Unauthorized
        '400':
          description: Invalid input

  /warranties/expiring:
    get:
      summary: Get expiring warranties
      security:
        - bearerAuth: []
      parameters:
        - name: days
          in: query
          schema:
            type: integer
            enum: [90, 30, 14]
            default: 30
        - name: boat_id
          in: query
          schema:
            type: string
      responses:
        '200':
          description: List of expiring warranties
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Warranty'

  /sales:
    post:
      summary: Initiate yacht sale
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - boat_id
                - buyer_email
              properties:
                boat_id:
                  type: string
                buyer_email:
                  type: string
                  format: email
      responses:
        '201':
          description: Sale initiated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Sale'

  /sales/{id}/generate-package:
    post:
      summary: Generate as-built package
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: ZIP file with documentation
          content:
            application/zip:
              schema:
                type: string
                format: binary

components:
  schemas:
    Warranty:
      type: object
      properties:
        id:
          type: string
        boat_id:
          type: string
        item_name:
          type: string
        provider:
          type: string
        purchase_date:
          type: string
          format: date
        warranty_period_months:
          type: integer
        expiration_date:
          type: string
          format: date
        coverage_amount:
          type: number
        status:
          type: string
          enum: [active, expired, claimed]
        created_at:
          type: string
          format: date-time

    Sale:
      type: object
      properties:
        id:
          type: string
        boat_id:
          type: string
        buyer_email:
          type: string
        status:
          type: string
          enum: [initiated, package_generated, transferred, completed]
        created_at:
          type: string
          format: date-time

  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

---

Database Migration Scripts

Migration: Add Warranty Tracking

File: migrations/20251113_add_warranty_tracking.sql

-- Up Migration
CREATE TABLE IF NOT EXISTS warranty_tracking (
  id TEXT PRIMARY KEY DEFAULT (lower(hex(randomblob(16)))),
  boat_id TEXT NOT NULL,
  item_name TEXT NOT NULL,
  provider TEXT,
  purchase_date TEXT NOT NULL,
  warranty_period_months INTEGER NOT NULL,
  expiration_date TEXT NOT NULL,
  coverage_amount REAL,
  claim_instructions TEXT,
  status TEXT DEFAULT 'active' CHECK(status IN ('active', 'expired', 'claimed')),
  created_at TEXT DEFAULT (datetime('now')),
  updated_at TEXT DEFAULT (datetime('now')),
  FOREIGN KEY (boat_id) REFERENCES boats(id) ON DELETE CASCADE
);

CREATE INDEX idx_warranty_boat_id ON warranty_tracking(boat_id);
CREATE INDEX idx_warranty_expiration ON warranty_tracking(expiration_date);
CREATE INDEX idx_warranty_status ON warranty_tracking(status);

-- Down Migration (Rollback)
-- DROP INDEX idx_warranty_status;
-- DROP INDEX idx_warranty_expiration;
-- DROP INDEX idx_warranty_boat_id;
-- DROP TABLE warranty_tracking;

Migration: Add Webhooks

File: migrations/20251113_add_webhooks.sql

-- Up Migration
CREATE TABLE IF NOT EXISTS webhooks (
  id TEXT PRIMARY KEY DEFAULT (lower(hex(randomblob(16)))),
  organization_id TEXT NOT NULL,
  url TEXT NOT NULL,
  topics TEXT NOT NULL, -- JSON array
  secret TEXT NOT NULL,
  status TEXT DEFAULT 'active' CHECK(status IN ('active', 'inactive')),
  last_delivery_at TEXT,
  last_delivery_status TEXT,
  created_at TEXT DEFAULT (datetime('now')),
  FOREIGN KEY (organization_id) REFERENCES organizations(id) ON DELETE CASCADE
);

CREATE INDEX idx_webhook_org_id ON webhooks(organization_id);
CREATE INDEX idx_webhook_status ON webhooks(status);

-- Down Migration (Rollback)
-- DROP INDEX idx_webhook_status;
-- DROP INDEX idx_webhook_org_id;
-- DROP TABLE webhooks;

---

Deployment Runbook

Pre-Deployment Checklist

• All tests passing (unit, integration, E2E)
• Database backup created (cp navidocs.db navidocs.db.backup-$(date +%Y%m%d))
• Environment variables configured in .env.production
• SSL certificate valid (check expiration)
• Dependencies updated (npm audit fix)
• Security audit passed (no high/critical vulnerabilities)

Deployment Steps (Zero-Downtime)

1. Stop Background Workers (prevent job processing during migration)

   pm2 stop navidocs-worker
   

2. Database Backup

   cp /var/www/navidocs/navidocs.db /var/www/navidocs/backups/navidocs.db.$(date +%Y%m%d-%H%M%S)
   

3. Deploy Code

   cd /var/www/navidocs
   git pull origin main
   npm install --production
   npm run build
   

4. Run Migrations

   npm run migrate:up
   

5. Restart Server

   pm2 restart navidocs-api
   pm2 restart navidocs-worker
   

Post-Deployment Validation

• Health check endpoint returns 200 (GET /api/health)
• Login flow functional (test with demo account)
• Critical API endpoints responding (GET /api/boats, POST /api/warranties)
• Background workers processing jobs (pm2 logs navidocs-worker)
• Error rate within acceptable range (<1% of requests)

Rollback Procedure (If Deployment Fails)

1. Stop Server

   pm2 stop navidocs-api navidocs-worker
   

2. Restore Database

   cp /var/www/navidocs/backups/navidocs.db.<timestamp> /var/www/navidocs/navidocs.db
   

3. Revert Code

   git revert HEAD
   npm install --production
   

4. Restart Server

   pm2 restart navidocs-api navidocs-worker
   

---

IF.TTT Compliance Checklist

• All tasks link to codebase files (file:line references)
• Acceptance criteria testable (Given/When/Then format)
• Dependencies mapped (Gantt chart with critical path)
• API specs validated against existing routes
• Migration scripts include rollback procedures
• Evidence artifacts stored in /intelligence/session-4/

---

Success Criteria

Minimum Viable Output:

• 4-week sprint breakdown (day-by-day tasks)
• Acceptance criteria for all major features
• Gantt chart with dependencies
• API specification (OpenAPI format)
• Database migration scripts with rollbacks

Stretch Goals:

• Automated testing framework setup (Playwright config)
• CI/CD pipeline configuration (GitHub Actions)
• Performance benchmarks (load testing plan)
• Monitoring setup (error tracking, uptime alerts)

---

Start Command: Deploy to Claude Code Cloud after Session 2 complete End Condition: All deliverables committed to dannystocker/navidocs repo under intelligence/session-4/