Architecture Migration Plan

Target: Product-Separated File Structure

Status: Planned - To be executed during refactoring sprint Created: 2026-01-08 Estimated Effort: 2-4 hours Risk Level: Medium (requires careful import updates)

---

Current vs Target Structure

Current Structure (Working)

robo-hub/
├── components/
│   ├── shared/              # Ecosystem-level
│   ├── fleetos/             # Legacy FleetOS
│   ├── fleetos-clean/       # Current FleetOS
│   └── robo-hub/            # Robo-Hub
├── services/                # Mixed (ecosystem + product)
├── lib/                     # Ecosystem-level
├── types/                   # Mixed
├── database/                # Mixed
├── docs/                    # All docs
└── Robo-Dapp/              # Separate Next.js app

Target Structure (Planned)

robo-hub/
│
├── ecosystem/               # T420 ECOSYSTEM LEVEL
│   ├── docs/
│   │   ├── T420_ECOSYSTEM_GUIDE.md
│   │   ├── ARCHITECTURE.md
│   │   ├── PROGRESSIVE_AUTH_ARCHITECTURE.md
│   │   ├── DEPLOYMENT.md
│   │   ├── USER_FLOWS.md
│   │   └── WORK_LOG.md
│   ├── database/
│   │   ├── core/           # Shared tables (users, relationships)
│   │   ├── migrations/
│   │   └── add-row-level-security.sql
│   ├── shared/
│   │   ├── components/     # Card, EmptyState, Breadcrumb, FilterBar
│   │   ├── services/       # AuthService, RelationshipService, QueryService
│   │   ├── lib/            # supabase.ts, typeGuards.ts, styleHelpers.ts
│   │   └── types/          # User, AuthTier, shared types
│   ├── scripts/            # System-wide utility scripts
│   └── agents/             # Code quality agents (verify-app, etc.)
│
├── fleetos/                # FLEETOS PRODUCT
│   ├── docs/
│   │   ├── FLEETOS_GUIDE.md
│   │   └── DEVELOPMENT_GUIDE.md (FleetOS-specific)
│   ├── components/         # All FleetOS UI components
│   │   ├── CleanLanding.tsx
│   │   ├── FleetRequestForm.tsx
│   │   ├── ManualRequestForm.tsx
│   │   ├── InviteFlow.tsx
│   │   ├── MinimalSignup.tsx
│   │   ├── RequestResponseView.tsx
│   │   ├── RequestSuccessPage.tsx
│   │   ├── RequestTrackingPage.tsx
│   │   ├── SupplierDirectory.tsx
│   │   └── SupplierTodoList.tsx
│   ├── services/           # FleetOS-specific services
│   │   ├── InviteService.ts
│   │   └── ViralTriggerEngine.ts (or move to ecosystem?)
│   ├── database/           # FleetOS-specific tables
│   │   └── fleetos/
│   └── scripts/            # FleetOS utility scripts
│
├── robo-hub/               # ROBO-HUB PRODUCT
│   ├── docs/
│   │   └── ROBO_HUB_GUIDE.md
│   ├── components/         # All Robo-Hub UI components
│   │   ├── agentic/
│   │   │   ├── AgenticChatInterface.tsx
│   │   │   ├── ShepherdChatInterface.tsx
│   │   │   ├── SupplierChatInterface.tsx
│   │   │   └── AgenticSupplyChainV2.tsx
│   │   ├── common/
│   │   └── pages/
│   ├── services/           # Robo-Hub specific services
│   │   ├── IntelligenceService.ts
│   │   └── IntelligenceDataService.ts
│   ├── database/           # Robo-Hub tables
│   │   └── robo-hub/
│   └── scripts/            # RH utility scripts
│
└── robo-dapp/              # ROBO-DAPP PRODUCT (separate Next.js)
    ├── docs/
    │   └── ROBO_DAPP_GUIDE.md
    ├── app/                # Next.js app directory
    ├── components/
    │   ├── onchain/        # Web3, wallet, DAO components
    │   └── offchain/       # Traditional UI components
    ├── lib/                # Web3 utilities
    └── api/                # API integrations, contract ABIs

---

Benefits

1. Clear Product Boundaries

   • FleetOS team: work in fleetos/ only

   • Robo-Hub team: work in robo-hub/ only

   • Ecosystem team: work in ecosystem/ for shared code

2. Matches Documentation Structure

   • Physical structure mirrors logical structure

   • Easier to find related files

3. Better Imports

   // Before (confusing)
   import Card from '../../components/shared/Card'
   import { FleetForm } from '../../components/fleetos-clean/FleetRequestForm'
   
   // After (clear)
   import { Card } from '@ecosystem/shared/components'
   import { FleetForm } from '@fleetos/components'

4. Scalable

   • Add new products easily

   • Clear for new developers

   • Easier to split repos later if needed

---

Migration Steps (When Ready)

Phase 1: Setup (No Breaking Changes)

1. Create directory structure

   mkdir -p ecosystem/{docs,database,shared,scripts,agents}
   mkdir -p fleetos/{docs,components,services,database,scripts}
   mkdir -p robo-hub/{docs,components,services,database,scripts}

2. Update build configuration

   vite.config.ts:

   export default defineConfig({
     resolve: {
       alias: {
         '@ecosystem': path.resolve(__dirname, './ecosystem'),
         '@fleetos': path.resolve(__dirname, './fleetos'),
         '@robo-hub': path.resolve(__dirname, './robo-hub'),
         '@robo-dapp': path.resolve(__dirname, './robo-dapp'),
       }
     }
   })

   tsconfig.json:

   {
     "compilerOptions": {
       "paths": {
         "@ecosystem/*": ["./ecosystem/*"],
         "@fleetos/*": ["./fleetos/*"],
         "@robo-hub/*": ["./robo-hub/*"],
         "@robo-dapp/*": ["./robo-dapp/*"]
       }
     }
   }

Phase 2: Move Ecosystem Files

# Preserve git history with git mv
git mv components/shared ecosystem/shared/components
git mv services/shared ecosystem/shared/services
git mv services/contracts ecosystem/shared/contracts
git mv lib ecosystem/shared/lib
git mv types/shared ecosystem/shared/types
git mv hooks ecosystem/shared/hooks

# Move database
git mv database/core ecosystem/database/core
git mv database/migrations ecosystem/database/migrations
git mv database/add-row-level-security.sql ecosystem/database/

# Move scripts (ecosystem-level only)
git mv scripts ecosystem/scripts

# Move docs
git mv docs/T420_ECOSYSTEM_GUIDE.md ecosystem/docs/
git mv docs/DEVELOPMENT_GUIDE.md ecosystem/docs/
git mv docs/WORK_LOG.md ecosystem/docs/
git mv docs/SHARED_GUIDE.md ecosystem/docs/
git mv docs/FEATURES_GUIDE.md ecosystem/docs/
git mv docs/ARCHIVE_INDEX.md ecosystem/docs/
git mv docs/archive ecosystem/docs/archive
git mv T420_ECOSYSTEM_MASTER_ARCHITECTURE.md ecosystem/docs/
git mv PROGRESSIVE_AUTH_ARCHITECTURE.md ecosystem/docs/
git mv ARCHITECTURE.md ecosystem/docs/
git mv USER_FLOWS.md ecosystem/docs/
git mv DEPLOYMENT.md ecosystem/docs/

# Commit
git commit -m "refactor: Move ecosystem-level files to ecosystem/"

Phase 3: Update Imports for Ecosystem

Find and replace:

# Find all imports from shared
grep -r "from.*components/shared" --include="*.tsx" --include="*.ts"
grep -r "from.*services/shared" --include="*.tsx" --include="*.ts"
grep -r "from.*lib/" --include="*.tsx" --include="*.ts"

# Update to use @ecosystem alias
# Example:
# Before: import { Card } from '../../components/shared/Card'
# After:  import { Card } from '@ecosystem/shared/components/Card'

Test:

npm run dev
# Verify app loads
# Test all product views

Commit:

git add -A
git commit -m "refactor: Update imports to use @ecosystem alias"

Phase 4: Move FleetOS Files

# Move components
git mv components/fleetos-clean fleetos/components

# Move services
git mv services/InviteService.ts fleetos/services/
git mv services/ViralTriggerEngine.ts fleetos/services/
git mv services/ViralAnalyticsService.ts fleetos/services/

# Move database
git mv database/fleetos fleetos/database/

# Move docs
git mv docs/FLEETOS_GUIDE.md fleetos/docs/

# Commit
git commit -m "refactor: Move FleetOS files to fleetos/"

Phase 5: Update FleetOS Imports

# Update imports to use @fleetos
# Test app
# Commit
git add -A
git commit -m "refactor: Update FleetOS imports to use @fleetos alias"

Phase 6: Move Robo-Hub Files

# Move components
git mv components/robo-hub robo-hub/components

# Move services
git mv services/IntelligenceService.ts robo-hub/services/
git mv services/IntelligenceDataService.ts robo-hub/services/

# Move database
git mv database/robo-hub robo-hub/database/

# Move docs
git mv docs/ROBO_HUB_GUIDE.md robo-hub/docs/

# Commit
git commit -m "refactor: Move Robo-Hub files to robo-hub/"

Phase 7: Update Robo-Hub Imports

# Update imports
# Test app
# Commit
git commit -m "refactor: Update Robo-Hub imports to use @robo-hub alias"

Phase 8: Move Robo-Dapp Docs

# Robo-Dapp is already separate, just move docs
git mv docs/ROBO_DAPP_GUIDE.md robo-dapp/docs/

# Commit
git commit -m "refactor: Move Robo-Dapp docs to robo-dapp/"

Phase 9: Clean Up Root

# Remove now-empty directories
rmdir components services database docs/setup docs/guides

# Update root README.md to point to new structure
# Commit
git commit -m "refactor: Clean up root directory after restructure"

---

Testing Checklist

After each phase, verify:

• npm run dev starts without errors

• FleetOS loads: VITE_PRODUCT=fleetos

• Robo-Hub loads: VITE_PRODUCT=robo-hub

• Shared components render (Card, EmptyState, etc.)

• Authentication works (magic links)

• Database queries work (check browser console)

• No TypeScript errors: npm run build

---

Rollback Plan

If migration causes issues:

# Revert to last working commit
git reset --hard HEAD~1

# Or revert specific commit
git revert <commit-hash>

---

Decision Criteria

Do this migration when:

• No active feature development

• Have 2-4 hours for careful work

• Can thoroughly test afterward

• Team agrees on new structure

• Before onboarding new developers

Don't do this migration if:

• Actively developing features

• Under deadline pressure

• Haven't backed up current working state

• Team is unfamiliar with structure

---

Current Status

Status: ✅ Documented, ready for execution when appropriate Created: 2026-01-08 Last Updated: 2026-01-08 Assigned: Future refactoring sprint

---

Alternative: Gradual Migration

Instead of all-at-once, migrate one product at a time as you work on it:

1. Next time working on FleetOS: Move fleetos/ files

2. Next time working on Robo-Hub: Move robo-hub/ files

3. Last: Move ecosystem/ files

This spreads the work over time and reduces risk.

---

Note: This is a plan document. The current structure is working well. Execute this migration when the time is right, not urgently.