# mridulgandhi874/localiq architecture

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

- Interactive diagram: https://gitdiagram.com/mridulgandhi874/localiq
- Repository: https://github.com/mridulgandhi874/localiq

## Overview

LocaliQ is a hyperlocal marketplace for independent neighbourhood shops, with customer takeaway or delivery by LocaliQ riders. Customers discover nearby stock, obtain a server-recomputed quote, place and pay for an order, then follow its separate order and dispatch lifecycles. Merchants manage listings and fulfil orders; riders handle offers and delivery; admins oversee operations and catalog review. The source excerpts show search and quote/order behavior, while other capabilities and app roles are documented in the README; unsampled subsystem links are cited there rather than inferred from imports.

Main entry points: [`apps/customer`](https://github.com/mridulgandhi874/localiq/tree/main/apps/customer) (Customer app), [`web/lib/mongo.ts`](https://github.com/mridulgandhi874/localiq/blob/main/web/lib/mongo.ts) (MongoDB access), [`web/app/api/orders/route.ts`](https://github.com/mridulgandhi874/localiq/blob/main/web/app/api/orders/route.ts) (Order creation), [`web/lib/orders.ts`](https://github.com/mridulgandhi874/localiq/blob/main/web/lib/orders.ts) (Order lifecycle)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_customer["Customer shopping"]
  node_customer_app["Customer app"]
  node_discovery["Product discovery<br/>[route.ts]"]
  node_nearby_shops["Nearby shops"]
  node_quote["Cart quote<br/>[route.ts]"]
  node_order_api["Order creation<br/>[route.ts]"]
end

subgraph group_fulfillment["Shop and delivery"]
  node_merchant_app["Merchant app"]
  node_shop_api["Shop operations"]
  node_rider_app["Rider app"]
  node_dispatch["Rider dispatch<br/>[dispatch.ts]"]
  node_rider_api["Rider workflow"]
end

subgraph group_operations["Platform operations"]
  node_catalog_review["Catalog review"]
  node_contributor_app["Contributor app"]
  node_admin_web["Admin console"]
  node_admin_api["Admin operations"]
end

subgraph group_backend["API and services"]
  node_payment_flow["Payment handling<br/>[route.ts]"]
  node_payment_provider["Payment provider<br/>[provider.ts]"]
  node_orders_domain["Order lifecycle<br/>[orders.ts]"]
end

subgraph group_data["Persistence and identity"]
  node_mongo[("MongoDB access<br/>[mongo.ts]")]
  node_auth["Request authentication<br/>[auth.ts]"]
  node_firebase["Firebase identity<br/>[firebase-admin.ts]"]
end

node_customer_actor(("Customer"))
node_merchant_actor(("Merchant"))
node_rider_actor(("Rider"))
node_admin_actor(("Administrator"))

node_customer_actor -->|"shops with"| node_customer_app
node_customer_app -->|"searches"| node_discovery
node_customer_app -->|"finds shops"| node_nearby_shops
node_discovery -->|"reads products"| node_mongo
node_discovery -->|"resolves sellers"| node_nearby_shops
node_customer_app -->|"requests quote"| node_quote
node_quote -->|"recomputes cart"| node_mongo
node_customer_app -->|"submits token"| node_order_api
node_quote -->|"signs quote for"| node_order_api
node_order_api -->|"transitions status"| node_orders_domain
node_order_api -->|"starts payment"| node_payment_flow
node_payment_flow -->|"verifies event"| node_payment_provider
node_payment_flow -->|"marks paid"| node_orders_domain
node_merchant_actor -->|"manages shop"| node_merchant_app
node_merchant_app -->|"manages listings"| node_shop_api
node_shop_api -->|"updates shop data"| node_mongo
node_contributor_app -->|"submits scans"| node_catalog_review
node_admin_actor -->|"operates platform"| node_admin_web
node_admin_web -->|"manages operations"| node_admin_api
node_admin_api -->|"assigns riders"| node_dispatch
node_admin_api -.->|"reviews catalog"| node_mongo
node_rider_actor -->|"handles deliveries"| node_rider_app
node_rider_app -->|"accepts offers"| node_rider_api
node_rider_api -.->|"updates dispatch"| node_dispatch
node_dispatch -->|"tracks separate state"| node_orders_domain
node_orders_domain -->|"persists orders"| node_mongo
node_customer_app -->|"authenticates"| node_auth
node_auth -->|"verifies token"| node_firebase

click node_customer_app "https://github.com/mridulgandhi874/localiq/tree/main/apps/customer"
click node_discovery "https://github.com/mridulgandhi874/localiq/blob/main/web/app/api/search/route.ts"
click node_nearby_shops "https://github.com/mridulgandhi874/localiq/tree/main/web/app/api/shops/nearby"
click node_quote "https://github.com/mridulgandhi874/localiq/blob/main/web/app/api/orders/quote/route.ts"
click node_order_api "https://github.com/mridulgandhi874/localiq/blob/main/web/app/api/orders/route.ts"
click node_payment_flow "https://github.com/mridulgandhi874/localiq/blob/main/web/app/api/payments/webhook/route.ts"
click node_payment_provider "https://github.com/mridulgandhi874/localiq/blob/main/web/lib/payments/provider.ts"
click node_merchant_app "https://github.com/mridulgandhi874/localiq/tree/main/apps/merchant"
click node_shop_api "https://github.com/mridulgandhi874/localiq/tree/main/web/app/api/shop"
click node_catalog_review "https://github.com/mridulgandhi874/localiq/tree/main/web/app/api/admin/catalog-requests"
click node_contributor_app "https://github.com/mridulgandhi874/localiq/tree/main/apps/contributor"
click node_rider_app "https://github.com/mridulgandhi874/localiq/tree/main/apps/rider"
click node_dispatch "https://github.com/mridulgandhi874/localiq/blob/main/web/lib/dispatch.ts"
click node_rider_api "https://github.com/mridulgandhi874/localiq/tree/main/web/app/api/rider"
click node_admin_web "https://github.com/mridulgandhi874/localiq/tree/main/web/app/admin"
click node_admin_api "https://github.com/mridulgandhi874/localiq/tree/main/web/app/api/admin"
click node_orders_domain "https://github.com/mridulgandhi874/localiq/blob/main/web/lib/orders.ts"
click node_mongo "https://github.com/mridulgandhi874/localiq/blob/main/web/lib/mongo.ts"
click node_auth "https://github.com/mridulgandhi874/localiq/blob/main/web/lib/auth.ts"
click node_firebase "https://github.com/mridulgandhi874/localiq/blob/main/web/lib/firebase-admin.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_customer_app,node_discovery,node_nearby_shops,node_quote,node_order_api toneBlue
class node_merchant_app,node_shop_api,node_rider_app,node_dispatch,node_rider_api toneAmber
class node_catalog_review,node_contributor_app,node_admin_web,node_admin_api toneMint
class node_payment_flow,node_payment_provider,node_orders_domain toneRose
class node_mongo,node_auth,node_firebase,node_customer_actor,node_merchant_actor,node_rider_actor,node_admin_actor toneIndigo
```

## Components

### Customer shopping

- [Customer app](https://github.com/mridulgandhi874/localiq/tree/main/apps/customer): `apps/customer`
- [Product discovery](https://github.com/mridulgandhi874/localiq/blob/main/web/app/api/search/route.ts): `web/app/api/search/route.ts`
- [Nearby shops](https://github.com/mridulgandhi874/localiq/tree/main/web/app/api/shops/nearby): `web/app/api/shops/nearby`
- [Cart quote](https://github.com/mridulgandhi874/localiq/blob/main/web/app/api/orders/quote/route.ts): `web/app/api/orders/quote/route.ts`
- [Order creation](https://github.com/mridulgandhi874/localiq/blob/main/web/app/api/orders/route.ts): `web/app/api/orders/route.ts`

### Shop and delivery

- [Merchant app](https://github.com/mridulgandhi874/localiq/tree/main/apps/merchant): `apps/merchant`
- [Shop operations](https://github.com/mridulgandhi874/localiq/tree/main/web/app/api/shop): `web/app/api/shop`
- [Rider app](https://github.com/mridulgandhi874/localiq/tree/main/apps/rider): `apps/rider`
- [Rider dispatch](https://github.com/mridulgandhi874/localiq/blob/main/web/lib/dispatch.ts): `web/lib/dispatch.ts`
- [Rider workflow](https://github.com/mridulgandhi874/localiq/tree/main/web/app/api/rider): `web/app/api/rider`

### Platform operations

- [Catalog review](https://github.com/mridulgandhi874/localiq/tree/main/web/app/api/admin/catalog-requests): `web/app/api/admin/catalog-requests`
- [Contributor app](https://github.com/mridulgandhi874/localiq/tree/main/apps/contributor): `apps/contributor`
- [Admin console](https://github.com/mridulgandhi874/localiq/tree/main/web/app/admin): `web/app/admin`
- [Admin operations](https://github.com/mridulgandhi874/localiq/tree/main/web/app/api/admin): `web/app/api/admin`

### API and services

- [Payment handling](https://github.com/mridulgandhi874/localiq/blob/main/web/app/api/payments/webhook/route.ts): `web/app/api/payments/webhook/route.ts`
- [Payment provider](https://github.com/mridulgandhi874/localiq/blob/main/web/lib/payments/provider.ts): `web/lib/payments/provider.ts`
- [Order lifecycle](https://github.com/mridulgandhi874/localiq/blob/main/web/lib/orders.ts): `web/lib/orders.ts`

### Persistence and identity

- [MongoDB access](https://github.com/mridulgandhi874/localiq/blob/main/web/lib/mongo.ts): `web/lib/mongo.ts`
- [Request authentication](https://github.com/mridulgandhi874/localiq/blob/main/web/lib/auth.ts): `web/lib/auth.ts`
- [Firebase identity](https://github.com/mridulgandhi874/localiq/blob/main/web/lib/firebase-admin.ts): `web/lib/firebase-admin.ts`

### Other components

- **Customer**
- **Merchant**
- **Rider**
- **Administrator**

## Connections

- Customer → Customer app: shops with
- Customer app → Product discovery: searches
- Customer app → Nearby shops: finds shops
- Product discovery → MongoDB access: reads products (evidence: `web/app/api/search/route.ts`)
- Product discovery → Nearby shops: resolves sellers (evidence: `web/app/api/search/route.ts`)
- Customer app → Cart quote: requests quote
- Cart quote → MongoDB access: recomputes cart (evidence: `web/app/api/orders/quote/route.ts`)
- Customer app → Order creation: submits token (evidence: `web/app/api/orders/route.ts`)
- Cart quote → Order creation: signs quote for
- Order creation → Order lifecycle: transitions status (evidence: `web/app/api/orders/route.ts`)
- Order creation → Payment handling: starts payment
- Payment handling → Payment provider: verifies event
- Payment handling → Order lifecycle: marks paid
- Merchant → Merchant app: manages shop
- Merchant app → Shop operations: manages listings
- Shop operations → MongoDB access: updates shop data (evidence: `web/app/api/shop/listings/route.ts`)
- Contributor app → Catalog review: submits scans
- Administrator → Admin console: operates platform
- Admin console → Admin operations: manages operations
- Admin operations → Rider dispatch: assigns riders (evidence: `web/app/api/admin/dispatch/route.ts`)
- Admin operations → MongoDB access: reviews catalog
- Rider → Rider app: handles deliveries
- Rider app → Rider workflow: accepts offers
- Rider workflow → Rider dispatch: updates dispatch
- Rider dispatch → Order lifecycle: tracks separate state
- Order lifecycle → MongoDB access: persists orders
- Customer app → Request authentication: authenticates
- Request authentication → Firebase identity: verifies token (evidence: `web/lib/auth.ts`)
