Architecture Overview
Relevant source files
The following files were used as context for generating this wiki page:
The Subito project is a TypeScript-based monorepo designed for a service-booking marketplace, likely focused on home cleaning services. It leverages a modern stack including a Hono-based API, a Next.js dashboard, and a shared PostgreSQL database managed with Drizzle ORM. The architecture is structured to support multi-role users (customers, partners, and admins), complex booking types (instant, scheduled, and recurring), and location-based service management through hubs and micro-hubs.
Sources: package.json, apps/api/src/app.ts:1-125, packages/db/drizzle/0000_normal_the_order.sql:1-40
Monorepo Structure
The project utilizes Turborepo to manage a collection of applications and shared packages. This structure ensures code reusability across the backend and frontend while maintaining clear boundaries between different domains.
Core Workspaces
| Workspace | Description | Key Technologies |
|---|---|---|
apps/api | Backend REST API serving mobile and web clients. | Hono, Zod, BullMQ, Firebase Admin |
apps/dashboard | Internal management interface. | Next.js, React, Shadcn/UI |
packages/db | Database schema definitions, migrations, and seeding. | Drizzle ORM, PostgreSQL |
packages/ui | Shared component library. | Tailwind CSS, Shadcn/UI, Lucide |
packages/shared | Common TypeScript types, constants, and utilities. | TypeScript |
Sources: package.json:20-22, apps/api/package.json:30-45, apps/dashboard/package.json:15-22, packages/db/package.json:23-28
The dependency flow between workspaces is managed via pnpm workspaces:
API Architecture
The API is built using the Hono framework, providing a lightweight and high-performance routing layer. It incorporates a middleware-heavy architecture for request tracing, security, and authentication.
Request Pipeline
Requests passing through the API undergo several transformations and checks:
- Tracing: Assignment of a unique
requestIdand performance timing. - Security: Enforcement of secure headers and CORS policies.
- Logging: Detailed logging of request methods, paths, and client headers (e.g.,
X-Platform,X-App-Version). - Routing: Versioned routing under
/v1, with specialized modules likeauthRouter.
Sources: apps/api/src/app.ts:40-100
Data Model and Schema
The system uses a relational PostgreSQL database with a highly normalized schema to handle the complexities of service marketplaces.
User and Role Management
The system defines three primary roles: customer, partner, and admin. Users are authenticated via Firebase (linked via firebase_uid).
- Partners: Have additional profiles containing professional details (Aadhar, PAN), ratings, and availability status (
online,offline,busy). - Addresses: Supports multiple address types (
HOME,OFFICE) with metadata for home cleaning (BHK, bathroom count, floor).
Sources: packages/db/drizzle/0000_normal_the_order.sql:1-5, packages/db/drizzle/0000_normal_the_order.sql:53-150
Service Organization
Service availability is managed through a hierarchical location model:
- Hubs: Represent major cities or regions (e.g., Hyderabad Central Hub).
- Micro-Hubs: Specific areas within a hub (e.g., Banjara Hills) associated with specific pincodes.
- Hub Configs: Define operational parameters like
day_start_time,slot_duration, andsurge_multiplierper micro-hub.
Booking and Payment Flow
The system supports complex lifecycle states for bookings and orders.
| Entity | Key States / Types |
|---|---|
| Booking Status | PENDING_PAYMENT, PENDING_MATCH, MATCHED, ARRIVING, STARTED, COMPLETED, CANCELLED |
| Booking Type | INSTANT, SCHEDULED, RECURRING |
| Order Status | CREATED, AUTHORIZED, CAPTURED, COMPLETED, FAILED |
| Payment Method | UPI, CARD, NETBANKING, WALLET, COD |
Sources: packages/db/drizzle/0000_normal_the_order.sql:10-25
Build and Deployment Configuration
The project uses turbo.json to define task dependencies and environment requirements.
Task Pipeline
The build pipeline is optimized to respect dependency order (e.g., building shared packages before apps).
{
"tasks": {
"build": {
"dependsOn": ["^build"],
"outputs": [".next/**", "dist/**"]
},
"db:migrate": { "cache": false }
}
}
Environment Variables
The system relies on critical global environment variables for operation, including DATABASE_URL, REDIS_URL, FIREBASE_SERVICE_ACCOUNT, and JUSPAY related credentials (implied by schema fields).
Sources: turbo.json:5-25, packages/db/drizzle/0000_normal_the_order.sql:515-530
Conclusion
The Subito architecture is a robust, type-safe monorepo tailored for high-reliability service delivery. By combining the speed of Hono with the structural integrity of Drizzle ORM and a centralized location/config hub model, the system provides a scalable foundation for managing users, partners, and complex service schedules.