Carts & Listings

Relevant source files

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

• packages/db/src/schema/carts.ts
• packages/db/src/seed.ts
• packages/db/drizzle/meta/0000_snapshot.json
• packages/db/drizzle/0000_normal_the_order.sql
• apps/api/package.json

The Carts & Listings module forms the core commercial infrastructure of the Subito platform. It manages the lifecycle of service offerings—from hierarchical category organization and detailed service listings to the staging area (Cart) where users configure their bookings. This system handles complex pricing logic, including base prices, catalog-specific variants, bundles, and dynamic adjustments like surge pricing and discounts.

The module facilitates a transition from browsing static service data to creating actionable intent through the carts and cart_items entities. These entities capture user preferences such as booking type (Instant, Scheduled, or Recurring), specific time slots, and associated promotional codes before they are finalized into a booking.

Sources: packages/db/src/schema/carts.ts:1-10, packages/db/src/seed.ts:184-330

Service Architecture & Cataloging

The service discovery layer is structured into a multi-tier hierarchy: Categories, Listings, and Catalogs. This allows for granular control over how services are presented and priced based on specific units or conditions.

Hierarchical Structure

• Categories: Broad groups (e.g., "Home Cleaning") that can have sub-categories (e.g., "Bathroom Cleaning") to organize the service marketplace.
• Listings: Specific service definitions under a category (e.g., "Regular Home Cleaning"). These define the base characteristics like tags and default duration.
• Catalogs: Concrete pricing variants for a listing (e.g., "1 BHK", "2 BHK"). They define the actual unit of measure and quantity constraints.
• Catalog Pricing: Allows for dependent pricing logic based on variables like the number of rooms (BHK) or specific area values.

Sources: packages/db/src/seed.ts:184-280, packages/db/drizzle/meta/0000_snapshot.json:1150-1350

Cart Management

The Cart system acts as a persistent staging area for users to configure their service requirements. Unlike simple e-commerce carts, a Subito cart integrates operational metadata such as address references and specific scheduling types.

Data Model: Carts & Cart Items

The carts table tracks the high-level configuration of a potential booking, including financial totals and promotional applications. cart_items links specific catalogs to the cart, allowing for customization via a property_config JSON field.

Field	Type	Description
booking_type	ENUM	Determines if the service is INSTANT, SCHEDULED, or RECURRING.
time_slot	JSONB	Stores user-selected scheduling data.
version	Integer	Used for optimistic concurrency control during updates.
is_active	Boolean	Flags if the cart is currently editable by the user.
property_config	JSONB	(Cart Item) Specific configuration for a service (e.g., room sizes).

Sources: packages/db/src/schema/carts.ts:25-78, packages/db/drizzle/0000_normal_the_order.sql:350-400

Pricing & Adjustments

The system performs complex financial calculations within the cart schema to ensure transparency before the user commits to a booking.

Calculation Logic

The cart tracks multiple price points to provide a detailed breakdown:

1. Total Price: The raw sum of all cart_items (quantity * unit_price).
2. Discount Amount: Reductions derived from coupon_id or bundle_id.
3. Surge Price: Dynamic price increases applied based on surge_applicable flags, often determined by hub-level demand.
4. GST Amount: Tax calculated on the price after adjustments.
5. Final Amount: The actual value to be charged to the user.

Sources: packages/db/src/schema/carts.ts:44-64, packages/db/src/seed.ts:130-150

Bundles and Promotions

Bundles allow multiple catalog items to be sold as a single package at a bundle_price. This is implemented via the bundles and bundle_items tables, which link back to the catalog. Coupons can be applied to carts to provide PERCENTAGE or FLAT discounts, subject to min_cart_value and usage limits.

Sources: packages/db/drizzle/meta/0000_snapshot.json:1000-1100, packages/db/src/seed.ts:310-350

Implementation Details

The implementation utilizes Drizzle ORM for schema definition and PostgreSQL for persistence. Enums are heavily used to enforce valid booking and recurring types.

// Example of the Booking Type Enum used across Carts and Bookings
export const bookingTypeEnum = pgEnum("booking_type", [
  "INSTANT",
  "SCHEDULED",
  "RECURRING",
])

// Cart Item schema showing the relationship to catalogs
export const cartItems = pgTable("cart_items", {
  id: uuid("id").primaryKey().defaultRandom(),
  cartId: uuid("cart_id").notNull().references(() => carts.id, { onDelete: "cascade" }),
  catalogId: uuid("catalog_id").notNull().references(() => catalogs.id, { onDelete: "cascade" }),
  unitPrice: decimal("unit_price", { precision: 10, scale: 2 }).notNull(),
  totalPrice: decimal("total_price", { precision: 12, scale: 2 }).notNull(),
})

Sources: packages/db/src/schema/carts.ts:12-23, 67-82, packages/db/drizzle/0000_normal_the_order.sql:8-10

Summary

The Carts & Listings module provides a robust foundation for the Subito marketplace. By decoupling service definitions (Listings) from their pricing and unit logic (Catalogs), the system maintains high flexibility. The Cart sub-system effectively bridges the gap between the static service catalog and the dynamic booking process, capturing essential financial and operational configurations required for a successful service match.