navidocs/intelligence/session-2/if-bus-maintenance-integration.json

{
  "integration_request": {
    "performative": "request",
    "message_id": "maintenance-integration-001",
    "timestamp": "2024-11-13T14:32:00Z",
    "sender": "if://agent/session-2/haiku-03",
    "receivers": [
      "if://agent/session-2/haiku-05",
      "if://agent/session-2/haiku-07A"
    ],
    "subject": "Maintenance Log System Integration Handshake",
    "priority": "high",

    "content": {
      "integration_needed": "Maintenance log tracking system requires bidirectional integration with contact management and calendar systems",
      "data_flows": [
        {
          "flow_id": "provider_contacts_flow",
          "from_system": "maintenance-log (S2-H03)",
          "to_system": "contact-management (S2-H05)",
          "direction": "bidirectional",
          "description": "Service provider contact auto-suggest and details lookup",
          "data_elements": [
            "maintenance_log.provider",
            "maintenance_log.service_type",
            "maintenance_log.cost",
            "maintenance_log.date"
          ],
          "required_endpoints": [
            "GET /api/v1/boats/{boatId}/contacts/providers (filter by service_type)",
            "GET /api/v1/contacts/{contactId} (full contact details)",
            "PATCH /api/v1/contacts/{contactId}/usage (update provider statistics)"
          ],
          "response_format": {
            "contact_id": "string",
            "name": "string",
            "phone": "string",
            "email": "string",
            "address": "string",
            "type": "marine_service|electrician|surveyor|etc",
            "last_used": "date",
            "times_used": "number",
            "average_cost": "decimal",
            "rating": "number"
          },
          "frequency": "on_demand",
          "sla_requirement": "<500ms response time"
        },
        {
          "flow_id": "calendar_sync_flow",
          "from_system": "maintenance-log (S2-H03)",
          "to_system": "calendar-system (S2-H07A)",
          "direction": "unidirectional_push",
          "description": "Maintenance due dates sync to boat calendar for event planning",
          "data_elements": [
            "maintenance_log.next_due_date",
            "maintenance_log.next_due_engine_hours",
            "maintenance_log.service_type",
            "maintenance_log.provider",
            "maintenance_log.id"
          ],
          "triggers": [
            "On maintenance record creation",
            "On maintenance record update",
            "On maintenance record completion (mark as calendar event)",
            "Nightly batch sync of upcoming services (7-90 day window)"
          ],
          "required_endpoints": [
            "POST /api/v1/boats/{boatId}/calendar/events (create maintenance event)",
            "PATCH /api/v1/boats/{boatId}/calendar/events/{eventId} (update event details)",
            "DELETE /api/v1/boats/{boatId}/calendar/events/{eventId} (remove event when completed)"
          ],
          "event_payload": {
            "title": "string (e.g. 'Oil Change Due')",
            "description": "string",
            "event_type": "maintenance",
            "service_type": "enum (engine|electronics|hull|deck|safety_equipment|antifouling|survey)",
            "due_date": "ISO8601 date",
            "due_engine_hours": "number or null",
            "location": "string",
            "priority": "enum (low|medium|high|urgent|critical)",
            "alert_days": "array of integers [7, 14, 30, 60]",
            "provider_contact_id": "string",
            "external_id": "string (maintenance_log.id)"
          },
          "frequency": "real_time + nightly batch",
          "sla_requirement": "<1s response time"
        },
        {
          "flow_id": "reminder_notifications_flow",
          "from_system": "maintenance-log (S2-H03)",
          "to_system": "notification-system (requires S2-H07A coordination)",
          "direction": "unidirectional",
          "description": "Trigger reminder notifications when maintenance due dates approach",
          "notification_triggers": [
            {
              "threshold": "60_days_before",
              "channels": ["in_app", "email"],
              "frequency": "weekly"
            },
            {
              "threshold": "30_days_before",
              "channels": ["in_app", "email", "push"],
              "frequency": "bi-weekly"
            },
            {
              "threshold": "14_days_before",
              "channels": ["in_app", "email", "push", "sms"],
              "frequency": "weekly"
            },
            {
              "threshold": "7_days_before",
              "channels": ["in_app", "email", "push", "sms"],
              "frequency": "daily"
            },
            {
              "threshold": "overdue",
              "channels": ["in_app", "email", "push", "sms"],
              "frequency": "daily"
            }
          ]
        }
      ],

      "implementation_requirements": {
        "s2_h05_contact_management": {
          "description": "S2-H05 must provide provider contact lookup and suggestion service",
          "dependencies": [
            "Maintain provider contact records with service type categorization",
            "Track usage history (last_used, times_used) per boat",
            "Calculate provider ratings based on maintenance cost history",
            "Support filtering contacts by service_type"
          ],
          "acceptance_criteria": [
            "Returns provider contacts in <500ms",
            "Provider suggestions ranked by frequency and rating",
            "Contact updates propagated to maintenance log within 1 minute",
            "Support for custom provider addition during maintenance entry"
          ]
        },
        "s2_h07a_calendar_integration": {
          "description": "S2-H07A must accept and manage maintenance events on boat calendar",
          "dependencies": [
            "Calendar event creation/update/deletion for maintenance",
            "Support multiple alert thresholds per event",
            "Enable calendar sync to mobile calendar applications",
            "Track event status (scheduled, in_progress, completed, overdue)"
          ],
          "acceptance_criteria": [
            "Maintenance events appear in boat calendar within 2 seconds of creation",
            "Calendar reminders trigger at configured thresholds (7, 14, 30, 60 days)",
            "Completed maintenance marked in calendar for historical tracking",
            "Calendar export includes maintenance events in iCal format"
          ]
        }
      },

      "data_integrity_requirements": {
        "conflict_resolution": "If maintenance date conflicts with existing calendar event, calendar event takes precedence and maintenance system defers",
        "sync_frequency": "Real-time for creation/updates, nightly batch at 02:00 UTC for verification",
        "data_validation": "All dates must be ISO8601 format, costs must be positive decimals, engine hours must be monotonically increasing",
        "audit_trail": "All integrations logged with timestamps and success/failure status"
      },

      "security_requirements": {
        "authentication": "All inter-system calls use mutual TLS with service certificates",
        "authorization": "Contact and calendar access verified against boat ownership",
        "encryption": "All data in transit encrypted with TLS 1.3",
        "rate_limiting": "Max 100 requests/minute per integration endpoint"
      },

      "error_handling": {
        "contact_lookup_failure": "Fall back to manual provider entry during maintenance creation",
        "calendar_sync_failure": "Queue event for retry with exponential backoff (max 5 retries over 24 hours)",
        "data_conflict": "Log conflict, alert system administrator, maintain local record as source of truth"
      },

      "response_required": {
        "s2_h05_acknowledgement": {
          "confirm_capability": "Can S2-H05 provide provider contact endpoints?",
          "timeline": "When can contact endpoints be available?",
          "constraints": "Any limitations on contact data or filtering?",
          "contact_point": "Who is the point person for integration questions?"
        },
        "s2_h07a_acknowledgement": {
          "confirm_capability": "Can S2-H07A accept maintenance events via API?",
          "event_schema": "Can S2-H07A accommodate the maintenance event payload structure?",
          "alert_configuration": "How are multiple alert thresholds configured per event?",
          "timeline": "When can calendar endpoints be ready?",
          "contact_point": "Who is the point person for integration questions?"
        }
      }
    },

    "attachments": {
      "database_schema": "/home/user/navidocs/intelligence/session-2/maintenance-log-spec.md",
      "api_endpoints": "Section 2 of maintenance-log-spec.md",
      "integration_diagrams": "Available upon request"
    }
  },

  "system_integration_checklist": {
    "s2_h03_responsibilities": [
      "Provide maintenance tracking and reminder calculation",
      "Call S2-H05 APIs for provider auto-suggest",
      "Push maintenance events to S2-H07A calendar",
      "Log all integration activities for audit trail",
      "Handle graceful degradation if S2-H05 or S2-H07A unavailable"
    ],
    "s2_h05_responsibilities": [
      "Maintain provider contact database with service categorization",
      "Expose contact lookup endpoints filtered by boat_id and service_type",
      "Track provider usage statistics (times_used, last_used, average_cost)",
      "Calculate provider ratings",
      "Support contact creation/update via API"
    ],
    "s2_h07a_responsibilities": [
      "Accept maintenance event creation requests",
      "Maintain maintenance events in boat calendar",
      "Generate reminders based on configured thresholds",
      "Support event status updates (completed, canceled, rescheduled)",
      "Provide calendar export with maintenance events"
    ]
  },

  "timeline": {
    "phase_1_acknowledgement": "Immediate - confirm capability",
    "phase_2_endpoint_availability": "Within 5 business days",
    "phase_3_integration_testing": "5-10 business days",
    "phase_4_production_launch": "Upon successful testing"
  }
}