Partners & Hubs

Relevant source files

The following files were used as context for generating this wiki page:

• packages/db/src/schema/partners.ts
• packages/db/src/schema/hubs.ts
• packages/db/src/seed.ts
• packages/db/drizzle/0000_normal_the_order.sql
• packages/shared/src/utils/index.ts

The Partners & Hubs system forms the operational backbone of the Subito platform, managing the geographical organization of services and the professional workforce that delivers them. Hubs and MicroHubs define the serviceable boundaries and operational parameters for specific regions, while the Partner module handles the lifecycle, availability, and performance tracking of service providers.

This system ensures that service requests are matched with qualified partners within a defined radius, utilizing a multi-tiered geographical hierarchy (City Hub -> MicroHub -> Pincodes) to optimize logistics and service availability.

Hub Architecture & Geography

The project utilizes a hierarchical structure to manage service areas. A "Hub" typically represents a city or a large metropolitan region, while "MicroHubs" represent specific neighborhoods or clusters of pincodes within that city.

Geographical Hierarchy

1. Hubs: The top-level entity representing a major area (e.g., Hyderabad Central). It contains global coordinates and a broad service radius.
2. MicroHubs: Child entities of Hubs that specify local areas (e.g., Banjara Hills) and are linked to specific sets of pincodes.
3. Hub Configs: Detailed operational settings that can be applied at either the Hub or MicroHub level, defining service hours and booking constraints.

The following diagram illustrates the relationship between these entities:

Operational Parameters

Operational windows and capacity are managed through hub_configs. This table stores critical metadata for scheduling:

Field	Type	Description
day_start_time	varchar	The earliest time a service can start (Default: 06:00).
day_closing_time	varchar	The latest time a service can end (Default: 21:00).
slot_duration	integer	Length of a booking slot in minutes (Default: 60).
buffer_time	integer	Gap between slots for travel/rest (Default: 30).
max_bookings_per_slot	integer	Capacity limit for a specific time window.
surge_multiplier	double	Dynamic pricing factor for high-demand periods.

Sources: packages/db/src/schema/hubs.ts:46-72, packages/db/src/seed.ts:219-250

Partner Management

Partners are specialized users assigned the partner role. Their profile includes professional credentials, financial information, and real-time status tracking.

Partner Lifecycle and Status

A partner's ability to receive bookings is governed by two distinct status fields:

• Status (partner_status): Administrative state including pending, approved, rejected, or suspended.
• Availability Status (partner_availability_status): Operational state including online, offline, or busy.

Sources: packages/db/src/schema/partners.ts:16-30, packages/db/drizzle/0000_normal_the_order.sql:2-5

Data Structure: Partner Profile

The partners table stores the core profile data, extending the base users record.

export const partners = pgTable("partners", {
  id: uuid("id").primaryKey().defaultRandom(),
  userId: uuid("user_id").notNull().references(() => users.id),
  status: partnerStatusEnum("status").default("pending"),
  availabilityStatus: partnerAvailabilityStatusEnum("availability_status").default("offline"),
  averageRating: decimal("average_rating", { precision: 3, scale: 2 }),
  serviceRadius: integer("service_radius").default(10),
  totalEarnings: decimal("total_earnings", { precision: 12, scale: 2 }),
  // ... financial fields (bankAccountNumber, aadharNumber, etc)
})

Sources: packages/db/src/schema/partners.ts:32-58, packages/db/drizzle/0000_normal_the_order.sql:84-106

Tracking and Logistics

The system tracks partners through several auxiliary tables to ensure reliable matching:

• partner_locations: Captures real-time GPS coordinates, heading, and speed. Indexed by partner_id and recorded_at for history.
• partner_availability: Stores weekly schedules (day of week, start/end times).
• partner_services: Links partners to the specific categories of work they are qualified to perform.

Sources: packages/db/src/schema/partners.ts:69-101, packages/db/drizzle/0000_normal_the_order.sql:57-75

Matching and Performance

The platform uses a scoring algorithm to match customers with the most suitable partner based on distance, historical performance, and availability.

Match Scoring Logic

The score is calculated using the following weights:

1. Rating: (Average Rating * 2).
2. Experience: (Completed Bookings / 10), capped at 3 points.
3. Distance: (10km - Actual Distance) * 0.5 points.

export function calculatePartnerMatchScore(input: {
  averageRating: string | null
  completedBookings: number | null
  distanceKm: number
}): number {
  const rating = input.averageRating ? parseFloat(input.averageRating) : 3
  const completed = input.completedBookings || 0
  const distanceScore = Math.max(0, 10 - input.distanceKm)
  return rating * 2 + Math.min(completed / 10, 3) + distanceScore * 0.5
}

Sources: packages/shared/src/utils/index.ts:36-47

Service Flow Diagram

This diagram describes the interaction between Hubs, MicroHubs, and Partners during the lifecycle of a service.

Financial Operations

Financial tracking for partners includes earnings accumulation and periodic payouts.

Table	Purpose	Key Fields
partners	Earnings aggregation	total_earnings
partner_payouts	Transaction history	amount, status, transaction_id, processed_at

Sources: packages/db/src/schema/partners.ts:51, 110-118, packages/db/drizzle/0000_normal_the_order.sql:76-83

Conclusion

The Partners & Hubs module provides a structured framework for managing distributed operations. By combining granular geographical boundaries (Hubs/MicroHubs) with detailed partner profiles and real-time tracking, the system ensures that service delivery is both efficient and scalable. The use of performance-based matching scores further ensures quality control by incentivizing high ratings and experience among the partner workforce.