T420 Development Guide

Complete setup, testing, and deployment guide for the T420 ecosystem

Version: 2.0 (Consolidated) Last Updated: 2026-01-08 Consolidated From: 12 setup guides + QUICKSTART.md + guides/QUICK_START.md

---

Table of Contents

1. Prerequisites

2. Quick Start (5 Minutes)

3. Environment Configuration

4. Database Setup

5. WhatsApp Integration

6. Email Configuration

7. Running the Applications

8. Project Structure

9. Testing

10. Troubleshooting

11. Production Deployment

---

Prerequisites

Required:

• Node.js: v18+ (v20 recommended)

• npm: v9+

• Git: For version control

For Full Features:

• Supabase Account: Database access (free tier available)

• Twilio Account: WhatsApp notifications (optional, $15 free credit)

• SendGrid Account: Email notifications (optional, free tier available)

---

Quick Start (5 Minutes)

1. Clone & Install

cd C:\Projects\robo-hub
npm install

2. Create .env File

Create .env in project root:

# Supabase Configuration (Required)
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'

# Email (Optional - for magic links)
VITE_SENDGRID_API_KEY=SG.your-api-key
VITE_SENDGRID_FROM_EMAIL=[e-mail]
VITE_SENDGRID_FROM_NAME=FleetOS

# WhatsApp (Optional - for notifications)
VITE_TWILIO_ACCOUNT_SID=ACxxxxxxxxxxxxxxxx
VITE_TWILIO_AUTH_TOKEN=your-auth-token
VITE_TWILIO_WHATSAPP_FROM=whatsapp:[phone]

3. Start Development Server

npm run dev

Visit: http://localhost:3000/

That's it! You're running T420 locally.

---

Environment Configuration

Supabase Setup (Required)

Option 1: Use Existing Project

1. Go to https://supabase.com/dashboard

2. Select your project

3. Go to Settings → API

4. Copy:

   • Project URL → VITE_SUPABASE_URL

   • anon/public key → VITE_SUPABASE_ANON_KEY

   • service_role key → VITE_SUPABASE_SERVICE_ROLE_KEY

Option 2: Create New Project

1. Go to https://supabase.com

2. Click Start your project

3. Create organization (if needed)

4. Click New project

5. Fill in:

   • Name: T420-production (or your choice)

   • Database Password: Generate strong password

   • Region: Choose closest to you

6. Wait ~2 minutes for provisioning

7. Copy API credentials (see Option 1)

Product Configuration

Set VITE_PRODUCT to control which app loads:

VITE_PRODUCT=fleetos     # FleetOS (zero-signup)
VITE_PRODUCT=robo-hub    # Robo-Hub (B2B marketplace)
VITE_PRODUCT=robo-dapp   # Robo-Dapp (DAO governance - separate Next.js app)

---

Database Setup

Apply Schema and RLS Policies

Option 1: Via Supabase Dashboard (Easiest)

1. Go to https://supabase.com/dashboard/project/YOUR_PROJECT_ID/sql/new

2. Open database/add-row-level-security.sql

3. Copy contents

4. Paste into SQL editor

5. Click Run

Option 2: Via psql Command Line

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

Enter your database password when prompted.

Option 3: Via Supabase CLI

# Install Supabase CLI (if not installed)
npm install -g supabase

# Login
supabase login

# Link to project
supabase link --project-ref your-project-ref

# Apply migrations
supabase db push

Verify Database Setup

Run the check script:

node scripts/check-companies-table.js

Expected output:

✓ Connected to Supabase
✓ Tables created
✓ RLS policies active

---

WhatsApp Integration

Optional - Only needed for WhatsApp notifications.

Step 1: Sign Up for Twilio (10 minutes)

1. Go to https://www.twilio.com/try-twilio

2. Sign up with your email

3. Verify your phone number

4. Get $15 free credit

Step 2: Get Account Credentials

1. Go to https://console.twilio.com

2. Look for Account Info section:

   • Account SID: ACxxxxxxxxxxxxxxxx

   • Auth Token: Click "Show" to reveal

3. Copy both values

Step 3: Set Up WhatsApp Sandbox

1. Left sidebar: Messaging → Try it out → Send a WhatsApp message

2. You'll see:

   Join your sandbox by sending:
   join <code-here>
   To: [phone]

3. Open WhatsApp on your phone

4. Send that message to [phone]

5. Receive confirmation message

6. Your sandbox number: whatsapp:[phone]

Step 4: Add to .env

VITE_TWILIO_ACCOUNT_SID=ACxxxxxxxxxxxxxxxx
VITE_TWILIO_AUTH_TOKEN=your-auth-token
VITE_TWILIO_WHATSAPP_FROM=whatsapp:[phone]

Testing WhatsApp (via curl)

curl -X POST https://api.twilio.com/2010-04-01/Accounts/YOUR_ACCOUNT_SID/Messages.json \
  --data-urlencode "From=whatsapp:[phone]" \
  --data-urlencode "To=whatsapp:+YOUR_PHONE" \
  --data-urlencode "Body=🚨 Test from FleetOS" \
  -u YOUR_ACCOUNT_SID:YOUR_AUTH_TOKEN

Note: Twilio API calls from browser are blocked by CORS. For production, use backend API or Supabase Edge Functions.

---

Email Configuration

Optional - Needed for magic link authentication.

Step 1: Sign Up for SendGrid (10 minutes)

1. Go to https://signup.sendgrid.com/

2. Sign up with your email

3. Fill out form:

   • Company: "FleetOS" or your name

   • Role: "Developer"

   • Reason: "Transactional Emails"

4. Verify your email (check inbox)

Step 2: Create API Key

1. After email verification, go to SendGrid dashboard

2. Left sidebar: Settings → API Keys

3. Click Create API Key

4. Name: FleetOS Production

5. Permissions: Full Access

6. Click Create & View

7. COPY THE API KEY NOW (you can't see it again!)

Step 3: Verify Sender Email

1. Left sidebar: Settings → Sender Authentication

2. Click Verify a Single Sender

3. Fill out form:

   • From Name: FleetOS

   • From Email: [e-mail]

   • Reply To: Same as above

   • Company Address: Your address (required)

4. Click Create

5. Check your email and click verification link

6. Once verified, use that email as VITE_SENDGRID_FROM_EMAIL

Step 4: Add to .env

VITE_SENDGRID_API_KEY=SG.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
VITE_SENDGRID_FROM_EMAIL=[e-mail]
VITE_SENDGRID_FROM_NAME=FleetOS

Test Email

1. Restart dev server: npm run dev

2. Go to supplier signup page

3. Enter your email

4. Check inbox for magic link

---

Running the Applications

FleetOS (Zero-Signup Flow)

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

Set product in .env:

VITE_PRODUCT=fleetos

Features:

• Zero-signup request/response

• Supplier onboarding

• Fleet coordination

• Magic link authentication

Robo-Hub (B2B Marketplace)

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

Set product in .env:

VITE_PRODUCT=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/

Features:

• Wallet authentication (MetaMask, WalletConnect)

• DAO governance

• On-chain operations

---

Project Structure

robo-hub/
├── components/
│   ├── shared/           # Shared UI components (Card, EmptyState, etc.)
│   ├── fleetos-clean/    # FleetOS components (clean rebuild)
│   └── robo-hub/         # Robo-Hub components
│
├── services/
│   ├── contracts/        # TypeScript service interfaces
│   ├── shared/           # Shared services (QueryService)
│   ├── AuthService.ts    # Authentication & magic links
│   ├── RelationshipService.ts
│   ├── IntelligenceService.ts
│   └── ViralTriggerEngine.ts
│
├── lib/
│   ├── chatTypeGuards.ts # Runtime type checking
│   ├── styleHelpers.ts   # Theme utilities
│   ├── supabase.ts       # Supabase client
│   └── domainExtraction.ts
│
├── types/
│   ├── shared/           # Shared types (User, AuthTier)
│   ├── robo-hub/         # Robo-Hub specific types
│   └── index.ts          # Exports
│
├── hooks/
│   └── useLocalStorage.ts # Shared localStorage hook
│
├── database/
│   ├── core/             # Core schema (users, relationships)
│   ├── fleetos/          # FleetOS-specific tables
│   ├── robo-hub/         # Robo-Hub specific tables
│   ├── add-row-level-security.sql
│   └── migrations/       # Schema migrations
│
├── docs/
│   ├── T420_ECOSYSTEM_GUIDE.md     # This ecosystem guide
│   ├── DEVELOPMENT_GUIDE.md        # This file
│   ├── FLEETOS_GUIDE.md            # FleetOS documentation
│   ├── ROBO_HUB_GUIDE.md           # Robo-Hub documentation
│   ├── FEATURES_GUIDE.md           # Feature documentation
│   └── WORK_LOG.md                 # Development history
│
├── scripts/
│   ├── check-companies-table.js    # Verify database
│   ├── run-migration-002.js        # Run migrations
│   └── ...                         # Other utilities
│
└── Robo-Dapp/           # Separate Next.js app (DAO governance)
    ├── app/
    ├── components/
    └── package.json

---

Testing

Manual Testing

FleetOS Zero-Signup Flow:

1. Visit http://localhost:3000/ (with VITE_PRODUCT=fleetos)

2. Click "Get My Free Agent Number"

3. Fill form with email

4. Check email for magic link

5. Click link → Should log in

6. Test service request flow

Robo-Hub Dashboard:

1. Visit http://localhost:3000/ (with VITE_PRODUCT=robo-hub)

2. Login as Shepherd

3. Create RFQ

4. Test contract flow

Database Verification

# Check tables exist
node scripts/check-companies-table.js

# Run migration
node scripts/run-migration-002.js

API Testing

Use browser console to test services:

// Test QueryService
import { QueryService } from './services/shared/QueryService';
const requests = await QueryService.getServiceRequests();
console.log(requests);

// Test AuthService
import { AuthService } from './services/AuthService';
const result = await AuthService.sendMagicLink('[e-mail]');
console.log(result);

---

Troubleshooting

Common Issues

1. "npm install" fails

# Clear cache
npm cache clean --force
rm -rf node_modules
rm package-lock.json
npm install

2. Supabase connection error

# Verify credentials in .env
echo $VITE_SUPABASE_URL
echo $VITE_SUPABASE_ANON_KEY

# Test connection
node scripts/check-companies-table.js

3. Email not sending

Check:

• SendGrid API key is correct

• Sender email is verified in SendGrid dashboard

• API key has "Full Access" permissions

• Check spam folder

Debug:

// Browser console
console.log(import.meta.env.VITE_SENDGRID_API_KEY); // Should show key
console.log(import.meta.env.VITE_SENDGRID_FROM_EMAIL); // Should show email

4. WhatsApp not working

Remember: WhatsApp calls from browser are blocked by CORS.

Solutions:

• Test via curl (see WhatsApp section)

• Use Twilio console test tool

• Move to backend API for production

5. Magic link expired

Links expire in 24 hours. Request a new one by logging in again.

6. Port 3000 already in use

# Find process using port 3000
netstat -ano | findstr :3000  # Windows
lsof -i :3000                  # Mac/Linux

# Kill process
taskkill /PID <process-id> /F  # Windows
kill -9 <process-id>           # Mac/Linux

# Or use different port
npm run dev -- --port 3001

7. Vite build errors

# Clear Vite cache
rm -rf node_modules/.vite
npm run dev

---

Production Deployment

Pre-Deployment Checklist

• All .env variables configured

• Database RLS policies applied

• SendGrid sender email verified

• Twilio sandbox approved (or production WhatsApp enabled)

• Tested all auth flows

• Tested magic links

• Build succeeds: npm run build

Build for Production

npm run build

Output: dist/ directory

Deploy to Vercel (Recommended)

# Install Vercel CLI
npm install -g vercel

# Deploy
vercel

# Add environment variables in Vercel dashboard
vercel env add VITE_SUPABASE_URL production
vercel env add VITE_SUPABASE_ANON_KEY production
# ... add all other env vars

Deploy to Netlify

# Install Netlify CLI
npm install -g netlify-cli

# Build
npm run build

# Deploy
netlify deploy --prod --dir=dist

Environment Variables for Production

Add to hosting platform:

• VITE_SUPABASE_URL

• VITE_SUPABASE_ANON_KEY

• VITE_SUPABASE_SERVICE_ROLE_KEY

• VITE_SENDGRID_API_KEY

• VITE_SENDGRID_FROM_EMAIL

• VITE_SENDGRID_FROM_NAME

• VITE_TWILIO_ACCOUNT_SID

• VITE_TWILIO_AUTH_TOKEN

• VITE_TWILIO_WHATSAPP_FROM

• VITE_PRODUCT

Production Database Setup

1. Create production Supabase project

2. Apply schema: Run database/add-row-level-security.sql

3. Run migrations: Execute all files in database/migrations/

4. Seed data (optional): Run seed scripts if needed

Post-Deployment

• Test magic links from production domain

• Verify email delivery

• Test WhatsApp notifications

• Monitor Supabase dashboard for errors

• Check browser console for errors

---

Additional Resources

Documentation:

• T420 Ecosystem Guide - Architecture overview

• FleetOS Guide - FleetOS product documentation

• Robo-Hub Guide - Robo-Hub product documentation

• Features Guide - Viral engine, agentic workflow

• Work Log - Development history

External Resources:

• Supabase Docs

• Vite Docs

• Twilio WhatsApp API

• SendGrid API

---

Version: 2.0 (Consolidated) Consolidated From: 12 setup guides + 2 quickstart files Last Updated: 2026-01-08 Maintained By: Development Team