Home
Relevant source files
The following files were used as context for generating this wiki page:
Subito is a monorepo-based platform designed for managing home services through a sophisticated service booking and partner matching engine. The project utilizes a modern TypeScript stack, orchestrating multiple applications and shared packages to handle user management, location-based service hubs, complex booking lifecycles, and financial transactions.
The system is architected as a monorepo managed by Turbo, separating concerns into specialized apps for APIs and dashboards, supported by shared packages for database schemas, UI components, and utility logic.
Sources: package.json:1-35, turbo.json:1-55, README.md:1-21
Core Architecture
The Subito project follows a monorepo structure using pnpm workspaces. This architecture ensures type safety across the entire stack and allows for efficient code sharing between the frontend and backend.
Project Structure
- apps/: Contains the main executable applications.
api: A Hono-based backend server.dashboard: A Next.js project for administrative and user management.
- packages/: Contains shared logic and configurations.
db: Drizzle ORM schemas and migration scripts for PostgreSQL.ui: Shared Shadcn/UI components.shared: Common TypeScript types, constants, and utility functions.utils: Specialized utilities like JWT access management.eslint-config/typescript-config: Shared development configurations.
Sources: package.json:18-30, apps/api/package.json:1-40, packages/ui/package.json:1-45, packages/db/package.json:1-35
Dependency Graph
The following diagram illustrates the internal relationships and dependencies between the various modules within the Subito monorepo:
Database Schema & Data Model
The data layer is built on PostgreSQL, utilizing Drizzle ORM to manage complex relationships between users, service hubs, and financial entities.
Entity Relationship Overview
The system manages three primary user roles: customer, partner, and admin. Service delivery is organized geographically through hubs and micro_hubs.
Core Tables
| Table | Description | Key Fields |
|---|---|---|
users | Core user identity and roles | firebase_uid, phone, role, is_onboarded |
partners | Extended profile for service providers | status, availability_status, average_rating, total_earnings |
hubs | Regional service centers | code, city, latitude, longitude, radius |
bookings | Service request lifecycle | booking_number, status, booking_type, total_amount |
orders | Financial transaction records | order_id, status, amount, payment_method |
Sources: packages/db/drizzle/0000_normal_the_order.sql:43-300
Service Matching & Logic
A critical component of Subito is the logic used to match customers with service providers. This is handled through a scoring mechanism based on distance, ratings, and historical performance.
Partner Match Scoring
The system calculates a PartnerMatchScore where a higher score indicates a better match. The formula weights different attributes as follows:
- Rating Weight: Average rating multiplied by 2.
- Experience Weight: Completed bookings (capped at 30, divided by 10).
- Distance Weight: Haversine distance from the service location, capped at 10km (inverse relationship).
Sources: packages/shared/src/utils/index.ts:40-50
Booking Lifecycle
Bookings transition through several states defined by the booking_status enum:
PENDING_PAYMENT: Initial state after creation.PENDING_MATCH: Awaiting an available partner.MATCHED: Partner assigned to the service.ARRIVING/STARTED: Service in progress.COMPLETED: Service finalized.
Sources: packages/db/drizzle/0000_normal_the_order.sql:12, packages/db/src/seed.ts:748-780
Development Workflow
The project uses Turbo to manage tasks across the monorepo, ensuring that builds, linting, and database operations are executed efficiently.
Primary Commands
| Task | Command | Description |
|---|---|---|
dev | turbo dev | Starts all applications in watch mode |
build | turbo build | Compiles all apps and packages |
db:generate | turbo db:generate | Generates Drizzle migrations |
db:seed | pnpm --filter @subito/db db:seed | Populates the database with test data |
Sources: package.json:6-14, turbo.json:21-50, packages/db/package.json:10-14
Environment Configuration
The monorepo requires a set of global environment variables for database connectivity (DATABASE_URL), caching (REDIS_URL), and security (JWT_SECRET, FIREBASE_SERVICE_ACCOUNT).
Sources: turbo.json:4-19
Summary
The Subito project provides a robust, type-safe foundation for a location-aware service marketplace. By leveraging a monorepo architecture, it centralizes complex business logic—such as partner matching scores and booking state machines—while allowing independent scaling of its API and dashboard interfaces. The integration of Drizzle ORM and PostgreSQL ensures a strongly-typed data layer capable of handling the intricacies of recurring bookings, regional hub configurations, and financial processing.