navidocs/intelligence/session-4/dependency-graph.md

NaviDocs Session 4: Dependency Graph & Critical Path Analysis

Agent: S4-H07 (Dependency Mapper) Created: 2025-11-13 Sprint Duration: 4 weeks (Nov 13 - Dec 10) Team: 1 solo developer (6-8 hours/day) Total Available Hours: 160-200 hours/month

---

Executive Summary

This dependency graph identifies the critical path for the 4-week NaviDocs sprint, highlighting task sequencing, parallel work opportunities, and risk mitigation strategies. The critical path spans 24 calendar days (actual work: ~18-19 days) and is bottlenecked by foundation tasks (DB migrations, Event Bus) that block all downstream work.

Key Findings:

• Critical Path: DB Migrations → Event Bus → Background Jobs → Warranty APIs → E2E Testing → Deployment
• Parallel Opportunities: 3 major zones where work can be parallelized (requires process changes)
• Risk Areas: 5 identified blockers with mitigation strategies
• Total Slack Time: 3-5 days available for handling blockers/unknowns

---

Detailed Task Dependencies (Mermaid Gantt)

gantt
    title NaviDocs 4-Week Sprint: Full Dependency Graph
    dateFormat  YYYY-MM-DD

    section Week 1: Foundation
    DB Migrations (warranty_tracking, webhooks, sale_workflows) :crit, w1_db, 2025-11-13, 1d
    Event Bus Implementation (IF.bus service + webhooks service) :crit, w1_eb, after w1_db, 1d
    Security Fixes (DELETE auth, stats isolation, endpoint protection) :w1_sec, 2025-11-14, 1d
    Notification Templates (DB seeding + service setup) :w1_notif, 2025-11-15, 1d
    Background Jobs (warranty expiration worker + registration) :crit, w1_jobs, after w1_notif, 1d
    Week 1 Testing & Validation :w1_test, after w1_jobs, 1d

    section Week 2: Core APIs & Integration
    Warranty CRUD APIs (POST, GET, PUT, DELETE endpoints) :crit, w2_warranty, after w1_eb, 2d
    Warranty Expiring Endpoint (GET /warranties/expiring with filtering) :crit, w2_expiring, after w2_warranty, 1d
    Home Assistant Webhook Setup (integration registration + validation) :w2_ha_setup, after w2_warranty, 1d
    Home Assistant Event Forwarding (webhook delivery + retry logic) :w2_ha_fwd, after w2_ha_setup, 2d
    MQTT Integration (optional stretch goal) :crit_optional, w2_mqtt, after w2_ha_fwd, 1d
    Camera Integration (optional stretch goal) :crit_optional, w2_camera, after w2_mqtt, 1d
    Week 2 Integration Testing :w2_test, after w2_expiring, 4d

    section Week 3: Automation & UX
    Sale Workflow Service (initiate, generate package, transfer) :crit, w3_sale, after w2_warranty, 2d
    As-Built Package Generator (ZIP creation, folder organization) :crit, w3_package, after w3_sale, 1d
    Email Service Setup (Nodemailer + templates) :w3_email, 2025-11-29, 1d
    SMS Gateway Integration (Twilio research + implementation) :w3_sms, after w3_email, 1d
    In-App Notification Center (DB table + API endpoints) :w3_inapp, after w3_sms, 1d
    Push Notifications (Service worker + Web Push API) :w3_push, after w3_inapp, 1d
    Offline Mode & Caching (service worker + IndexedDB) :w3_offline, 2025-12-01, 1d
    Week 3 E2E Testing :w3_test, after w3_package, 3d

    section Week 4: Polish & Deploy
    MLS Integration - YachtWorld (API research + client setup) :w4_mls1, 2025-12-04, 1d
    MLS Integration - Boat Trader (API integration + abstraction layer) :w4_mls2, after w4_mls1, 1d
    MLS Sync Background Job (daily sync scheduling) :w4_mls_job, after w4_mls2, 1d
    E2E Test Suite - Critical Flows (Playwright setup) :crit, w4_e2e, after w3_test, 1d
    Security Audit (OWASP + auth/authz review) :crit, w4_audit, after w4_e2e, 1d
    Pre-Deployment Checklist (backups, env vars, SSL) :crit, w4_precheck, after w4_audit, 1d
    Production Deployment (migrations, code deploy, restart) :crit, w4_deploy, after w4_precheck, 1d
    Post-Deployment Validation (smoke tests + monitoring) :crit, w4_smoke, after w4_deploy, 1d
    Riviera Pilot Setup (demo account, training, HA config) :w4_pilot, after w4_smoke, 2d

---

Critical Path Analysis

Primary Critical Path (24 days, ~18-19 work days)

Week 1:
  Day 1  → DB Migrations (1d)
  Day 2  → Event Bus (1d)
  Day 4  → Notification Templates (1d)
  Day 5  → Background Jobs (1d)
  Day 6  → Week 1 Testing (1d)

Week 2:
  Day 7-8   → Warranty APIs (2d)
  Day 9     → Warranty Expiring Endpoint (1d)
  Day 10-11 → HA Integration (2d basic, optional +1d MQTT, +1d Camera)
  Day 12-14 → Integration Testing (3d)

Week 3:
  Day 15-16 → Sale Workflow (2d)
  Day 17    → Package Generator (1d)
  Day 18    → Email Service (1d)
  Day 19-21 → Notification System (3d)
  Day 22    → Offline Mode (1d)

Week 4:
  Day 23    → E2E Test Suite (1d)
  Day 24    → Security Audit (1d)
  Day 25    → Pre-Deploy Checklist (1d)
  Day 26    → Production Deploy (1d)
  Day 27    → Post-Deploy Validation (1d)

TOTAL: 27 calendar days, ~19-20 work days

Why This Is Critical

1. DB Migrations must complete first (blocks all APIs)
2. Event Bus must follow immediately (blocks async notifications)
3. Background Jobs depends on both (warranty expiration worker)
4. Warranty APIs depend on DB + Jobs (foundation for Week 2+)
5. E2E Testing depends on all feature implementation
6. Deployment depends on passing security audit + smoke tests

Slack Analysis

• Buffer Built In: 6-8 working days available (assuming 6-8 hrs/day × 27 days)
• Consumed by Critical Path: ~19-20 days
• Available Slack: 3-5 days for blockers/unknowns
• Weekly Buffer: 1 day/week = 4 days total

---

Parallel Work Opportunities

Opportunity 1: Week 2 - Home Assistant + Optional Features (4-5 days)

Window: Days 8-14 (after Warranty APIs complete)

Parallel Track A (Required):

• Warranty APIs (CRUD) → 2 days
• Warranty Expiring Endpoint → 1 day
• Integration Tests → 2-3 days

Parallel Track B (Can overlap with Track A from Day 9+):

• Home Assistant Webhook Setup → 1 day
• Home Assistant Event Forwarding → 2 days
• (Optional) MQTT Integration → 1 day
• (Optional) Camera Integration → 1 day

Recommendation: Keep as sequential given solo developer constraint. If split into 2 developers:

• Dev 1: Warranty APIs + Testing
• Dev 2: HA Integration + Optional features (in parallel)

Time Saved: 1-2 days if parallelized

---

Opportunity 2: Week 3 - Sale Workflow + Notification System (5-6 days)

Window: Days 15-22 (after Week 2 complete)

Parallel Track A (Required):

• Sale Workflow → 2 days
• Package Generator → 1 day
• Integration Testing → 2-3 days

Parallel Track B (Can overlap from Day 18+):

• Email Service → 1 day
• SMS Gateway → 1 day
• In-App Notifications → 1 day
• Push Notifications → 1 day

Recommendation: Sequential for solo developer. Potential parallelization:

• Dev 1: Sale Workflow + Package Generator + Testing
• Dev 2: Notification System (Email, SMS, In-App, Push)

Time Saved: 1-2 days if parallelized

---

Opportunity 3: Week 4 - MLS Integration (Optional Deferral)

Window: Days 23-26 (first 2 days of Week 4)

Status: Non-critical path

• Can be deferred to Week 5/post-release
• Does NOT block deployment
• Adds 2-3 days to schedule if included
• Should only proceed if ahead of schedule

Recommendation: Mark as "nice-to-have" and defer if timeline slips

---

Risk Areas & Blockers

Risk 1: Home Assistant Webhook Validation Unknown (Medium Risk)

Description: HA webhook reachability check may fail or have undocumented requirements Impact: 1-2 day delay if validation logic needs rework Mitigation:

• Day 9 afternoon: Spike on HA webhook requirements (2-4 hours research)
• Set up test HA instance locally for validation
• Have fallback: skip validation if unreachable (defer to Week 4)
• Contingency Time: 0.5 day slack allocated

---

Risk 2: Database Migration Edge Cases (Medium Risk)

Description: SQLite migration rollback may have issues with foreign keys/cascading deletes Impact: 0.5-1 day delay if rollback testing reveals issues Mitigation:

• Day 1 afternoon: Run test rollback on all 3 migrations
• Validate indexes created correctly
• Document any SQLite-specific gotchas
• Contingency Time: 0.5 day slack allocated

---

Risk 3: OWASP Dependency Scan Failures (Medium Risk)

Description: npm audit may find critical vulnerabilities blocking deployment Impact: 1-2 days delay for patching/workarounds Mitigation:

• Run audit on Day 1 (get baseline)
• Schedule security audit for Day 24, not Day 27
• Update dependencies early (Week 1)
• Have rollback plan for breaking updates
• Contingency Time: 1 day slack allocated

---

Risk 4: Playwright E2E Setup Complexity (Low Risk)

Description: E2E test framework setup may be more complex than estimated (2-4 hrs) Impact: 0.5 day delay if setup takes longer Mitigation:

• Use Playwright templates/examples
• Start E2E suite on Day 22 (not Day 23)
• Have pre-built critical flow test cases
• Contingency Time: 0.5 day slack allocated

---

Risk 5: Production Deployment Issues (High Risk)

Description: Database migration in production may fail, or code may crash on startup Impact: 2-4 hours delay + potential rollback (half day) Mitigation:

• Test full migration → code deploy → restart flow on staging (Day 25)
• Automated smoke tests running before deployment
• Runbook with rollback steps prepared (Day 25)
• Keep developer available for 24 hours post-deploy (Dec 9)
• Contingency Time: Contingency is the post-deploy validation day

---

Slack Time Distribution

Total Available Time: 200 hours (6-8 hrs/day × 27 days)

Critical Path Actual Work: ~150-160 hours

Slack Allocation:

Week	Available	Critical	Slack	Risk Buffer
W1	40-50 hrs	30-35 hrs	5-10 hrs	DB/EB migrations
W2	40-50 hrs	35-40 hrs	0-5 hrs	HA spike, testing
W3	40-50 hrs	35-40 hrs	0-5 hrs	Notification overlap
W4	40-50 hrs	20-25 hrs	15-20 hrs	MLS optional, smoke tests

Weekly Slack Reserves:

• Week 1: 1 full day for DB/migration issues
• Week 2: 0.5 day for HA validation spike
• Week 3: 0.5 day for testing overflow
• Week 4: 1.5 days (MLS is optional, smoke tests have buffer)

Total Contingency Buffer: 3.5 days (28 hours) = 18% buffer

---

Critical Task Dependencies (Dependency Matrix)

Task	Depends On	Duration	Slack	Risk Level
DB Migrations	None	1d	0d	CRITICAL
Event Bus	DB Migrations	1d	0d	CRITICAL
Security Fixes	None	1d	0.5d	MEDIUM
Notification Templates	None	1d	0.5d	LOW
Background Jobs	Event Bus + Notification	1d	0d	CRITICAL
Week 1 Testing	All W1 tasks	1d	0d	CRITICAL
Warranty APIs	DB Migrations	2d	0.5d	CRITICAL
Warranty Expiring	Warranty APIs	1d	0.5d	MEDIUM
HA Webhook	Webhook table (DB)	1d	1d	MEDIUM (unknown spike risk)
HA Event Forward	HA Webhook	2d	0d	MEDIUM
Sale Workflow	DB (sale_workflows table)	2d	0.5d	CRITICAL
Package Generator	Sale Workflow	1d	0.5d	LOW
Notification System	Email Service	3d	1d	LOW
Offline Mode	Vue 3 + Service Worker	1d	1d	LOW
E2E Testing	All features	1d	0.5d	MEDIUM
Security Audit	All code	1d	0d	CRITICAL
Pre-Deploy	Security Audit pass	1d	0d	CRITICAL
Deployment	Pre-Deploy OK	1d	0d	CRITICAL
Post-Deploy	Deployment OK	1d	0d	CRITICAL

---

Risk Mitigation Strategies

Strategy 1: Daily Risk Check-In (Lightweight)

Every morning (10 min):

• Check: Is DB/Event Bus/Background Jobs on track? (if no → escalate)
• Check: Any unknowns surfaced in optional features? (HA, MQTT, Camera)
• Check: Test failures blocking next day's work?
• Action: If blocked, pull from slack day or defer optional feature

Responsible: Developer + optionally S4-H10 (Deployment Checklist Creator)

---

Strategy 2: Pre-Spike Research Days (Early Risk Reduction)

Allocate "spike days" for unknowns before critical path:

Day	Spike Duration	Focus Area	Outcome
Nov 13 PM (4 hrs)	Audit HA webhook API	Identify reachability check approach	Clear spec or fallback plan
Nov 14 PM (2 hrs)	OWASP scan baseline	Identify dependencies with issues	Remediation plan
Nov 21 PM (2 hrs)	Playwright setup test	Verify test config works	Confirmed setup approach
Nov 28 PM (2 hrs)	Email service selection	Nodemailer vs alternatives	Selected + configured

Impact: 10 hours of research saves 2-3 days of debugging later

---

Strategy 3: Optional Feature Deferral Plan

If schedule slips, defer in this order:

1. Defer MQTT Integration (Day 10) → +1 day slack
2. Defer Camera Integration (Day 10) → +1 day slack
3. Defer MLS Integration (Days 23-26) → +3 days slack
4. Defer Riviera Pilot Training (Days 28-29) → +1 day slack

Contingency Capacity: 6 days of deferrable work = can handle 2-3 day overrun

---

Strategy 4: Test-Driven Fallback (Quality Gate)

If Day 24 security audit fails critical vulnerabilities:

1. Fix critical issues (max 1 day)
2. Re-run audit
3. If still failing → defer MLS integration → gain 2-3 days
4. Continue with deployment path

Goal: Avoid shipping known critical vulns

---

Strategy 5: Database Rollback Drills

Pre-Deploy (Day 25):

• Practice full rollback sequence on staging
• Time rollback operation (target: <10 min)
• Verify all migrations rollback cleanly
• Document any manual steps needed

Impact: 2-3 hours investment saves hours of production firefighting

---

Parallel Work Recommendations

For Solo Developer (Current Plan)

• Recommendation: Keep as sequential
• Reason:
  • Context switching overhead 15-20% on solo developer
  • Feature dependencies are deep (DB → APIs → Features)
  • Testing/validation easier if focused on 1-2 features at a time
• Flexibility: Use slack days to parallelize if ahead of schedule

If Extended to 2 Developers (Ideal)

Developer 1: Database + Event Bus + Warranty APIs
Developer 2: Security Fixes + Notifications + HA Integration (parallel from Day 7)

Week 2-3:
Developer 1: Sale Workflow + E2E Testing
Developer 2: Notification System + Offline Mode (parallel from Day 17)

Week 4:
Developer 1: Security Audit + Deployment
Developer 2: MLS Integration (optional)

Time Saved: 2-3 days with 2-person team

---

Weekly Milestones & Go/No-Go Gates

End of Week 1 (Nov 16, Friday EOD) - GATE 1

Deliverables Required:

• All 3 migrations (warranty_tracking, sale_workflows, webhooks) created + tested
• Event bus service implementation complete + passing unit tests
• Background jobs registered + warranty expiration worker passing integration tests
• Security fixes applied (3/5 prioritized)
• Week 1 acceptance criteria 90%+ passing

Go Criteria: All critical items complete, <1 day behind schedule No-Go Criteria: DB migrations unstable OR Event Bus failing tests If No-Go: Pause Week 2 work, fix blockers, escalate to S4-H10

---

End of Week 2 (Nov 23, Friday EOD) - GATE 2

Deliverables Required:

• Warranty APIs complete (CRUD + expiring endpoint)
• Home Assistant integration basic version (webhook registration + event forwarding)
• Integration tests passing (80%+ coverage)
• Optional features (MQTT, Camera) deferred or 50%+ complete

Go Criteria: Warranty APIs stable, HA integration working No-Go Criteria: Warranty APIs failing tests OR HA webhook unreachable If No-Go: Defer optional features, focus on core APIs, escalate

---

End of Week 3 (Nov 30, Friday EOD) - GATE 3

Deliverables Required:

• Sale workflow complete (initiate → generate → transfer)
• Notification system 90%+ complete (email + SMS + in-app + push)
• Offline mode working for critical manuals
• E2E test suite skeleton ready

Go Criteria: Sale workflow + notifications stable, offline mode working No-Go Criteria: Sale workflow failing OR notification system unreliable If No-Go: Defer Riviera pilot, focus on core features, extend Week 4

---

End of Week 4 (Dec 10, Wednesday EOD) - GATE 4 (FINAL)

Deliverables Required:

• All features deployed to production
• E2E tests passing (10 critical flows)
• Security audit passed (no high/critical vulns)
• Post-deployment validation complete
• Riviera pilot account set up OR deferred to Week 5

Go Criteria: Production deployment successful, smoke tests passing No-Go Criteria: Post-deploy validation failing OR critical issues found If No-Go: Rollback to previous version, debug issues, re-deploy Dec 11-12

---

Communication Protocol (IF.bus)

Message Pattern: Dependency Updates

When a task completes, send dependency notification to downstream agents:

Example (Day 1 EOD):

{
  "performative": "inform",
  "sender": "if://agent/session-4/S4-H01",
  "receiver": ["if://agent/session-4/S4-H02", "if://agent/session-4/S4-H07"],
  "content": {
    "claim": "DB migrations complete - warranty_tracking, webhooks, sale_workflows tables created",
    "evidence": ["3 migrations tested", "rollback scripts verified"],
    "confidence": 0.95,
    "unblocks": ["Warranty APIs", "Event Bus service", "Sale Workflow APIs"],
    "blockers": [],
    "ready_for_week_2": true
  }
}

Gate Status Messages (Weekly)

Every Friday EOD, send gate status to S4-H10:

performative: "inform" or "disconfirm"
content:
  week: N
  gate_status: "GO" | "NO-GO"
  deliverables_complete: X/Y
  critical_blockers: []
  schedule_delta: "+1d" | "on-time" | "-1d"
  recommendation: "proceed" | "extend week N" | "defer optional feature X"

---

Metrics & Tracking

Tracked Metrics (Daily)

• Hours spent on critical path vs. actual time available
• Number of test failures by type (unit, integration, E2E)
• Blocker count (active issues blocking progress)
• Code coverage % for core services

Tracked Metrics (Weekly)

• Critical path burn-down (% complete vs. planned)
• Slack time consumed vs. available
• Features deferred (if any)
• Risk status (new blockers surfaced)

Rollup Reports (EOW)

To: S4-H10 (Deployment Checklist Creator) Format:

## Week N Status Report
- Planned Work: [list of tasks]
- Completed: X/Y tasks
- Critical Path Status: On-track | +1d | +2d+
- Blockers: [list of active issues]
- Next Week Readiness: [go/no-go]

---

Summary: Timeline at a Glance

Week 1 (Nov 13-19)    Foundation    [████████░] 90% foundation ready
                      Migrations, Event Bus, Security, Background Jobs

Week 2 (Nov 20-26)    Core APIs     [████░░░░░] 70% APIs + integrations
                      Warranty APIs, HA Integration, Testing

Week 3 (Nov 27-Dec 3) Automation    [██████░░░] 60% features + notifications
                      Sale Workflow, Notifications, Offline

Week 4 (Dec 4-10)     Polish/Deploy [███████░░] 80% ready for production
                      E2E Tests, Security Audit, Deployment

CRITICAL PATH:        DB → EB → Jobs → APIs → E2E → Deploy (27 days)
SLACK BUFFER:         3-5 days available
RISK LEVEL:           MEDIUM (Home Assistant unknowns, security audit)

---

Appendix: Dependency Graph (Visual Reference)

Week 1 (Foundation)
┌─────────────────────────────────────────┐
│ DB Migrations                           │ Day 1 (CRITICAL)
│ ↓                                       │
│ Event Bus Service                       │ Day 2 (CRITICAL)
│ ├─→ Background Jobs Worker              │ Day 5 (CRITICAL)
│ └─→ Webhook Service                     │
│ ↓                                       │
│ Security Fixes (parallel, Day 3)        │
│ Notification Templates (parallel, Day 4)│
│ ↓                                       │
│ Week 1 Testing                          │ Day 6 (GATE 1)
└─────────────────────────────────────────┘

Week 2 (APIs)
┌─────────────────────────────────────────┐
│ Warranty APIs (CRUD)                    │ Days 7-8 (CRITICAL)
│ ├─→ Warranty Expiring Endpoint          │ Day 9
│ ├─→ Home Assistant Setup                │ Day 9 (parallel)
│ │   ├─→ HA Event Forwarding             │ Days 10-11
│ │   ├─→ MQTT (optional)                 │ Day 11
│ │   └─→ Camera (optional)               │ Day 12
│ └─→ Integration Testing                 │ Days 12-14 (GATE 2)
└─────────────────────────────────────────┘

Week 3 (Features)
┌─────────────────────────────────────────┐
│ Sale Workflow                           │ Days 15-16 (CRITICAL)
│ ├─→ Package Generator                   │ Day 17
│ ├─→ Email Service                       │ Day 18 (parallel)
│ │   ├─→ SMS Gateway                     │ Day 19
│ │   ├─→ In-App Notifications            │ Day 20
│ │   └─→ Push Notifications              │ Day 21
│ ├─→ Offline Mode                        │ Day 22 (parallel)
│ └─→ E2E Testing                         │ Days 21-23 (GATE 3)
└─────────────────────────────────────────┘

Week 4 (Deploy)
┌─────────────────────────────────────────┐
│ Security Audit                          │ Day 24 (CRITICAL)
│ ├─→ Pre-Deploy Checklist                │ Day 25 (CRITICAL)
│ │   └─→ Production Deploy               │ Day 26 (CRITICAL)
│ │       └─→ Post-Deploy Validation      │ Day 27 (GATE 4)
│ └─→ MLS Integration (optional, Days 23-26)
│ Riviera Pilot (optional, Days 27-28)
└─────────────────────────────────────────┘

---

Document Status: Final Confidence Level: 0.92 (high confidence given detailed task specs in planning doc) Next Step: Share with S4-H10 via IF.bus "inform" message (critical path identified)