# tafseelkhan/tizzygo-os architecture

> Architecture diagram of the GitHub repository tafseelkhan/tizzygo-os, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/tafseelkhan/tizzygo-os
- Repository: https://github.com/tafseelkhan/tizzygo-os

## Overview

The repository implements two related API products: TizzyGo commerce and TizzyOS marketplace/operations, including ride-hailing and shipping workflows. Requests enter through the separate application surfaces and expose domain routes; sampled routes show ride quoting and booking, while checkout/webhook code handles payment confirmation and order/cart state. TizzyOS also covers seller products, payout setup, riders, and fulfillment tracking. The map includes central runtime models, payment selection, and cleanup. Several route and controller internals were not sampled, so their connections are limited to explicitly shown mounts or references.

Main entry points: [`src/tizzyos/app.ts`](https://github.com/tafseelkhan/tizzygo-os/blob/main/src/tizzyos/app.ts) (TizzyOS API), [`src/controller/tizzygo/buynow/webhookController.ts`](https://github.com/tafseelkhan/tizzygo-os/blob/main/src/controller/tizzygo/buynow/webhookController.ts) (Checkout and webhook), [`src/services/tizzyos/shippings/trackingServices.ts`](https://github.com/tafseelkhan/tizzygo-os/blob/main/src/services/tizzyos/shippings/trackingServices.ts) (Shipping tracking), [`src/tizzygo/app.ts`](https://github.com/tafseelkhan/tizzygo-os/blob/main/src/tizzygo/app.ts) (TizzyGo API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API surfaces"]
  node_tizzygo_api["TizzyGo API<br/>[app.ts]"]
  node_tizzyos_api["TizzyOS API<br/>[app.ts]"]
end

subgraph group_commerce["Commerce"]
  node_commerce_routes["Commerce routes"]
  node_auth["Authentication<br/>[authMiddleware.ts]"]
  node_checkout["Checkout and webhook"]
  node_payment_service["Payment service<br/>[paymentService.ts]"]
  node_gateway_factory["Gateway selection"]
  node_gateway["Razorpay gateway<br/>[RazorpayGateway.ts]"]
  node_cart_store[("Cart data<br/>[Cart.ts]")]
  node_checkout_store[("Checkout and orders<br/>[order.ts]")]
  node_transaction_store[("Transactions<br/>[Transaction.ts]")]
  node_event_store[("Webhook events<br/>[WebhookEvent.ts]")]
end

subgraph group_mobility["Ride-hailing"]
  node_ride_routes["Ride booking routes"]
  node_ride_quote["Ride quotes"]
  node_ride_booking["Ride booking"]
  node_ride_dispatch["Driver dispatch"]
end

subgraph group_fulfillment["Seller and shipping"]
  node_seller_routes["Seller operations"]
  node_product_catalog[("Product catalog<br/>[Products.ts]")]
  node_shipping_routes["Shipping routes"]
  node_shipping_tracking["Shipping tracking"]
  node_rider_registry[("FWS rider records<br/>[fwsRegistration.ts]")]
  node_rider_locations[("Rider locations")]
  node_delivery_tracking[("Delivery tracking")]
end

subgraph group_runtime["Shared runtime"]
  node_media_cleanup["Media cleanup"]
  node_cleanup_scheduler["Checkout cleanup"]
  node_media_records[("Upload tracking")]
  node_seller_logger["Seller logger<br/>[logger.ts]"]
end

node_consumer(("Client apps"))

node_consumer -->|"sends requests"| node_tizzygo_api
node_consumer -->|"sends requests"| node_tizzyos_api
node_tizzygo_api -->|"mounts routes"| node_commerce_routes
node_tizzyos_api -.->|"mounts routes"| node_ride_routes
node_tizzyos_api -->|"mounts routes"| node_seller_routes
node_tizzyos_api -->|"mounts routes"| node_shipping_routes
node_commerce_routes -->|"guards requests"| node_auth
node_commerce_routes -.->|"routes webhook"| node_checkout
node_checkout -->|"selects gateway"| node_gateway_factory
node_gateway_factory -->|"registers gateway"| node_gateway
node_checkout -->|"deduplicates events"| node_event_store
node_checkout -->|"clears cart"| node_cart_store
node_checkout -->|"reads and updates"| node_checkout_store
node_payment_service -->|"reads and writes"| node_checkout_store
node_payment_service -->|"reads and writes"| node_cart_store
node_payment_service -->|"reads and writes"| node_transaction_store
node_ride_routes -->|"guards booking"| node_auth
node_ride_routes -.->|"requests quotes"| node_ride_quote
node_ride_routes -.->|"creates bookings"| node_ride_booking
node_ride_booking -.->|"dispatches drivers"| node_ride_dispatch
node_seller_routes -.->|"manages products"| node_product_catalog
node_shipping_routes -.->|"routes tracking"| node_shipping_tracking
node_shipping_tracking -->|"reads orders"| node_checkout_store
node_shipping_tracking -->|"reads and writes"| node_rider_registry
node_shipping_tracking -->|"reads and writes"| node_rider_locations
node_shipping_tracking -->|"reads and writes"| node_delivery_tracking
node_media_cleanup -.->|"cleans records"| node_media_records
node_cleanup_scheduler -->|"cleans abandoned orders"| node_checkout_store
node_cleanup_scheduler -->|"cleans transactions"| node_transaction_store
node_tizzygo_api -->|"invokes cleanup"| node_media_cleanup
node_tizzygo_api -->|"starts scheduler"| node_cleanup_scheduler
node_tizzyos_api -->|"invokes cleanup"| node_media_cleanup
node_tizzyos_api -->|"starts scheduler"| node_cleanup_scheduler

click node_tizzygo_api "https://github.com/tafseelkhan/tizzygo-os/blob/main/src/tizzygo/app.ts"
click node_tizzyos_api "https://github.com/tafseelkhan/tizzygo-os/blob/main/src/tizzyos/app.ts"
click node_commerce_routes "https://github.com/tafseelkhan/tizzygo-os/tree/main/src/routes/tizzygo"
click node_auth "https://github.com/tafseelkhan/tizzygo-os/blob/main/src/middleware/tizzygo/authMiddleware.ts"
click node_checkout "https://github.com/tafseelkhan/tizzygo-os/blob/main/src/controller/tizzygo/buynow/webhookController.ts"
click node_payment_service "https://github.com/tafseelkhan/tizzygo-os/blob/main/src/services/tizzygo/paymentService.ts"
click node_gateway_factory "https://github.com/tafseelkhan/tizzygo-os/blob/main/src/factories/PaymentGatewayFactory.ts"
click node_gateway "https://github.com/tafseelkhan/tizzygo-os/blob/main/src/gateways/RazorpayGateway.ts"
click node_cart_store "https://github.com/tafseelkhan/tizzygo-os/blob/main/src/models/tizzygo/cart/Cart.ts"
click node_checkout_store "https://github.com/tafseelkhan/tizzygo-os/blob/main/src/models/tizzygo/checkout/order.ts"
click node_transaction_store "https://github.com/tafseelkhan/tizzygo-os/blob/main/src/models/tizzygo/checkout/Transaction.ts"
click node_event_store "https://github.com/tafseelkhan/tizzygo-os/blob/main/src/models/tizzygo/checkout/WebhookEvent.ts"
click node_ride_routes "https://github.com/tafseelkhan/tizzygo-os/blob/main/src/routes/tizzyos/cab/rideBookingRoutes.ts"
click node_ride_quote "https://github.com/tafseelkhan/tizzygo-os/blob/main/src/services/tizzyos/cab/rideQuoteService.ts"
click node_ride_booking "https://github.com/tafseelkhan/tizzygo-os/blob/main/src/services/tizzyos/cab/rideBookingService.ts"
click node_ride_dispatch "https://github.com/tafseelkhan/tizzygo-os/blob/main/src/services/tizzyos/cab/rideDispatchService.ts"
click node_seller_routes "https://github.com/tafseelkhan/tizzygo-os/tree/main/src/routes/tizzyos/seller"
click node_product_catalog "https://github.com/tafseelkhan/tizzygo-os/blob/main/src/models/tizzyos/seller/AddProducts/Products.ts"
click node_shipping_routes "https://github.com/tafseelkhan/tizzygo-os/tree/main/src/routes/tizzyos/shipping"
click node_shipping_tracking "https://github.com/tafseelkhan/tizzygo-os/blob/main/src/services/tizzyos/shippings/trackingServices.ts"
click node_rider_registry "https://github.com/tafseelkhan/tizzygo-os/blob/main/src/models/tizzyos/shipping/fws/fwsRegistration.ts"
click node_rider_locations "https://github.com/tafseelkhan/tizzygo-os/blob/main/src/models/tizzyos/shipping/fws/fwsRiderLocation.ts"
click node_delivery_tracking "https://github.com/tafseelkhan/tizzygo-os/blob/main/src/models/tizzyos/shipping/order/deliveryTracking.ts"
click node_media_cleanup "https://github.com/tafseelkhan/tizzygo-os/blob/main/src/jobs/cronMediaCleanup.ts"
click node_cleanup_scheduler "https://github.com/tafseelkhan/tizzygo-os/blob/main/src/schedulers/cleanupScheduler.ts"
click node_media_records "https://github.com/tafseelkhan/tizzygo-os/blob/main/src/models/tizzyos/seller/AddProducts/MediaUploadTracker.ts"
click node_seller_logger "https://github.com/tafseelkhan/tizzygo-os/blob/main/src/utils/tizzyos/seller/logger.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_tizzygo_api,node_tizzyos_api,node_consumer toneBlue
class node_commerce_routes,node_auth,node_checkout,node_payment_service,node_gateway_factory,node_gateway,node_cart_store,node_checkout_store,node_transaction_store,node_event_store toneAmber
class node_ride_routes,node_ride_quote,node_ride_booking,node_ride_dispatch toneMint
class node_seller_routes,node_product_catalog,node_shipping_routes,node_shipping_tracking,node_rider_registry,node_rider_locations,node_delivery_tracking toneRose
class node_media_cleanup,node_cleanup_scheduler,node_media_records,node_seller_logger toneIndigo
```

## Components

### API surfaces

- [TizzyGo API](https://github.com/tafseelkhan/tizzygo-os/blob/main/src/tizzygo/app.ts): `src/tizzygo/app.ts`
- [TizzyOS API](https://github.com/tafseelkhan/tizzygo-os/blob/main/src/tizzyos/app.ts): `src/tizzyos/app.ts`

### Commerce

- [Commerce routes](https://github.com/tafseelkhan/tizzygo-os/tree/main/src/routes/tizzygo): `src/routes/tizzygo`
- [Authentication](https://github.com/tafseelkhan/tizzygo-os/blob/main/src/middleware/tizzygo/authMiddleware.ts): `src/middleware/tizzygo/authMiddleware.ts`
- [Checkout and webhook](https://github.com/tafseelkhan/tizzygo-os/blob/main/src/controller/tizzygo/buynow/webhookController.ts): `src/controller/tizzygo/buynow/webhookController.ts`
- [Payment service](https://github.com/tafseelkhan/tizzygo-os/blob/main/src/services/tizzygo/paymentService.ts): `src/services/tizzygo/paymentService.ts`
- [Gateway selection](https://github.com/tafseelkhan/tizzygo-os/blob/main/src/factories/PaymentGatewayFactory.ts): `src/factories/PaymentGatewayFactory.ts`
- [Razorpay gateway](https://github.com/tafseelkhan/tizzygo-os/blob/main/src/gateways/RazorpayGateway.ts): `src/gateways/RazorpayGateway.ts`
- [Cart data](https://github.com/tafseelkhan/tizzygo-os/blob/main/src/models/tizzygo/cart/Cart.ts): `src/models/tizzygo/cart/Cart.ts`
- [Checkout and orders](https://github.com/tafseelkhan/tizzygo-os/blob/main/src/models/tizzygo/checkout/order.ts): `src/models/tizzygo/checkout/order.ts`
- [Transactions](https://github.com/tafseelkhan/tizzygo-os/blob/main/src/models/tizzygo/checkout/Transaction.ts): `src/models/tizzygo/checkout/Transaction.ts`
- [Webhook events](https://github.com/tafseelkhan/tizzygo-os/blob/main/src/models/tizzygo/checkout/WebhookEvent.ts): `src/models/tizzygo/checkout/WebhookEvent.ts`

### Ride-hailing

- [Ride booking routes](https://github.com/tafseelkhan/tizzygo-os/blob/main/src/routes/tizzyos/cab/rideBookingRoutes.ts): `src/routes/tizzyos/cab/rideBookingRoutes.ts`
- [Ride quotes](https://github.com/tafseelkhan/tizzygo-os/blob/main/src/services/tizzyos/cab/rideQuoteService.ts): `src/services/tizzyos/cab/rideQuoteService.ts`
- [Ride booking](https://github.com/tafseelkhan/tizzygo-os/blob/main/src/services/tizzyos/cab/rideBookingService.ts): `src/services/tizzyos/cab/rideBookingService.ts`
- [Driver dispatch](https://github.com/tafseelkhan/tizzygo-os/blob/main/src/services/tizzyos/cab/rideDispatchService.ts): `src/services/tizzyos/cab/rideDispatchService.ts`

### Seller and shipping

- [Seller operations](https://github.com/tafseelkhan/tizzygo-os/tree/main/src/routes/tizzyos/seller): `src/routes/tizzyos/seller`
- [Product catalog](https://github.com/tafseelkhan/tizzygo-os/blob/main/src/models/tizzyos/seller/AddProducts/Products.ts): `src/models/tizzyos/seller/AddProducts/Products.ts`
- [Shipping routes](https://github.com/tafseelkhan/tizzygo-os/tree/main/src/routes/tizzyos/shipping): `src/routes/tizzyos/shipping`
- [Shipping tracking](https://github.com/tafseelkhan/tizzygo-os/blob/main/src/services/tizzyos/shippings/trackingServices.ts): `src/services/tizzyos/shippings/trackingServices.ts`
- [FWS rider records](https://github.com/tafseelkhan/tizzygo-os/blob/main/src/models/tizzyos/shipping/fws/fwsRegistration.ts): `src/models/tizzyos/shipping/fws/fwsRegistration.ts`
- [Rider locations](https://github.com/tafseelkhan/tizzygo-os/blob/main/src/models/tizzyos/shipping/fws/fwsRiderLocation.ts): `src/models/tizzyos/shipping/fws/fwsRiderLocation.ts`
- [Delivery tracking](https://github.com/tafseelkhan/tizzygo-os/blob/main/src/models/tizzyos/shipping/order/deliveryTracking.ts): `src/models/tizzyos/shipping/order/deliveryTracking.ts`

### Shared runtime

- [Media cleanup](https://github.com/tafseelkhan/tizzygo-os/blob/main/src/jobs/cronMediaCleanup.ts): `src/jobs/cronMediaCleanup.ts`
- [Checkout cleanup](https://github.com/tafseelkhan/tizzygo-os/blob/main/src/schedulers/cleanupScheduler.ts): `src/schedulers/cleanupScheduler.ts`
- [Upload tracking](https://github.com/tafseelkhan/tizzygo-os/blob/main/src/models/tizzyos/seller/AddProducts/MediaUploadTracker.ts): `src/models/tizzyos/seller/AddProducts/MediaUploadTracker.ts`
- [Seller logger](https://github.com/tafseelkhan/tizzygo-os/blob/main/src/utils/tizzyos/seller/logger.ts): `src/utils/tizzyos/seller/logger.ts`

### Other components

- **Client apps**

## Connections

- Client apps → TizzyGo API: sends requests (evidence: `src/tizzygo/app.ts`)
- Client apps → TizzyOS API: sends requests (evidence: `src/tizzyos/app.ts`)
- TizzyGo API → Commerce routes: mounts routes (evidence: `src/tizzygo/app.ts`)
- TizzyOS API → Ride booking routes: mounts routes (evidence: `src/tizzyos/app.ts`)
- TizzyOS API → Seller operations: mounts routes (evidence: `src/tizzyos/app.ts`)
- TizzyOS API → Shipping routes: mounts routes (evidence: `src/tizzyos/app.ts`)
- Commerce routes → Authentication: guards requests (evidence: `src/routes/tizzygo/social/shareRoutes.ts`)
- Commerce routes → Checkout and webhook: routes webhook
- Checkout and webhook → Gateway selection: selects gateway (evidence: `src/controller/tizzygo/buynow/webhookController.ts`)
- Gateway selection → Razorpay gateway: registers gateway (evidence: `src/factories/PaymentGatewayFactory.ts`)
- Checkout and webhook → Webhook events: deduplicates events (evidence: `src/controller/tizzygo/buynow/webhookController.ts`)
- Checkout and webhook → Cart data: clears cart (evidence: `src/controller/tizzygo/buynow/webhookController.ts`)
- Checkout and webhook → Checkout and orders: reads and updates (evidence: `src/controller/tizzygo/buynow/webhookController.ts`)
- Payment service → Checkout and orders: reads and writes (evidence: `src/services/tizzygo/paymentService.ts`)
- Payment service → Cart data: reads and writes (evidence: `src/services/tizzygo/paymentService.ts`)
- Payment service → Transactions: reads and writes (evidence: `src/services/tizzygo/paymentService.ts`)
- Ride booking routes → Authentication: guards booking (evidence: `src/routes/tizzyos/cab/rideBookingRoutes.ts`)
- Ride booking routes → Ride quotes: requests quotes
- Ride booking routes → Ride booking: creates bookings
- Ride booking → Driver dispatch: dispatches drivers
- Seller operations → Product catalog: manages products
- Shipping routes → Shipping tracking: routes tracking
- Shipping tracking → Checkout and orders: reads orders (evidence: `src/services/tizzyos/shippings/trackingServices.ts`)
- Shipping tracking → FWS rider records: reads and writes (evidence: `src/services/tizzyos/shippings/trackingServices.ts`)
- Shipping tracking → Rider locations: reads and writes (evidence: `src/services/tizzyos/shippings/trackingServices.ts`)
- Shipping tracking → Delivery tracking: reads and writes (evidence: `src/services/tizzyos/shippings/trackingServices.ts`)
- Media cleanup → Upload tracking: cleans records
- Checkout cleanup → Checkout and orders: cleans abandoned orders (evidence: `src/schedulers/cleanupScheduler.ts`)
- Checkout cleanup → Transactions: cleans transactions (evidence: `src/schedulers/cleanupScheduler.ts`)
- TizzyGo API → Media cleanup: invokes cleanup (evidence: `src/tizzygo/app.ts`)
- TizzyGo API → Checkout cleanup: starts scheduler (evidence: `src/tizzygo/app.ts`)
- TizzyOS API → Media cleanup: invokes cleanup (evidence: `src/tizzyos/app.ts`)
- TizzyOS API → Checkout cleanup: starts scheduler (evidence: `src/tizzyos/app.ts`)
