Integration Architecture

External System --> Adapter --> Service Interface --> Widget

Example: DMS Integration

Lightspeed EVO                    QueueService
      |           Lightspeed           |
      +----------> Adapter ----------->+---> QueueList widget
                      |                |
                  Maps fields       Returns
                  to QueueJob[]    QueueJob[]


Example: Telemetry Integration

Siren Marine                      TelemetryService
      |           Siren Marine         |
      +----------> Adapter ----------->+---> TelemetryWidget
                      |                |
                  Maps readings     Returns
                  to fields[]      TelemetryProfile

+------------------+     +------------------+     +------------------+
|  External System |     |  Adapter Layer   |     |  Widget Layer    |
|                  |     |                  |     |                  |
|  Lightspeed API -+---->+ LightspeedQueue  +---->+ QueueList        |
|  Siren Marine   -+---->+ SirenTelemetry   +---->+ TelemetryWidget  |
|  SAP Parts      -+---->+ SAPParts         +---->+ PartsWidget      |
|  (none)         -+---->+ MockAdapter      +---->+ (demo data)      |
+------------------+     +------------------+     +------------------+

interface QueueJob {
  id: string;                // Work order number
  label: string;             // Vessel/asset name
  sublabel: string;          // Make and model
  equipment: string;         // Engine model
  equipmentCount: number;    // Number of engines
  hours: number;             // Engine hours
  complaint: string;         // Customer complaint summary
  priority: "high" | "normal" | "low";
  faultCode: string | null;
  faultDescription: string | null;
  partsStatus: "staged" | "ordered" | "not_staged";
  assessmentReady: boolean;
  bay: string;
  customer: string;
  assignedAt: string;        // ISO timestamp
}

interface QueueService {
  getJobs(): Promise<QueueJob[]>;
}

interface DraftJobInput {
  description: string;
  equipmentId?: string;
  faultCodes?: string;
  customerName?: string;
  assetName?: string;
}

interface JobService {
  loadWorkOrder(jobId: string): Promise<WorkOrder>;
  createDraft(input: DraftJobInput): WorkOrder;
}

interface TelemetryField {
  key: string;              // e.g. "coolant_temp_f"
  label: string;            // e.g. "Coolant Temp"
  value: number | null;     // Current reading
  unit: string;             // e.g. "F", "PSI", "RPM"
  warn_low: number | null;
  warn_high: number | null;
  critical_low: number | null;
  critical_high: number | null;
}

interface TelemetryEvent {
  id: string;
  date: string;
  time: string;
  peak: number;
  rpm: number;
  severity: "critical" | "warning" | "info";
  data: { t: string; v: number }[];  // Time-series for charting
}

interface TelemetryProfile {
  events: TelemetryEvent[];
  threshold: number;
  unit: string;
  domain: [number, number];
  ticks: number[];
  fields: TelemetryField[];
}

interface TelemetryService {
  getReadings(engineId: string): Promise<TelemetryReading[]>;
  getEventProfile(faultCode?: string): Promise<TelemetryProfile>;
}

interface PartEntry {
  partNumber: string;
  description: string;
  quantity: number;
  status: string;           // "in_stock", "ordered", "backordered"
  binLocation: string;
  unitCost: number;
}

interface PartsService {
  getPartsForJob(woNumber: string): Promise<PartEntry[]>;
}

interface CustomerInfo {
  name: string;
  phone: string;
  email?: string;
}

interface ServiceHistoryEntry {
  date: string;
  hoursAtService: number;
  description: string;
}

interface CustomerService {
  getCustomer(woNumber: string): Promise<CustomerInfo>;
  getServiceHistory(assetId: string): Promise<ServiceHistoryEntry[]>;
}

interface ServiceAdapter {
  queue: QueueService;
  job: JobService;
  telemetry: TelemetryService;
  parts: PartsService;
  customer: CustomerService;
}

// Example: a partial adapter that provides real queue data
// but falls back to mock for everything else

import { MockAdapter } from "./mock-adapter";
import type { ServiceAdapter, QueueService, QueueJob } from "./types";

class LightspeedQueueService implements QueueService {
  constructor(private apiUrl: string, private apiKey: string) {}

  async getJobs(): Promise<QueueJob[]> {
    const response = await fetch(`${this.apiUrl}/work-orders`, {
      headers: { Authorization: `Bearer ${this.apiKey}` },
    });
    const data = await response.json();
    return data.work_orders.map(mapLightspeedToQueueJob);
  }
}

// Compose: real queue, mock everything else
export function createLightspeedAdapter(
  config: { apiUrl: string; apiKey: string }
): ServiceAdapter {
  const mock = new MockAdapter();
  return {
    queue: new LightspeedQueueService(config.apiUrl, config.apiKey),
    job: mock.job,
    telemetry: mock.telemetry,
    parts: mock.parts,
    customer: mock.customer,
  };
}

function mapLightspeedToQueueJob(wo: LightspeedWorkOrder): QueueJob {
  return {
    id: wo.wo_number,
    label: wo.unit?.name || "Unknown",
    sublabel: `${wo.unit?.make || ""} ${wo.unit?.model || ""}`.trim(),
    equipment: wo.unit?.engine_model || "Unknown",
    equipmentCount: wo.unit?.engine_count || 1,
    hours: wo.unit?.hours || 0,
    complaint: wo.complaint_description || "",
    priority: wo.priority === "rush" ? "high" : "normal",
    faultCode: wo.dtc_codes?.[0]?.code || null,
    faultDescription: wo.dtc_codes?.[0]?.description || null,
    partsStatus: mapPartsStatus(wo.parts_status),
    assessmentReady: wo.status === "assigned",
    bay: wo.bay_number || "",
    customer: wo.customer?.name || "",
    assignedAt: wo.assigned_at || new Date().toISOString(),
  };
}

Normal flow:
  External API --> Adapter --> Widget (real data)

Error flow:
  External API --> Adapter --> ERROR
                      |
                      v
              MockAdapter --> Widget (demo data + warning banner)