Identity & Routing Strategy - The BIG Question

Date: 2026-01-04 Status: 🤔 Design Discussion Question: How do we route messages long-term? What is the unique ID for companies and contacts?

---

🎯 The Challenge

Current State (Demo/MVP)

• Supplier responds via magic link: /respond?requestId=REQ_123&phone=%2B27835775735

• Phone number as primary identifier

• No company concept yet

• No multi-contact support

The Questions

1. What is a Company's unique ID?

   • Is it a generated UUID?

   • Is it derived from first contact's phone?

   • Is it a company registration number?

2. What is a Contact's unique ID?

   • Phone number as root identity?

   • Email as fallback?

   • What if someone changes their number?

3. How do we route messages?

   • One company, multiple contacts (who receives what?)

   • One contact, multiple companies (freelancer working for different fleets)

   • Team structure (owner, manager, technician roles)

---

💡 Your Ideas + Strategic Analysis

Option 1: Phone-First Identity (WhatsApp Model)

Concept: Phone number IS the identity, everything else is metadata

// Core Identity
type ContactIdentity = {
  phone: string;              // PRIMARY KEY - never changes
  name?: string;              // Collected on first response
  email?: string;             // Optional backup
  created_at: timestamp;
};

// Company is a collection of contacts
type Company = {
  id: string;                 // Generated UUID
  name?: string;              // Learned from usage
  primary_contact: string;    // Phone number of owner/main contact
  team_contacts: string[];    // Array of phone numbers
  created_at: timestamp;
};

// Routing: Message goes to specific phone number
// UI shows: "Joe Smith (ABC Tires)" not "ABC Tires (Joe Smith)"

Pros:

• ✅ Matches WhatsApp mental model (contacts = people, not companies)

• ✅ Simple onboarding (one person, one phone)

• ✅ Natural team growth (add teammates later)

• ✅ Phone number portability (if Joe changes numbers, create new identity)

Cons:

• ❌ What if Joe loses his phone? (New number = new identity)

• ❌ Company structure unclear at start

• ❌ Who "owns" the company account?

Use Case:

1. Fleet sends request to Joe's number
2. Joe responds, provides name
3. System creates: ContactIdentity(phone=+27123, name="Joe Smith")
4. After 5 requests, system asks: "Are you a business? What's the name?"
5. Joe says "ABC Tires"
6. System creates: Company(id=UUID, name="ABC Tires", primary_contact="+27123")
7. Later, Joe adds teammate: "My mechanic Tom handles urgent jobs"
8. System adds Tom's number to team_contacts[]
9. ROUTING: Urgent requests → Tom's phone, Scheduled → Joe's phone

---

Option 2: Email-First Identity (SaaS Model)

Concept: Email IS the identity, phone is just a notification channel

// Core Identity
type UserIdentity = {
  email: string;              // PRIMARY KEY
  phone?: string;             // Notification channel
  name?: string;
  created_at: timestamp;
};

// Company Account
type Company = {
  id: string;                 // Generated UUID
  name: string;               // Required on signup
  owner_email: string;        // Owner's email
  team_emails: string[];      // Team members
  created_at: timestamp;
};

// Routing: Message goes to email, notification via phone/WhatsApp

Pros:

• ✅ Standard SaaS model (understood by developers)

• ✅ Email doesn't change as often as phone

• ✅ Clear company ownership (owner email)

Cons:

• ❌ More friction (need email upfront)

• ❌ Doesn't match WhatsApp model (we lose zero-signup flow)

• ❌ Many suppliers don't use email actively

---

Option 3: Hybrid - Phone for Identity, Company for Routing

Concept: Phone is root identity, company is routing layer

// Step 1: Contact Identity (created on first response)
type Contact = {
  id: string;                 // Generated UUID (stable across phone changes)
  phone: string;              // Current phone (can be updated)
  name: string;               // Collected on first response
  email?: string;             // Optional
  verified_phone: boolean;    // Did they click magic link?
  created_at: timestamp;
};

// Step 2: Company (created when needed)
type Company = {
  id: string;                 // Generated UUID
  name: string;               // Business name
  owner_contact_id: string;   // Who created/owns this
  team_contact_ids: string[]; // Team members
  categories: string[];       // Learned from request history
  created_at: timestamp;
};

// Step 3: Routing Rules (flexible)
type RoutingRule = {
  company_id: string;
  urgency: 'urgent' | 'today' | 'scheduled';
  category?: string;          // e.g., "tires", "mechanical"
  route_to_contact_id: string; // Which contact handles this
  notify_via: 'whatsapp' | 'sms' | 'email';
};

// Routing: Check rules, fall back to owner

Pros:

• ✅ Zero-signup preserved (phone is initial identity)

• ✅ Stable identity even if phone changes (update Contact.phone)

• ✅ Flexible routing (different contacts for different request types)

• ✅ Team structure emerges naturally

Cons:

• ❌ More complex database schema

• ❌ Routing logic complexity

Use Case:

1. Fleet sends to [phone]
2. Receive → Respond → "What's your name?" → "Joe Smith"
3. System creates: Contact(id=CONTACT_001, phone=+27123, name="Joe")
4. After 3 requests, system infers: "Looks like you handle tires. Business name?"
5. Joe: "ABC Tires"
6. System creates: Company(id=COMPANY_001, name="ABC Tires", owner=CONTACT_001)
7. Joe adds Tom: "My mechanic handles urgent jobs"
8. System creates: Contact(id=CONTACT_002, phone=+27999, name="Tom")
9. System adds to company.team_contact_ids
10. Joe sets routing: RoutingRule(urgent → CONTACT_002, scheduled → CONTACT_001)
11. FUTURE: If Joe changes number, update Contact(id=CONTACT_001, phone=NEW_NUMBER)

---

🔑 Recommended Approach: Hybrid (Option 3)

Phase 1: MVP (Current)

Just Contacts

• Phone number as primary identifier

• Name collected on first response

• No company concept yet

• Direct phone-to-phone messaging

-- Minimal schema for MVP
CREATE TABLE contacts (
  id UUID PRIMARY KEY,
  phone VARCHAR(20) UNIQUE NOT NULL,
  name VARCHAR(255),
  email VARCHAR(255),
  created_at TIMESTAMP
);

CREATE TABLE service_requests (
  id UUID PRIMARY KEY,
  fleet_contact_id UUID REFERENCES contacts(id),
  supplier_phone VARCHAR(20), -- Initially just phone, later links to contact
  supplier_name VARCHAR(255),  -- Captured on first response
  status VARCHAR(50),
  ...
);

Phase 2: Company Emergence (After First Beta)

Introduce Company Layer

• After X requests from same contact, prompt: "Are you a business?"

• Create company record if yes

• Link contact as owner

-- Add companies table
CREATE TABLE companies (
  id UUID PRIMARY KEY,
  name VARCHAR(255) NOT NULL,
  owner_contact_id UUID REFERENCES contacts(id),
  created_at TIMESTAMP
);

-- Link contacts to companies
CREATE TABLE company_contacts (
  company_id UUID REFERENCES companies(id),
  contact_id UUID REFERENCES contacts(id),
  role VARCHAR(50), -- 'owner', 'manager', 'technician'
  PRIMARY KEY (company_id, contact_id)
);

-- Update service_requests to reference company
ALTER TABLE service_requests
  ADD COLUMN supplier_company_id UUID REFERENCES companies(id);

Phase 3: Smart Routing (After Observing Usage)

Routing Rules

• Observe which contacts handle which types of requests

• Allow manual routing rules: "Urgent tires → Tom, Everything else → Joe"

• AI suggestions: "I notice Tom handles all urgent requests. Want to route them automatically?"

-- Routing rules
CREATE TABLE routing_rules (
  id UUID PRIMARY KEY,
  company_id UUID REFERENCES companies(id),
  urgency VARCHAR(50), -- 'urgent', 'today', 'scheduled'
  category VARCHAR(50), -- 'tires', 'mechanical', null (all)
  route_to_contact_id UUID REFERENCES contacts(id),
  notify_via VARCHAR(50) DEFAULT 'whatsapp',
  created_at TIMESTAMP
);

---

🚦 Message Routing Logic

Phase 1 (MVP): Direct Contact

// Fleet sends request to supplier
async function sendRequest(params: {
  recipientPhone: string;
  fleetName: string;
  vehicleInfo: string;
  description: string;
  urgency: 'urgent' | 'today' | 'scheduled';
}) {
  // Generate magic link
  const requestId = generateId();
  const magicLink = `https://fleetos.t420.com/respond?requestId=${requestId}&phone=${encodeURIComponent(params.recipientPhone)}`;

  // Send WhatsApp
  await NotificationService.sendWhatsApp(params.recipientPhone, `
🚗 ${params.fleetName}: ${params.urgency === 'urgent' ? '🔴 URGENT' : ''}

${params.description}

Tap to respond: ${magicLink}
  `);

  // Store request
  await db.service_requests.create({
    id: requestId,
    supplier_phone: params.recipientPhone,
    fleet_name: params.fleetName,
    ...params
  });
}

Phase 2: Company Routing

// Fleet sends to "ABC Tires" (company)
async function sendRequestToCompany(params: {
  companyId: string;
  urgency: 'urgent' | 'today' | 'scheduled';
  category?: string;
  ...
}) {
  // Find routing rule
  const rule = await db.routing_rules.findOne({
    company_id: params.companyId,
    urgency: params.urgency,
    category: params.category
  });

  // Get contact to route to
  const contactId = rule?.route_to_contact_id || company.owner_contact_id;
  const contact = await db.contacts.findOne({ id: contactId });

  // Send to that contact's phone
  await sendRequest({
    recipientPhone: contact.phone,
    ...params
  });
}

Phase 3: Multi-Contact Notification

// Notify multiple contacts (e.g., urgent request to whole team)
async function sendRequestToTeam(params: {
  companyId: string;
  urgency: 'urgent';
  ...
}) {
  const company = await db.companies.findOne({ id: params.companyId });
  const teamContacts = await db.contacts.findMany({
    id: { in: company.team_contact_ids }
  });

  // Send to all team members
  await Promise.all(
    teamContacts.map(contact =>
      sendRequest({
        recipientPhone: contact.phone,
        ...params
      })
    )
  );

  // First to respond "wins" (others get notification: "Tom already accepted this")
}

---

🤔 Open Questions for Discussion

1. Phone Number as Primary Key?

Pros: Simple, matches WhatsApp model, zero signup Cons: What if someone changes their number?

Proposed Solution:

• Phase 1: Phone is primary key

• Phase 2: UUID is primary key, phone can be updated (with verification)

2. Company Discovery?

When do we prompt: "Are you a business? What's the name?"

• After 3 requests from same contact?

• After they respond to 2 different fleets?

• Manual trigger: "Want to add your business name?"

Proposed Solution:

• Wait until they've seen value (3-5 successful requests)

• Soft prompt: "Looks like you're running a business. Want to add a business name?" [Yes] [Not now]

3. Team Member Addition?

How does Joe add Tom?

• Joe sends invite via WhatsApp?

• Joe enters Tom's number in settings?

• Tom receives request, responds, system asks: "Are you with ABC Tires?"

Proposed Solution:

• Start with option 3 (organic discovery)

• Later add option 1 (manual invite)

4. Multi-Company Freelancers?

Tom works for ABC Tires AND XYZ Mechanical

• Does Tom have one Contact record or two?

• How do we show "Tom (ABC Tires)" vs "Tom (XYZ Mechanical)" to fleets?

Proposed Solution:

• One Contact record for Tom

• Tom can be linked to multiple companies via company_contacts table

• When Tom responds, system asks: "Which business is this for? [ABC Tires] [XYZ Mechanical] [Personal]"

---

📋 Next Steps

1. Implement Phase 1 (MVP) - Just contacts, phone-based

2. Observe real usage - See how suppliers actually organize themselves

3. Design Phase 2 - Based on observed patterns, not assumptions

4. Iterate on routing - Let complexity emerge from actual needs

Key Principle: Start simple (phone + name), let structure emerge from usage.

---

🧠 Your Ideas?

This is the foundation - what are your thoughts on:

1. Phone vs Email as primary identity?

2. When to introduce company concept?

3. How routing should work for teams?

4. Multi-company contact handling?

Let's discuss and refine before building Phase 2! 🚀