search

T420 Ecosystem Guide

Complete guide to the T420 ecosystem architecture, products, and documentation

Version: 2.0 Last Updated: 2026-01-08 Status: Active - Consolidated Master Document

hashtag
Table of Contents

  1. Introduction

  2. Documentation Structure

  3. The 100-20-2 Market Strategy

  4. Progressive Authentication

  5. Shared Infrastructure

  6. Finding Information

  7. Documentation Philosophy

hashtag
Introduction

T420 is ONE SYSTEM with THREE PRODUCTS serving different market segments.

The T420 ecosystem consists of three interconnected products built on shared infrastructure:

┌─────────────────────────────────────────────────────────────────┐
│                    T420 PROTOCOL (One System)                    │
│                                                                   │
│  Shared Infrastructure:                                          │
│  • Relationship Graph (Fleet ↔ Supplier connections)            │
│  • User Authentication (Magic links, JWT, Web3)                 │
│  • Notification Engine (WhatsApp, Email, SMS)                   │
│  • Intelligence Layer (Pattern detection, baselines, AI)        │
│  • Database (PostgreSQL/Supabase - shared schema)               │
│                                                                   │
└─────────────────────────────────────────────────────────────────┘
                              │
                 ┌────────────┼────────────┐
                 │            │            │
         ┌───────▼──────┐ ┌──▼──────┐ ┌──▼──────────┐
         │   FleetOS    │ │Robo-Hub │ │ Robo-Dapp   │
         │              │ │         │ │             │
         │  100% US     │ │ 20% US  │ │   2% US     │
         │  Market      │ │ Market  │ │  Market     │
         │              │ │         │ │             │
         │  FREE        │ │ PAID    │ │  PREMIUM    │
         │  Entry Point │ │ B2B     │ │  On-Chain   │
         └──────────────┘ └─────────┘ └─────────────┘
              │                │              │
              └────────────────┴──────────────┘
                    Users Flow Upward

hashtag
Documentation Structure

hashtag
Master Documents (9 Total)

The T420 documentation is organized into 9 comprehensive master documents:

hashtag
Ecosystem Level

  1. T420_ECOSYSTEM_GUIDE.md (this document) - Architecture, products, finding information

  2. DEVELOPMENT_GUIDE.md - Setup, installation, testing, deployment

  3. WORK_LOG.md - Chronological development history

hashtag
Product Level

  1. FLEETOS_GUIDE.md - Complete FleetOS product guide

  2. ROBO_HUB_GUIDE.md - Complete Robo-Hub product guide

  3. ROBO_DAPP_GUIDE.md - Complete Robo-Dapp product guide

hashtag
Technical Reference

  1. FEATURES_GUIDE.md - Viral engine, agentic workflow, UX patterns

  2. SHARED_GUIDE.md - Shared components and services

  3. ARCHIVE_INDEX.md - Historical documentation index

hashtag
Root Project Files

Located in the project root directory:

  • T420_ECOSYSTEM_MASTER_ARCHITECTURE.md - Detailed technical architecture (18,000+ lines)

  • PROGRESSIVE_AUTH_ARCHITECTURE.md - Authentication system design

  • ARCHITECTURE.md - Technical implementation details

  • USER_FLOWS.md - User journey documentation

  • DEPLOYMENT.md - Production deployment guide

hashtag
The 100-20-2 Market Strategy

hashtag
Market Segmentation

Product
Market Size
Target Users
Complexity
Revenue

FleetOS

100% US Market

Independent mobile service providers + Regular fleets

LOW (Free coordination tool)

Freemium ($0-49/mo)

Robo-Hub

20% US Market

Professional suppliers + Shepherds (entrepreneurs)

MEDIUM (B2B marketplace)

B2B (NFT sales, contracts)

Robo-Dapp

2% US Market

Shepherds operating T420 robotaxi fleets

HIGH (On/off-chain ops)

Protocol fees, staking

hashtag
US Fleet Maintenance & Repair Market: ~$80B Annually

  • FleetOS TAM: $80B (100%) - All mobile service providers

    • Mobile tire shops: 15,000+ businesses

    • Mobile mechanics: 25,000+ operators

    • EV charging: 5,000+ providers

    • Tow/roadside: 30,000+ operators

    • Glass repair: 8,000+ mobile units

  • Robo-Hub TAM: $16B (20%) - Professional suppliers + entrepreneurs

    • Multi-location suppliers

    • Contract-seeking businesses

    • Zone license buyers (Shepherds)

  • Robo-Dapp TAM: $1.6B (2%) - T420 robotaxi operators

    • Shepherd-operated fleets

    • Protocol participants

    • DePIN stakeholders

hashtag
Product Positioning

FleetOS: The Volume Play

  • Tagline: "From Chaos to Compliance"

  • Zero-signup service coordination

  • Competing with email & WhatsApp

  • Must be AS EASY or easier

  • Calm, professional, infrastructure-like

Robo-Hub: The Professional Tier

  • B2B marketplace with RFQs

  • Contract management

  • Zone-based routing

  • Shepherd empowerment

Robo-Dapp: The Premium Experience

  • DAO governance

  • On-chain contract execution

  • Wallet authentication

  • Token economics

hashtag
Progressive Authentication

hashtag
The 5-Tier System

Tier 0: Anonymous (FleetOS)

  • No signup required

  • Receive service request

  • Respond inline

  • Provide name/email only if first time

Tier 1: Magic Link

  • Click link in email

  • Instant access

  • No password needed

Tier 2: Authenticated

  • Session established

  • Full FleetOS features

  • Profile management

Tier 3: Robo-Hub

  • B2B marketplace access

  • RFQ creation

  • Contract management

Tier 4: Robo-Dapp

  • Wallet connection

  • DAO voting

  • On-chain contracts

hashtag
Zero-Signup Philosophy

Competing with: Email & WhatsApp Must be: AS EASY or easier, or they won't switch Flow: Receive → Respond → (Name+Email if first time) → Done

Calm by FleetOS

  • No pushy tactics

  • No heavy signup forms

  • Just works, like email

  • Professional infrastructure feel

hashtag
Shared Infrastructure

hashtag
Database (Supabase/PostgreSQL)

Shared Tables:

  • users - All users across all products

  • user_profiles - Profile data

  • relationships - Fleet ↔ Supplier connections

  • service_requests - All service requests

  • notifications - Email/SMS/WhatsApp notifications

  • viral_events - Growth tracking

Product-Specific Tables:

  • FleetOS: fleetos_invites, fleetos_tracking_tokens

  • Robo-Hub: rfqs, contracts, zones

  • Robo-Dapp: dao_proposals, dao_votes

hashtag
Services Layer

Shared Services:

  • AuthService - Authentication & magic links

  • RelationshipService - Fleet-supplier connections

  • IntelligenceService - Pattern detection & baselines

  • IntelligenceDataService - Intelligence data access

  • ViralTriggerEngine - Growth moments

  • ViralAnalyticsService - Growth tracking

Product Services:

  • InviteService - FleetOS invitations

  • NotificationService - Multi-channel notifications (being refactored)

  • WhatsAppService - WhatsApp integration

hashtag
Components

Shared Components (components/shared/):

  • BaseChatInterface - Base for all chat UIs

  • Card - 4 variants (default, elevated, interactive, outlined)

  • EmptyState - Standardized empty states

  • Breadcrumb - Navigation breadcrumbs

  • FilterBar - Search/filter/sort component

Product Components:

  • FleetOS: components/fleetos-clean/

  • Robo-Hub: components/robo-hub/

  • Robo-Dapp: Robo-Dapp/ (separate Next.js app)

hashtag
Finding Information

hashtag
Quick Reference

I want to...

...get started quickly → DEVELOPMENT_GUIDE.md

...understand the detailed architecture → ../T420_ECOSYSTEM_MASTER_ARCHITECTURE.mdarrow-up-right

...see what was built recently → WORK_LOG.md (top section)

...understand FleetOS → FLEETOS_GUIDE.md

...understand Robo-Hub → ROBO_HUB_GUIDE.mdarrow-up-right

...understand Robo-Dapp → ROBO_DAPP_GUIDE.mdarrow-up-right

...use shared components → SHARED_GUIDE.mdarrow-up-right or components/shared/README.md

...learn about features → FEATURES_GUIDE.md

...find historical context → ARCHIVE_INDEX.md

...troubleshoot an issue → DEVELOPMENT_GUIDE.md#troubleshooting

hashtag
For New Developers

Day 1:

  1. Read this document (T420_ECOSYSTEM_GUIDE.md)

  2. Follow DEVELOPMENT_GUIDE.md

  3. Review WORK_LOG.md (recent entries)

Week 1: 4. Explore product-specific guides (FleetOS, Robo-Hub, or Robo-Dapp) 5. Review SHARED_GUIDE.mdarrow-up-right 6. Study FEATURES_GUIDE.md

Ongoing: 7. Check WORK_LOG.md for recent changes 8. Consult ../T420_ECOSYSTEM_MASTER_ARCHITECTURE.mdarrow-up-right for deep architectural details

hashtag
Documentation Philosophy

hashtag
1. Progressive Detail

  • Quick Start: Get running in 5 minutes

  • Product Guides: Understand specific features

  • Shared Docs: Learn reusable patterns

  • Work Log: Deep dive into development history

  • Archive: Historical context when needed

hashtag
2. Single Source of Truth

  • 9 master documents (not 93 scattered files)

  • Clear ownership: FLEETOS_GUIDE.md owns all FleetOS docs

  • No duplicate setup guides

  • Historical docs properly archived

hashtag
3. Living Documentation

  • Updated as code changes

  • Located close to code

  • Includes real code examples

  • Links to actual files

hashtag
4. Developer-Focused

  • How to use, not just what it is

  • Common tasks and troubleshooting

  • Migration guides for breaking changes

  • Testing examples

hashtag
Contributing to Documentation

hashtag
When to Update Docs

Always update when:

  • Adding new shared components → Update SHARED_GUIDE.md

  • Creating new services → Update SHARED_GUIDE.md

  • Changing service contracts → Update SHARED_GUIDE.md

  • Modifying authentication flow → Update PROGRESSIVE_AUTH_ARCHITECTURE.md

  • Restructuring folders → Update this document

Document in Work Log when:

  • Completing major features

  • Making architectural decisions

  • Encountering important learnings

  • Solving tricky bugs

hashtag
Where to Document

What
Where

Ecosystem concepts

T420_ECOSYSTEM_GUIDE.md (this doc)

Setup/installation

DEVELOPMENT_GUIDE.md

FleetOS features

FLEETOS_GUIDE.md

Robo-Hub features

ROBO_HUB_GUIDE.md

Robo-Dapp features

ROBO_DAPP_GUIDE.md

Shared components/services

SHARED_GUIDE.md

Feature documentation

FEATURES_GUIDE.md

Development history

WORK_LOG.md

Historical context

Archive (via ARCHIVE_INDEX.md)

hashtag
Recent Major Changes

hashtag
2026-01-08: Documentation Consolidation ✅

  • Consolidated 93 files → 9 master documents

  • Eliminated 10 duplicate files

  • Reduced documentation by 66%

  • Created single source of truth per topic

  • Preserved all historical docs in archive

hashtag
2026-01-08: Phase 3 Cleanup ✅

  • Removed scraper/ directory (5,474 files)

  • Kept Robo-Dapp (part of ecosystem)

  • Kept verify-app (Claude plugin)

hashtag
2026-01-08: Major Code Cleanup ✅

  • Removed 63 obsolete files

  • Deleted 32 migration/test scripts

  • Removed 6 agent service files

  • Archived 7 completion docs

  • Scripts reduced: 45 → 13 (71% reduction)

hashtag
2026-01-05: System Architect Cleanup ✅

  • Created 12 new files (contracts, components, docs)

  • Archived 19 historical MD files

  • Reduced code duplication by ~2,000 lines

  • Established clear documentation structure

  • Created formal service contracts

hashtag
Support & Feedback

For questions about:

To contribute:

  1. Update relevant master document (don't create new files)

  2. Add entry to WORK_LOG.md if significant

  3. Keep examples up-to-date with code

  4. Archive old docs when superseded (add to archive/2026-01/)

Documentation Version: 2.0 (Consolidated) Last Major Update: 2026-01-08 Consolidated From: docs/README.md, docs/INDEX.md, architecture references Status: Active Development Maintained By: Development Team

PreviousTable of contentsNextThe T420 Protocol: The Operating System for the Robotaxi Era

Last updated

Was this helpful?