T420 Robo-Hub: System Architecture Blueprint

⚠️ IMPORTANT: This is Robo-Hub product documentation (NOT FleetOS)

• Robo-Hub = 2-sided marketplace (Shepherds ↔ Suppliers)

• FleetOS = Simple supplier directory utility

• See /docs/fleetos/ for FleetOS documentation

---

1. Executive Summary

The T420 Robo-Hub is the Strategic Sourcing & Governance Platform for the T420 Protocol. It serves two primary functions:

1. The Primary Market: Selling "Zone Licenses" (Shepherd NFTs) to entrepreneurs.

2. The B2B Marketplace: Connecting those Shepherds with Suppliers to establish infrastructure contracts.

Note: Operational features (Fleet Cards, Daily Dispatch, Real-time Payments) reside in the separate Robo-Dapp application.

---

2. Technology Stack (Production Target)

A. Interface Layer (Frontend)

• Framework: Next.js 14+ (App Router)

• Styling: Tailwind CSS + CSS Variables (Theming).

• State Management: React Context + TanStack Query.

B. Logic Layer (Backend / API)

• Runtime: Next.js Serverless API Routes.

• AI Engine: Google Gemini 2.5 Flash (Server-Side) for logistics analysis and negotiation simulation.

C. State Layer (Database & Auth)

• Platform: Supabase (Managed PostgreSQL).

• Authentication:

  • Shepherds: Web3 Wallet Connect (SIWE) - Tied to NFT ownership.

  • Suppliers: Email/Password (Web2) - Tied to Business Verification.

D. Protocol Layer (Web3 / Blockchain)

• Chain: Base (L2) or Solana.

• Smart Contracts:

  • T420 Token: Governance & Staking.

  • Shepherd NFT: Zone-based "License to Operate".

  • Staking Contract: Manages the $5,000 base stake + $500/vehicle stake.

  • Revenue Distributor: The 42/42/16 Split Logic.

---

3. Data Schema (Entity Relationships)

Core Tables

1. users

   • id, wallet_address, role (SHEPHERD/SUPPLIER)

   • nft_zone_id (The specific territory they own)

2. zone_licenses (The Product)

   • zone_id (e.g., "mia-south-beach")

   • total_capacity (e.g., 10)

   • sold_count (e.g., 4)

   • hub_allowance (Max fleets per license)

3. contracts (The Sourcing Result)

   • id (UUID)

   • shepherd_id (FK)

   • supplier_id (FK)

   • status (ACTIVE, NEGOTIATING)

   • agreed_rates (JSON)

   • Note: These contracts are exported to Robo-Dapp for execution.

---

4. Operational Flows

A. The Shepherd Flow (Buy Side)

1. Discovery: User explores City Zones (Market Research).

2. Acquisition: User Mints Zone License NFT ($5k Stake).

3. Sourcing: User accesses the "Marketplace" to find Suppliers in their Zone.

4. Contracting: User employs AI Agent to negotiate rates.

5. Handoff: User clicks "Launch Robo-Dapp" to begin operations using these contracts.

B. The Supplier Flow (Sell Side)

1. Registration: Business verification and category listing.

2. Negotiation: Receiving and accepting RFQs from Shepherds.

3. Integration: Setting up API hooks (T420 Connect) for the Robo-Dapp to call later.

---

5. AI-Assisted Procurement & Negotiation Protocol (The "Real" Version)

The AI Agent is not a sentient negotiator. It is a data-driven, asynchronous state machine that automates research, comparison, and communication to provide the Shepherd with decision-making leverage. This is a "human-in-the-loop" system.

Phase 1: RFQ Generation (Shepherd Initiates)

• The Shepherd selects 2-5 vendors from the Marketplace and clicks "Dispatch Agent".

• The system generates a standardized Request for Quote (RFQ) based on the Shepherd's BusinessConfig (e.g., "Requesting bids for 50 Tesla Model Y tire rotations per month for 12 months in the 'Downtown LA' zone.").

• This RFQ is saved to the database and sent to the selected Suppliers' dashboards (or their API endpoint).

Phase 2: Supplier Response

• Suppliers are notified of a new RFQ.

• They respond through their T420 dashboard or API, submitting a structured quote including pricing tiers, SLAs, and contract terms.

Phase 3: AI Analysis & Counter-Offer Generation (The "Negotiation")

• Once all quotes are received, the T420 AI Engine activates. It does not "talk" in real-time; it performs a rapid analysis.

• A. Data Enrichment: The AI queries its own historical database for the average market price of that service in that specific zone. If data is sparse, it can perform a live Google Search to enrich its understanding.

• B. Comparative Analysis: It compares all received quotes against each other and against the calculated market average.

• C. Recommendation Engine: It generates a concise summary report for the Shepherd, presented in the AgentConsole:

  "Analysis Complete:

  • Supplier A: Quoted $95/rotation (12% above market average).

  • Supplier B: Quoted $85/rotation (at market average).

  • Supplier C: Quoted $82/rotation (4% below market average, best offer). Recommendation: Proceed with Supplier C or dispatch an automated counter-offer to Supplier A & B."

• D. Automated Counter-Offer: If the Shepherd chooses, the system sends a pre-formulated but context-aware message to the higher-priced suppliers:

  "Thank you for your quote for RFQ #1234. After reviewing market data, a rate closer to $82/rotation would be more aligned with our budget for a 50-vehicle fleet. Are you able to revise your offer?"

Phase 4: Finalization (Human-in-the-Loop)

• The Supplier can accept, reject, or revise their quote based on the AI's counter-offer.

• The Shepherd always makes the final decision. They review the final offers and click "Finalize Contract" on their chosen vendor.

• This action signs a "digital handshake" (potentially a simple smart contract) and adds the vendor to the Shepherd's "Active Supply Chain", making their rates available in the Robo-Dapp for future operational payments.

---

6. Supplier API Gateway (T420 Connect)

While payments happen in Robo-Dapp, the Integration happens here in Robo-Hub.

• Purpose: Allows Suppliers to connect their CRM/ERP to the T420 Protocol.

• Function: When a Shepherd "hires" a Supplier in Robo-Hub, the API establishes the link so that future work orders (from Robo-Dapp) flow directly into the Supplier's system.