Shared Documentation

Documentation for shared components, services, and utilities used across all three products.

Overview

The T420 ecosystem shares core functionality across FleetOS, Robo-Hub, and Robo-Dapp to maintain consistency and reduce duplication.

---

Shared Components

See: components/shared/README.md

Available Components:

1. Card - Reusable card container with 4 variants

2. EmptyState - Standardized no-data UI

3. Breadcrumb - Navigation breadcrumbs

4. FilterBar - Search/filter/sort interface

5. chatHelpers - Message rendering utilities

Impact: ~2,000 lines of duplicate code eliminated

---

Shared Services

See: services/shared/README.md

Available Services:

1. QueryService - Centralized database queries

   • Eliminates 100+ duplicate Supabase queries

   • Type-safe, cacheable

   • Single source of truth

Service Contracts: See: services/contracts/

1. IAuthService - Authentication across all products

2. IRoutingService - Identity resolution and routing

3. IRelationshipService - Relationship management

4. INotificationService - Multi-channel notifications

5. IIntelligenceService - Analytics and insights

---

Shared Types

See: types/shared/

Type Definitions:

1. auth.ts - User, AuthTier, AuthPermissions

2. common.ts - View, Theme, City, ServiceCategory

Usage:

import { User, AuthTier } from '@/types/shared/auth';
import { View, City } from '@/types/shared/common';

---

Shared Utilities

Type Guards

File: lib/chatTypeGuards.ts

Purpose: Runtime type checking for chat messages

Functions:

• isUserMessage(message) - Check if user message

• isSystemMessage(message) - Check if system message

• isAIMessage(message) - Check if AI message

• hasRecommendation(metadata) - Check for recommendation metadata

Style Helpers

File: lib/styleHelpers.ts

Purpose: Centralized theme colors and utilities

Exports:

• themeColors - Product-specific color palettes

• getBorderStyle() - Consistent border styling

• getButtonStyles() - Standardized button variants

localStorage Hook

File: hooks/useLocalStorage.ts

Purpose: Type-safe, SSR-safe localStorage hook

Usage:

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

---

Database Schema

Shared Tables

Core Tables:

1. users - User accounts (all products)

2. user_profiles - Extended user data

3. service_requests - Service requests (all products)

4. notifications - Multi-channel notifications

5. relationships - Supplier-fleet relationships

Product Isolation:

• source_product column ('fleetos' | 'robo-hub' | 'robo-dapp')

• Row-Level Security (RLS) policies

• Product-specific views

RLS Policies

See: database/add-row-level-security.sql

Enforced Isolation:

• FleetOS users cannot see Robo-Hub data

• Robo-Hub users cannot see Robo-Dapp data

• Users can only see their own data

Apply:

psql < database/add-row-level-security.sql

---

Progressive Authentication Tiers

All three products share the same authentication tier system:

Tier 1: ANONYMOUS
- Browse public pages
- View landing pages
- No database access

Tier 2: MAGIC_LINK
- Submit requests via magic link
- Receive updates
- Temporary session

Tier 3: AUTHENTICATED
- Full account creation
- Create invites
- Manage relationships
- FleetOS full access

Tier 4: ROBO_HUB
- RFQ creation
- Contract management
- Zone assignments
- Robo-Hub full access

Tier 5: ROBO_DAPP
- DAO voting
- On-chain operations
- Governance participation
- Robo-Dapp full access

Upgrade Triggers:

• Tier 2→3: User wants to create invites

• Tier 3→4: User manages 10+ suppliers

• Tier 4→5: User needs blockchain features

---

Shared Design Principles

1. Zero-Signup Philosophy

Competing with: Email & WhatsApp Must be: AS EASY or easier

Flow: Receive → Respond → (Name+Email if first time) → Done

2. Calm, Professional, Infrastructure-like

• No pushy tactics

• No heavy signup forms

• Just works, like email

• "Calm by FleetOS"

3. Progressive Enhancement

• Start simple (FleetOS)

• Add features as needed (Robo-Hub)

• Unlock advanced capabilities (Robo-Dapp)

4. Product Separation

• Clear boundaries

• Shared core

• Product-specific extensions

• No cross-product data leaks

---

Shared Workflows

Magic Link Authentication

1. User provides email
   ↓
2. System generates magic link token
   ↓
3. Send via email/WhatsApp
   ↓
4. User clicks link
   ↓
5. Verify token
   ↓
6. Create session (Tier 2: MAGIC_LINK)
   ↓
7. Prompt for name if first time
   ↓
8. Done - user authenticated

Identity Resolution

1. Receive request with contact info
   ↓
2. Extract email domain
   ↓
3. Look up company by domain
   ↓
4. Create company if not exists
   ↓
5. Link contact to company
   ↓
6. Establish relationship

Request Routing

1. Parse request (web form, WhatsApp, email)
   ↓
2. Resolve supplier ID
   ↓
3. Resolve fleet user ID
   ↓
4. Check for active relationship
   ↓
5. Route:
   - Active relationship → active_queue
   - No relationship → pending_queue

---

Migration Guide

See: services/MIGRATION_NOTES.md

Key Changes:

1. Import QueryService from @/services/shared/QueryService

2. Use shared components from @/components/shared/

3. Import types from @/types/shared/

4. Use service contracts from @/services/contracts/

---

Testing Shared Code

Component Testing

import { render, screen } from '@testing-library/react';
import { Card } from '@/components/shared/Card';

test('renders card', () => {
  render(<Card>Test</Card>);
  expect(screen.getByText('Test')).toBeInTheDocument();
});

Service Testing

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

test('gets service requests', async () => {
  const requests = await QueryService.getServiceRequests({
    status: 'pending'
  });
  expect(Array.isArray(requests)).toBe(true);
});

Type Guard Testing

import { isUserMessage } from '@/lib/chatTypeGuards';

test('identifies user message', () => {
  const message = { senderType: 'supplier', text: 'Hello' };
  expect(isUserMessage(message)).toBe(true);
});

---

Related Documentation

• Quick Start: docs/guides/QUICK_START.md

• Work Log: docs/WORK_LOG.md

• Master Architecture: T420_ECOSYSTEM_MASTER_ARCHITECTURE.md

• Components: components/shared/README.md

• Services: services/shared/README.md

• Contracts: services/contracts/

---

Last Updated: 2026-01-05 Maintained By: System Architect Status: Active - Shared across all products