Domain-Based Company Identity Architecture

Date: 2026-01-05 Critical Insight: Email domain = Company identity (no random Agent IDs needed)

🔑 Core Concept

Instead of:

Agent ID: AGENT_ABC123 (random, collision risk)

Use:

Email: zane@t420.io
Company Domain: t420.io (DNS-unique)
Result: All @t420.io users = same company

💡 Why This is Game-Changing

1. No Collision Possible

Email domains are globally unique (DNS system)
No random ID generation needed
No database collision checking needed
Zero maintenance overhead

2. KILLER Competitive Advantage Over WhatsApp

WhatsApp: Individual conversations only

Each person has separate chat
Manager can't see dispatch's conversations
No team coordination
Personal tool, not company tool

FleetOS: Company/Team visibility

T420 Fleet Company (@t420.io):
├── Zane (Fleet Operator) - submits requests
├── Sarah (Dispatch) - triages urgent requests
└── Mike (Fleet Manager) - reviews all company activity

All see company dashboard
All see company requests
Roles determine permissions

WhatsApp CANNOT do this!

3. Natural Organizational Structure

Suppliers (Multi-tech shops):

ABC Tires (@abctires.com):
├── Office Receptionist - sees incoming requests
├── Mobile Tech #1 - assigned requests
├── Mobile Tech #2 - assigned requests
└── Shop Owner - oversight/audit

Fleets (Dispatch operations):

T420 Logistics (@t420.io):
├── Night Dispatch - handles 6 AM emergencies
├── Day Dispatch - handles scheduled work
├── Fleet Manager - reviews quotes, approvals
└── CFO - exports audit trail for compliance

🏗️ Database Schema

Current Issues to Check:

❓ Does companies table exist?
❓ Does user_profiles have company_name field?
❓ Do we need to create companies table?

Proposed Schema:

-- Companies table (domain-based)
CREATE TABLE companies (
  company_id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  domain TEXT UNIQUE NOT NULL, -- extracted from email (e.g., "t420.io")
  company_name TEXT NOT NULL,   -- user-provided (e.g., "T420 Logistics")
  company_type TEXT CHECK (company_type IN ('fleet', 'supplier', 'mixed')),
  created_at TIMESTAMP DEFAULT NOW(),
  settings JSONB DEFAULT '{}'
);

-- User profiles linked to companies
CREATE TABLE user_profiles (
  profile_id UUID PRIMARY KEY,
  user_id UUID REFERENCES users(user_id),
  company_id UUID REFERENCES companies(company_id), -- NEW
  email TEXT NOT NULL,
  role TEXT CHECK (role IN ('fleet_operator', 'dispatch', 'manager', 'tech', 'owner')),
  permissions JSONB DEFAULT '{}', -- role-based permissions
  created_at TIMESTAMP DEFAULT NOW()
);

-- Service requests linked to companies (not individuals)
CREATE TABLE service_requests (
  request_id UUID PRIMARY KEY,
  fleet_company_id UUID REFERENCES companies(company_id), -- who requested
  supplier_company_id UUID REFERENCES companies(company_id), -- who responds
  submitted_by_user_id UUID REFERENCES users(user_id), -- which team member submitted
  assigned_to_user_id UUID REFERENCES users(user_id), -- which tech assigned
  vehicle_identifier TEXT,
  location TEXT,
  urgency TEXT CHECK (urgency IN ('URGENT', 'TODAY', 'SCHEDULED')),
  status TEXT CHECK (status IN (
    'pending',
    'assigned',     -- NEW STATUS
    'acknowledged',
    'accepted',
    'in_progress',
    'completed',
    'declined'
  )),
  description TEXT,
  created_at TIMESTAMP DEFAULT NOW(),
  assigned_at TIMESTAMP,
  acknowledged_at TIMESTAMP,
  accepted_at TIMESTAMP,
  completed_at TIMESTAMP
);

📊 Status Options (Functional Design)

Current Statuses:

pending - Request submitted, waiting for supplier
acknowledged - Supplier saw it ("Got it")
accepted - Supplier will do it
in_progress - Tech is working on it
completed - Job done
declined - Supplier can't do it

NEW Status: `assigned`

Why Needed:

Multi-tech supplier workflow:
1. Request comes in → pending
2. Dispatch assigns to Tech #2 → assigned
3. Tech #2 sees assignment → acknowledged
4. Tech #2 starts work → in_progress
5. Tech #2 finishes → completed

Without "assigned" status:

Can't track who's responsible
Can't distinguish "waiting for dispatch" vs "waiting for tech"
No accountability

👁️ Visibility Matrix (Who Sees What)

Service Request Visibility:

User Role

What They See

Actions

Fleet Operator (submitter)

Own requests only

Create, cancel

Fleet Dispatch

ALL company requests

Create, assign priority

Fleet Manager

ALL company requests

View, export audit

Supplier Tech

Assigned to me

Acknowledge, update status

Supplier Dispatch

ALL company requests

Assign to techs, respond

Supplier Owner

ALL company requests

View, analytics, audit

Example Scenarios:

Scenario 1: Fleet Side

3:00 AM - Emergency flat tire
↓
Night Dispatch (Sarah@t420.io) submits request
↓
6:00 AM - Day Dispatch (John@t420.io) sees same request
↓
Fleet Manager (Mike@t420.io) reviews response time
↓
All see the same company dashboard

Scenario 2: Supplier Side

Request arrives at ABC Tires
↓
Receptionist (office@abctires.com) sees request → Status: pending
↓
Dispatch assigns to Tech #2 → Status: assigned
↓
Tech #2 (tech2@abctires.com) sees "Assigned to me" → acknowledges
↓
Owner (owner@abctires.com) reviews completion time
↓
All see company TODO list, filtered by role

🎨 Status Flow & Color Coding (Focus on Function First)

Complete Status Flow:

pending → assigned → acknowledged → accepted → in_progress → completed
   ↓
declined (any stage)

Status Definitions:

Status

Who Sets

Meaning

Visible To

pending

System (on submit)

Waiting for supplier dispatch

Fleet & Supplier company

assigned

Supplier dispatch

Assigned to specific tech

Supplier company, Fleet sees "processing"

acknowledged

Assigned tech

"I got it, on my way"

Everyone

accepted

Tech or dispatch

"I will do this job"

Everyone

in_progress

Assigned tech

"Working on it now"

Everyone

completed

Assigned tech

"Job done"

Everyone

declined

Supplier dispatch/tech

"Can't do it" + reason

Everyone

Color Coding (Future - Function First):

User mentioned: "maybe not need to xmas tress colors we deal with that later"

For now: Focus on STATUS FUNCTIONALITY
Later: Design color system that makes sense

🔐 Permission System

Role-Based Permissions:

Fleet Operator:

✅ Submit requests
✅ View own requests
❌ View other team members' requests
❌ Export company audit

Fleet Dispatch:

✅ Submit requests
✅ View ALL company requests
✅ Mark as priority
❌ Export audit (manager only)

Fleet Manager:

✅ View ALL company requests
✅ Export audit trail
✅ Review analytics
❌ Submit requests (not their job)

Supplier Tech:

✅ View assigned requests
✅ Update status (acknowledge, in_progress, complete)
❌ View other techs' requests
❌ Assign work

Supplier Dispatch:

✅ View ALL company requests
✅ Assign to techs
✅ Acknowledge/decline
✅ Respond with quotes

Supplier Owner:

✅ View ALL company requests
✅ View analytics
✅ Export audit
❌ Update individual requests (oversight only)

🚀 Implementation Checklist

Phase 1: Database Setup

Check if companies table exists in Supabase
If not: Create companies table
Add company_id to user_profiles
Add company_id to service_requests
Add assigned_to_user_id to service_requests
Add "assigned" to status enum

Phase 2: Domain Extraction Logic

Extract domain from email on signup
Check if company exists (by domain)
If new: Create company
If exists: Link user to existing company
Store in user_profiles.company_id

Phase 3: Visibility Rules

Add role-based filtering to SupplierTodoList
Add "assigned to me" filter for techs
Add "all company" view for dispatch/managers
Add assignment action for dispatch

Phase 4: Status Flow

Add "assigned" status option
Add "assign to tech" dropdown (dispatch only)
Update status transition logic
Add timestamps (assigned_at, etc.)

🎯 Immediate Next Steps

User said: "I tihnk there are company table you have access via supabase let me know if you have issue"

ACTION: Check Supabase database directly for:

Does companies table exist?
Does user_profiles have company_id or company_name?
Does service_requests have company linking?

Once confirmed, implement:

Domain extraction on signup
Company creation/linking
Add "assigned" status
Role-based visibility

💰 Business Impact

Why This Matters:

Messaging:

"WhatsApp is for individuals. FleetOS is for companies."

Value Props:

For Fleet Managers:

See ALL fleet activity (not just own requests)
Export company audit trail
Track dispatcher performance
Compliance in one click

For Supplier Owners:

See ALL tech activity
Assign work efficiently
Track completion rates
Identify bottlenecks

Competitive Edge:

❌ WhatsApp: Personal tool, no team features
✅ FleetOS: Company tool, built for teams

Status: Architecture defined, awaiting database schema confirmation Next: Check Supabase for companies table, then implement

PreviousDocumentation Cleanup Plan NextHow to View Your Scraped Data in the UI

Last updated 8 days ago

Was this helpful?

hashtag🔑 Core Concept

hashtag💡 Why This is Game-Changing

hashtag1. No Collision Possible

hashtag2. KILLER Competitive Advantage Over WhatsApp

hashtag3. Natural Organizational Structure

hashtag🏗️ Database Schema

hashtagCurrent Issues to Check:

hashtagProposed Schema:

hashtag📊 Status Options (Functional Design)

hashtagCurrent Statuses:

hashtagNEW Status: assigned

hashtag👁️ Visibility Matrix (Who Sees What)

hashtagService Request Visibility:

hashtagExample Scenarios:

hashtag🎨 Status Flow & Color Coding (Focus on Function First)

hashtagComplete Status Flow:

hashtagStatus Definitions:

hashtagColor Coding (Future - Function First):

hashtag🔐 Permission System

hashtagRole-Based Permissions:

hashtag🚀 Implementation Checklist

hashtagPhase 1: Database Setup

hashtagPhase 2: Domain Extraction Logic

hashtagPhase 3: Visibility Rules

hashtagPhase 4: Status Flow

hashtag🎯 Immediate Next Steps

hashtag💰 Business Impact

🔑 Core Concept

💡 Why This is Game-Changing

1. No Collision Possible

2. KILLER Competitive Advantage Over WhatsApp

3. Natural Organizational Structure

🏗️ Database Schema

Current Issues to Check:

Proposed Schema:

📊 Status Options (Functional Design)

Current Statuses:

NEW Status: `assigned`

👁️ Visibility Matrix (Who Sees What)

Service Request Visibility:

Example Scenarios:

🎨 Status Flow & Color Coding (Focus on Function First)

Complete Status Flow:

Status Definitions:

Color Coding (Future - Function First):

🔐 Permission System

Role-Based Permissions:

🚀 Implementation Checklist

Phase 1: Database Setup

Phase 2: Domain Extraction Logic

Phase 3: Visibility Rules

Phase 4: Status Flow

🎯 Immediate Next Steps

💰 Business Impact