Quick Start Guide - T420 Robo-Hub

Get up and running with the T420 ecosystem in minutes.

---

Prerequisites

• Node.js: v18+ (v20 recommended)

• npm: v9+

• Supabase Account: For database access

• Git: For version control

---

Installation

1. Clone & Install

cd C:\Projects\robo-hub
npm install

2. Environment Setup

Create .env file in project root:

# Supabase Configuration
VITE_SUPABASE_URL=https://your-project.supabase.co
VITE_SUPABASE_ANON_KEY=your-anon-key
VITE_SUPABASE_SERVICE_ROLE_KEY=your-service-role-key

# Product Configuration
VITE_PRODUCT=robo-hub  # or 'fleetos' or 'robo-dapp'

3. Database Setup (Optional)

If starting fresh, apply RLS policies:

psql -h your-supabase-host.supabase.co -U postgres -d postgres < database/add-row-level-security.sql

---

Running the Apps

FleetOS (Standalone)

npm run dev
# Visit: http://localhost:3000/fleetos-demo.html

FleetOS Features:

• Zero-signup request/response flow

• Supplier onboarding

• Fleet coordination

• Magic link authentication

Robo-Hub (Main App)

npm run dev
# Visit: http://localhost:3000/

Robo-Hub Features:

• Shepherd dashboard

• RFQ management

• Contract negotiations

• Zone assignments

Robo-Dapp (Separate Next.js App)

cd Robo-Dapp
npm install
npm run dev
# Visit: http://localhost:3001/

Robo-Dapp Features:

• Wallet authentication

• DAO governance

• On-chain operations

---

Project Structure

robo-hub/
├── components/
│   ├── shared/           # Shared UI components
│   ├── fleetos/          # FleetOS legacy components
│   ├── fleetos-clean/    # FleetOS clean rebuild (8 components)
│   └── robo-hub/         # Robo-Hub components
│
├── services/
│   ├── contracts/        # TypeScript service interfaces
│   ├── shared/           # Shared services (QueryService)
│   └── *.ts              # Service implementations
│
├── lib/
│   ├── chatTypeGuards.ts # Runtime type checking
│   ├── styleHelpers.ts   # Theme utilities
│   └── supabase.ts       # Supabase client
│
├── types/
│   ├── shared/           # Shared types (User, AuthTier, etc.)
│   ├── robo-hub/         # Robo-Hub specific types
│   └── index.ts          # Backward compatibility exports
│
├── hooks/
│   └── useLocalStorage.ts # Shared localStorage hook
│
├── docs/
│   ├── guides/           # This file
│   ├── archive/          # Historical documentation
│   └── WORK_LOG.md       # Development work log
│
└── database/
    ├── core/             # Core schema (users, relationships)
    ├── fleetos/          # FleetOS-specific tables
    ├── robo-hub/         # Robo-Hub specific tables
    └── add-row-level-security.sql # RLS policies

---

Using Shared Components

Card Component

import { Card, CardHeader, CardFooter } from '@/components/shared/Card';

<Card variant="featured" onClick={handleClick}>
  <CardHeader>
    <h3>Title</h3>
  </CardHeader>
  <div style={{ padding: '20px' }}>
    Content goes here
  </div>
  <CardFooter>
    <button>Action</button>
  </CardFooter>
</Card>

EmptyState Component

import { EmptyState } from '@/components/shared/EmptyState';

<EmptyState
  icon="📭"
  title="No Requests"
  description="Requests will appear here."
  actionLabel="Create Request"
  onAction={() => setView('CREATE')}
/>

FilterBar Component

import { FilterBar } from '@/components/shared/FilterBar';

<FilterBar
  searchValue={search}
  onSearchChange={setSearch}
  filterOptions={[
    { value: 'pending', label: 'Pending' },
    { value: 'completed', label: 'Completed' }
  ]}
  filterValue={filter}
  onFilterChange={setFilter}
/>

---

Using Shared Services

QueryService (Replaces Direct Supabase Calls)

Old way:

const { data } = await supabase
  .from('service_requests')
  .select('*')
  .eq('status', 'pending');

New way:

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

const requests = await QueryService.getServiceRequests({
  status: 'pending'
});

useLocalStorage Hook

Old way:

const user = JSON.parse(localStorage.getItem('user') || 'null');
localStorage.setItem('user', JSON.stringify(newUser));

New way:

import { useLocalStorage } from '@/hooks/useLocalStorage';

const [user, setUser, removeUser] = useLocalStorage<User>('user', null);
setUser(newUser); // Automatically persists

---

Development Workflow

1. Start Development Server

npm run dev

2. Make Changes

Edit files in components/, services/, or lib/

3. Type Check

npm run type-check

4. Build

npm run build

5. Preview Build

npm run preview

---

Common Tasks

Adding a New View

1. Add view to types/shared/common.ts:

   export type View =
     | 'LANDING'
     | 'YOUR_NEW_VIEW'
     | ...;

2. Create component in appropriate folder:

   // components/robo-hub/YourNewView.tsx
   export function YourNewView() {
     return <div>Your content</div>;
   }

3. Add routing in App.tsx:

   case 'YOUR_NEW_VIEW':
     return <YourNewView />;

Creating a New Service

1. Define contract in services/contracts/:

   // services/contracts/IYourService.ts
   export interface IYourService {
     doSomething(): Promise<void>;
   }

2. Implement service:

   // services/YourService.ts
   import { IYourService } from './contracts/IYourService';
   
   class YourService implements IYourService {
     async doSomething() { ... }
   }
   
   export default new YourService();

Adding Database Queries

Add to QueryService:

// services/shared/QueryService.ts
export class QueryService {
  static async getYourData(filters: YourFilters) {
    const { data, error } = await supabase
      .from('your_table')
      .select('*')
      .match(filters);

    if (error) throw error;
    return data || [];
  }
}

---

Testing

Manual Testing

1. FleetOS: Visit /fleetos-demo.html

2. Robo-Hub: Visit /

3. Components: Create test pages like demo-*.html

Type Checking

npm run type-check

Build Testing

npm run build
# Check for type errors and build issues

---

Authentication Flow

FleetOS (Magic Link)

1. User receives WhatsApp/email with magic link

2. Click link → lands on /respond?requestId=xxx

3. View request details

4. Respond (prompts for name + email if first time)

5. Done - no signup required

Robo-Hub (Email + Password)

1. User signs up with email

2. Verify email

3. Choose role (Shepherd/Supplier)

4. Access dashboard

Robo-Dapp (Wallet)

1. Connect wallet (MetaMask, WalletConnect)

2. Sign message to verify ownership

3. Link to email account (optional)

4. Access DAO features

---

Troubleshooting

Port Already in Use

# Kill process on port 3000 (Windows)
netstat -ano | findstr :3000
taskkill /PID <PID> /F

# Kill process on port 3000 (Linux/Mac)
lsof -ti:3000 | xargs kill

Supabase Connection Issues

1. Check .env file has correct credentials

2. Verify Supabase project is running

3. Check RLS policies don't block your queries:

   -- Temporarily disable RLS for testing
   ALTER TABLE service_requests DISABLE ROW LEVEL SECURITY;

Type Errors

# Clear TypeScript cache
rm -rf node_modules/.vite
rm -rf dist

# Reinstall
npm install

# Rebuild
npm run build

Module Not Found

If you see "Cannot find module '@/components/shared/Card'":

1. Check the file exists

2. Verify import path uses @/ alias

3. Restart dev server (Ctrl+C then npm run dev)

---

Next Steps

1. Read Architecture: T420_ECOSYSTEM_MASTER_ARCHITECTURE.md

2. Review Work Log: docs/WORK_LOG.md

3. Explore Components: components/shared/README.md

4. Study Services: services/shared/README.md

5. Check Contracts: services/contracts/

---

Getting Help

• Documentation: Check docs/ folder

• Work Log: See docs/WORK_LOG.md for recent changes

• Archive: Historical docs in docs/archive/2026-01/

• Code Examples: Look in components/fleetos-clean/ for clean implementations

---

Last Updated: 2026-01-05 Version: 1.0 Status: Active Development