Service Migration Notes

This document tracks service reorganization and provides migration guidance for import path changes.

Overview

Services are being reorganized into three categories:

1. Shared Services (services/shared/) - Used across all products

2. Service Contracts (services/contracts/) - TypeScript interfaces

3. Product-Specific Services (services/) - Product-specific implementations

---

What Was Moved

Shared Services (Now in services/shared/)

Service	Old Path	New Path	Status
QueryService	services/QueryService.ts	services/shared/QueryService.ts	Planned

Service Contracts (Now in services/contracts/)

Contract	File	Status
IAuthService	services/contracts/IAuthService.ts	Created
IRoutingService	services/contracts/IRoutingService.ts	Created
IRelationshipService	services/contracts/IRelationshipService.ts	Exists
INotificationService	services/contracts/INotificationService.ts	Exists
IIntelligenceService	services/contracts/IIntelligenceService.ts	Exists

Existing Services (Staying in services/)

These services remain in their current location:

• AuthService.ts - Implements IAuthService

• IdentityResolverService.ts - Part of routing implementation

• RelationshipResolverService.ts - Part of routing implementation

• IngressParserService.ts - Part of routing implementation

• NotificationService.ts - Implements INotificationService

• IntelligenceService.ts - Implements IIntelligenceService

• RelationshipService.ts - Implements IRelationshipService

• WhatsAppService.ts - Used by NotificationService

• InviteService.ts - FleetOS-specific

• ConversationService.ts - Robo-Hub specific

---

Import Path Changes

QueryService

Before:

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

After:

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

Files That Need Updating:

• Search for: from '@/services/QueryService'

• Replace with: from '@/services/shared/QueryService'

---

Recommended Migration Steps

Phase 1: Update Imports (Low Risk)

1. Update QueryService imports across all files

2. Run TypeScript check: npm run type-check

3. Test that builds succeed

Phase 2: Implement Contracts (Medium Risk)

1. Update existing services to implement their contracts:

   // AuthService.ts
   import { IAuthService } from './contracts/IAuthService';
   
   class AuthService implements IAuthService {
     // ... implementation
   }

2. This is non-breaking but improves type safety

Phase 3: Create Routing Service (Optional)

1. Consider combining IdentityResolverService, RelationshipResolverService, and IngressParserService into a single RoutingService

2. Implement IRoutingService contract

3. This is a larger refactor - assess value vs effort

---

Files That Need Import Updates

Run these commands to find files that need updating:

# Find QueryService imports
grep -r "from '@/services/QueryService'" --include="*.ts" --include="*.tsx"

# Find IdentityResolverService usage
grep -r "IdentityResolverService" --include="*.ts" --include="*.tsx"

# Find RelationshipResolverService usage
grep -r "RelationshipResolverService" --include="*.ts" --include="*.tsx"

# Find IngressParserService usage
grep -r "IngressParserService" --include="*.ts" --include="*.tsx"

Expected Files to Update

Based on your codebase structure, these files likely import services:

Components:

• components/fleetos/**/*.tsx - FleetOS components

• components/robo-hub/**/*.tsx - Robo-Hub components

• components/fleetos-clean/**/*.tsx - FleetOS clean components

Services (cross-imports):

• services/ConversationService.ts

• services/IntelligenceService.ts

• services/NotificationService.ts

• services/RelationshipService.ts

Potential Hot Spots:

• Any dashboard components showing statistics (likely use QueryService)

• Chat interfaces (AgenticChatInterface, ShepherdChatInterface, SupplierChatInterface)

• Authentication flows

• Request submission forms

---

Contract Implementation Checklist

AuthService

• Import IAuthService contract

• Implement interface

• Verify all methods match contract

• Add JSDoc comments for any missing documentation

RoutingService (Future)

• Create unified RoutingService class

• Implement IRoutingService contract

• Combine IdentityResolverService logic

• Combine RelationshipResolverService logic

• Combine IngressParserService logic

• Update all imports across codebase

NotificationService

• Already has contract - verify implementation matches

IntelligenceService

• Already has contract - verify implementation matches

RelationshipService

• Already has contract - verify implementation matches

---

Testing After Migration

1. Type Checking

npm run type-check

2. Build Test

npm run build

3. Runtime Testing

• Test authentication flows (magic link, SSO)

• Test request submission (web form, WhatsApp parsing)

• Test dashboard queries (relationships, requests, stats)

• Test identity resolution

4. Product-Specific Testing

FleetOS:

• Supplier onboarding

• Fleet request submission

• Invite flow

• Relationship creation

Robo-Hub:

• Shepherd dashboard

• RFQ creation

• Contract management

• Zone assignment

Robo-Dapp:

• Wallet connection

• DAO features (if implemented)

---

Rollback Plan

If migration causes issues:

1. Revert import changes:

   git checkout -- .

2. Incremental rollback:

   • QueryService is low-risk - can stay in services/shared/

   • Contracts are additive - can be ignored if not implemented

   • RoutingService unification is optional - existing services work fine

---

Benefits After Migration

For FleetOS

• Clearer separation from Robo-Hub logic

• Faster builds (fewer unnecessary imports)

• Easier to extract into separate deployment

For Robo-Hub

• Advanced features clearly separated

• Shepherd-specific logic isolated

• Contract-based architecture for future plugins

For Robo-Dapp

• Blockchain logic clearly separated

• Wallet-based flows isolated

• DAO features extensible

For All Products

• Single source of truth for queries (QueryService)

• Type-safe contracts prevent API drift

• Easier testing with clear interfaces

• Better documentation through JSDoc

---

Questions?

If you encounter issues during migration:

1. Check TypeScript errors first

2. Verify import paths match new structure

3. Ensure contracts are imported but not necessarily implemented (optional)

4. Test incrementally - one service at a time

Next Steps

1. Immediate: Update QueryService imports

2. Short-term: Implement contracts in existing services

3. Long-term: Consider creating unified RoutingService

4. Future: Extract product-specific services into separate packages