Shared Services

This directory contains shared service implementations used across all three products (FleetOS, Robo-Hub, Robo-Dapp).

Overview

Shared services eliminate code duplication and provide a single source of truth for common functionality. Each service implements a formal contract interface defined in services/contracts/.

Available Shared Services

1. QueryService

File: QueryService.ts Contract: N/A (utility class) Purpose: Eliminates 100+ duplicate Supabase queries across products

Features:

• Standardized, reusable database queries

• Type-safe query methods

• Consistent error handling

• Future caching layer support

Usage:

import { QueryService } from '@/services/shared/QueryService';

// Get service requests with filters
const requests = await QueryService.getServiceRequests({
  source_product: 'fleetos',
  status: 'pending',
  urgency: 'URGENT'
});

// Get active relationships
const relationships = await QueryService.getActiveRelationships(userId);

// Get relationship statistics
const stats = await QueryService.getRelationshipStats(relationshipId);

Common Queries:

• getServiceRequests(filters) - Get filtered service requests

• getRequestsByRelationship(relationshipId) - Get requests for a relationship

• getRelationships(filters) - Get filtered relationships

• getActiveRelationships(userId) - Get active relationships for user

• getFleetNames(fleetIds) - Batch fetch fleet names

• getSupplierNames(supplierIds) - Batch fetch supplier names

• getNotifications(userId) - Get user notifications

• getShepherdRFQs(shepherdId) - Get RFQs for shepherd (Robo-Hub)

• getShepherdContracts(shepherdId) - Get contracts for shepherd (Robo-Hub)

---

Service Contracts

All shared services implement formal TypeScript interfaces defined in services/contracts/. This ensures:

• Consistent API across products

• Type safety

• Clear separation between FleetOS, Robo-Hub, and Robo-Dapp implementations

• Easy mocking for tests

Available Contracts

1. IAuthService (contracts/IAuthService.ts)

   • Magic link authentication

   • Session management

   • Progressive tier upgrades (ANONYMOUS → MAGIC_LINK → AUTHENTICATED → ROBO_HUB → ROBO_DAPP)

   • Cross-domain SSO

2. IRoutingService (contracts/IRoutingService.ts)

   • Identity resolution (supplier/fleet lookup)

   • Request parsing (web form, WhatsApp, email)

   • Request routing (active queue vs pending queue)

   • Cache management

3. IRelationshipService (contracts/IRelationshipService.ts)

   • Relationship establishment

   • Status management

   • Health score calculation

   • FleetOS: Simple fleet-supplier relationships

   • Robo-Hub: Contracted relationships with pricing/SLAs

4. INotificationService (contracts/INotificationService.ts)

   • WhatsApp messaging

   • Email notifications

   • SMS notifications

   • Magic link generation

5. IIntelligenceService (contracts/IIntelligenceService.ts)

   • Relationship health calculation

   • Exception detection

   • Pattern analysis

   • Weekly summaries

---

Using Shared Services Across Products

FleetOS

import AuthService from '@/services/AuthService';
import { IdentityResolverService } from '@/services/IdentityResolverService';
import { RelationshipResolverService } from '@/services/RelationshipResolverService';
import { QueryService } from '@/services/shared/QueryService';

// FleetOS uses simple authentication
const session = await AuthService.verifyMagicLink(token);

// FleetOS uses basic identity resolution
const supplierId = await IdentityResolverService.resolveSupplier({
  phone: '[phone]'
});

// FleetOS uses simple relationship routing
const routing = await RelationshipResolverService.routeRequest(
  parsed,
  supplierId,
  fleetUserId
);

Robo-Hub

import AuthService from '@/services/AuthService';
import { QueryService } from '@/services/shared/QueryService';
import { IntelligenceService } from '@/services/IntelligenceService';

// Robo-Hub uses shepherd authentication
const shepherdProfile = await AuthService.createShepherdProfile(userId, {
  organization_name: 'ABC Logistics',
  zone_id: 'zone-123',
  service_categories: ['TIRES', 'MAINTENANCE']
});

// Robo-Hub uses advanced queries
const rfqs = await QueryService.getShepherdRFQs(shepherdId);
const contracts = await QueryService.getShepherdContracts(shepherdId);

// Robo-Hub uses intelligence services
const health = await IntelligenceService.calculateRelationshipHealth(relationshipId);
const patterns = await IntelligenceService.analyzePatterns(userId);

Robo-Dapp

import AuthService from '@/services/AuthService';

// Robo-Dapp uses wallet-based authentication
const session = await AuthService.authenticateWithWallet(
  walletAddress,
  signature,
  message
);

// Link wallet to existing account
const user = await AuthService.linkWalletToAccount(
  userId,
  walletAddress,
  signature
);

---

Architecture Principles

1. Product Separation

• FleetOS: Simple, fast onboarding for suppliers and fleets

• Robo-Hub: Advanced features for shepherds managing networks

• Robo-Dapp: Blockchain-based governance and DAO features

2. Progressive Enhancement

Services support progressive feature unlocking:

• Tier 1 (ANONYMOUS): Browse public pages

• Tier 2 (MAGIC_LINK): Submit requests, receive updates

• Tier 3 (AUTHENTICATED): Create invites, manage relationships

• Tier 4 (ROBO_HUB): RFQs, contracts, zone management

• Tier 5 (ROBO_DAPP): DAO voting, on-chain operations

3. Shared Core, Product-Specific Extensions

• Base interfaces define common functionality

• Product-specific interfaces extend base interfaces

• Implementations can override or extend shared methods

4. Single Source of Truth

• One database schema shared across products

• QueryService eliminates duplicate queries

• Contracts ensure consistent APIs

---

Testing Shared Services

import { QueryService } from '@/services/shared/QueryService';

// Mock Supabase for tests
jest.mock('@/lib/supabase', () => ({
  supabase: {
    from: jest.fn()
  }
}));

// Test shared service
describe('QueryService', () => {
  it('should get service requests with filters', async () => {
    const requests = await QueryService.getServiceRequests({
      status: 'pending'
    });
    expect(requests).toBeDefined();
  });
});

---

Adding New Shared Services

1. Define Contract in services/contracts/

2. Implement Service in services/ or services/shared/

3. Export Types from contract for use across products

4. Document Usage in this README

5. Add Tests for shared functionality

---

Migration Guide

See services/MIGRATION_NOTES.md for detailed migration instructions when moving services between products.