# saumya028/local-mart architecture

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

- Interactive diagram: https://gitdiagram.com/saumya028/local-mart
- Repository: https://github.com/saumya028/local-mart

## Overview

LocalMart is a multi-vendor marketplace: customers browse products, maintain a cart and address, place per-shop orders, and track payment and fulfillment; shops manage catalog, orders, returns, and payment settings, while administrators manage platform settings and users. The frontend calls a FastAPI backend, which authenticates Supabase sessions and persists marketplace state in Postgres, with Redis supporting cart, cache, and rate-limit behavior. The README documents direct UPI/cash payments and major customer, shop, and admin capabilities. Some frontend-to-endpoint wiring and unsampled modules are not shown, so those links are omitted.

Main entry points: [`backend/app/main.py`](https://github.com/saumya028/local-mart/blob/main/backend/app/main.py) (API application), [`backend/app/core/db.py`](https://github.com/saumya028/local-mart/blob/main/backend/app/core/db.py) (Postgres), [`backend/app/routers/orders.py`](https://github.com/saumya028/local-mart/blob/main/backend/app/routers/orders.py) (Orders and payments), [`backend/app/routers/auth.py`](https://github.com/saumya028/local-mart/blob/main/backend/app/routers/auth.py) (Authentication)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Customer storefront"]
  node_storefront["Browse storefront<br/>[page.tsx]"]
  node_product_detail["Product detail<br/>[page.tsx]"]
  node_cart_checkout["Cart and checkout<br/>[page.tsx]"]
  node_order_tracking["Order tracking<br/>[page.tsx]"]
  node_account["Account and returns<br/>[page.tsx]"]
  node_shop_dashboard_ui["Shop dashboard<br/>[page.tsx]"]
  node_admin_ui["Admin panel<br/>[page.tsx]"]
  node_api_client["API client<br/>[apiClient.ts]"]
end

subgraph group_api["Marketplace API"]
  node_api_entry["API application<br/>[main.py]"]
  node_auth_routes["Authentication<br/>[auth.py]"]
  node_catalog_routes["Catalog and shops<br/>[products.py]"]
  node_cart_routes["Cart operations<br/>[cart.py]"]
  node_order_routes["Orders and payments<br/>[orders.py]"]
  node_return_routes["Returns<br/>[returns.py]"]
  node_shop_routes["Shop operations<br/>[shop_dashboard.py]"]
  node_admin_routes["Administration<br/>[admin.py]"]
end

subgraph group_domain["Domain services"]
  node_auth_security["JWT and roles<br/>[security.py]"]
  node_payment_logic["Payment confirmation"]
  node_cart_logic["Cart service<br/>[cart.py]"]
  node_order_states["Order lifecycle<br/>[order_status.py]"]
  node_return_states["Return lifecycle<br/>[return_status.py]"]
end

subgraph group_infra["Platform services"]
  node_postgres[("Postgres<br/>[db.py]")]
  node_redis[("Redis client<br/>[redis_client.py]")]
  node_rate_limit["Rate limiting<br/>[rate_limit.py]"]
  node_observability["Request logging<br/>[logging_config.py]"]
end

node_customer(("Customer"))
node_shop_operator(("Shop operator"))
node_administrator(("Administrator"))

node_customer -->|"browses"| node_storefront
node_customer -->|"views products"| node_product_detail
node_customer -->|"checks out"| node_cart_checkout
node_customer -->|"tracks orders"| node_order_tracking
node_customer -->|"manages account"| node_account
node_shop_operator -->|"manages shop"| node_shop_dashboard_ui
node_administrator -->|"manages platform"| node_admin_ui
node_api_client -->|"sends requests"| node_api_entry
node_api_entry -->|"registers"| node_auth_routes
node_api_entry -->|"registers"| node_catalog_routes
node_api_entry -->|"registers"| node_cart_routes
node_api_entry -->|"registers"| node_order_routes
node_api_entry -->|"registers"| node_return_routes
node_api_entry -->|"registers"| node_shop_routes
node_api_entry -->|"registers"| node_admin_routes
node_auth_routes -->|"verifies identity"| node_auth_security
node_auth_routes -->|"opens session"| node_postgres
node_cart_routes -->|"uses cart service"| node_cart_logic
node_cart_routes -->|"opens session"| node_postgres
node_order_routes -->|"uses cart service"| node_cart_logic
node_order_routes -->|"confirms payment"| node_payment_logic
node_order_routes -->|"uses lifecycle"| node_order_states
node_order_routes -->|"opens session"| node_postgres
node_return_routes -->|"uses lifecycle"| node_return_states
node_return_routes -->|"opens session"| node_postgres
node_shop_routes -->|"opens session"| node_postgres
node_admin_routes -->|"opens session"| node_postgres
node_auth_routes -->|"limits requests"| node_rate_limit
node_rate_limit -->|"uses Redis"| node_redis
node_api_entry -->|"configures logging"| node_observability

click node_storefront "https://github.com/saumya028/local-mart/blob/main/frontend/app/page.tsx"
click node_product_detail "https://github.com/saumya028/local-mart/blob/main/frontend/app/product/%5Bid%5D/page.tsx"
click node_cart_checkout "https://github.com/saumya028/local-mart/blob/main/frontend/app/checkout/page.tsx"
click node_order_tracking "https://github.com/saumya028/local-mart/blob/main/frontend/app/orders/%5Bid%5D/page.tsx"
click node_account "https://github.com/saumya028/local-mart/blob/main/frontend/app/profile/page.tsx"
click node_shop_dashboard_ui "https://github.com/saumya028/local-mart/blob/main/frontend/app/shop/dashboard/page.tsx"
click node_admin_ui "https://github.com/saumya028/local-mart/blob/main/frontend/app/admin/page.tsx"
click node_api_client "https://github.com/saumya028/local-mart/blob/main/frontend/lib/apiClient.ts"
click node_api_entry "https://github.com/saumya028/local-mart/blob/main/backend/app/main.py"
click node_auth_routes "https://github.com/saumya028/local-mart/blob/main/backend/app/routers/auth.py"
click node_catalog_routes "https://github.com/saumya028/local-mart/blob/main/backend/app/routers/products.py"
click node_cart_routes "https://github.com/saumya028/local-mart/blob/main/backend/app/routers/cart.py"
click node_order_routes "https://github.com/saumya028/local-mart/blob/main/backend/app/routers/orders.py"
click node_return_routes "https://github.com/saumya028/local-mart/blob/main/backend/app/routers/returns.py"
click node_shop_routes "https://github.com/saumya028/local-mart/blob/main/backend/app/routers/shop_dashboard.py"
click node_admin_routes "https://github.com/saumya028/local-mart/blob/main/backend/app/routers/admin.py"
click node_auth_security "https://github.com/saumya028/local-mart/blob/main/backend/app/core/security.py"
click node_payment_logic "https://github.com/saumya028/local-mart/blob/main/backend/app/core/payment_confirmation.py"
click node_cart_logic "https://github.com/saumya028/local-mart/blob/main/backend/app/core/cart.py"
click node_order_states "https://github.com/saumya028/local-mart/blob/main/backend/app/core/order_status.py"
click node_return_states "https://github.com/saumya028/local-mart/blob/main/backend/app/core/return_status.py"
click node_postgres "https://github.com/saumya028/local-mart/blob/main/backend/app/core/db.py"
click node_redis "https://github.com/saumya028/local-mart/blob/main/backend/app/core/redis_client.py"
click node_rate_limit "https://github.com/saumya028/local-mart/blob/main/backend/app/core/rate_limit.py"
click node_observability "https://github.com/saumya028/local-mart/blob/main/backend/app/core/logging_config.py"

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_storefront,node_product_detail,node_cart_checkout,node_order_tracking,node_account,node_shop_dashboard_ui,node_admin_ui,node_api_client toneBlue
class node_api_entry,node_auth_routes,node_catalog_routes,node_cart_routes,node_order_routes,node_return_routes,node_shop_routes,node_admin_routes toneAmber
class node_auth_security,node_payment_logic,node_cart_logic,node_order_states,node_return_states toneMint
class node_postgres,node_redis,node_rate_limit,node_observability toneRose
class node_customer,node_shop_operator,node_administrator toneIndigo
```

## Components

### Customer storefront

- [Browse storefront](https://github.com/saumya028/local-mart/blob/main/frontend/app/page.tsx): `frontend/app/page.tsx`
- [Product detail](https://github.com/saumya028/local-mart/blob/main/frontend/app/product/%5Bid%5D/page.tsx): `frontend/app/product/[id]/page.tsx`
- [Cart and checkout](https://github.com/saumya028/local-mart/blob/main/frontend/app/checkout/page.tsx): `frontend/app/checkout/page.tsx`
- [Order tracking](https://github.com/saumya028/local-mart/blob/main/frontend/app/orders/%5Bid%5D/page.tsx): `frontend/app/orders/[id]/page.tsx`
- [Account and returns](https://github.com/saumya028/local-mart/blob/main/frontend/app/profile/page.tsx): `frontend/app/profile/page.tsx`
- [Shop dashboard](https://github.com/saumya028/local-mart/blob/main/frontend/app/shop/dashboard/page.tsx): `frontend/app/shop/dashboard/page.tsx`
- [Admin panel](https://github.com/saumya028/local-mart/blob/main/frontend/app/admin/page.tsx): `frontend/app/admin/page.tsx`
- [API client](https://github.com/saumya028/local-mart/blob/main/frontend/lib/apiClient.ts): `frontend/lib/apiClient.ts`

### Marketplace API

- [API application](https://github.com/saumya028/local-mart/blob/main/backend/app/main.py): `backend/app/main.py`
- [Authentication](https://github.com/saumya028/local-mart/blob/main/backend/app/routers/auth.py): `backend/app/routers/auth.py`
- [Catalog and shops](https://github.com/saumya028/local-mart/blob/main/backend/app/routers/products.py): `backend/app/routers/products.py`
- [Cart operations](https://github.com/saumya028/local-mart/blob/main/backend/app/routers/cart.py): `backend/app/routers/cart.py`
- [Orders and payments](https://github.com/saumya028/local-mart/blob/main/backend/app/routers/orders.py): `backend/app/routers/orders.py`
- [Returns](https://github.com/saumya028/local-mart/blob/main/backend/app/routers/returns.py): `backend/app/routers/returns.py`
- [Shop operations](https://github.com/saumya028/local-mart/blob/main/backend/app/routers/shop_dashboard.py): `backend/app/routers/shop_dashboard.py`
- [Administration](https://github.com/saumya028/local-mart/blob/main/backend/app/routers/admin.py): `backend/app/routers/admin.py`

### Domain services

- [JWT and roles](https://github.com/saumya028/local-mart/blob/main/backend/app/core/security.py): `backend/app/core/security.py`
- [Payment confirmation](https://github.com/saumya028/local-mart/blob/main/backend/app/core/payment_confirmation.py): `backend/app/core/payment_confirmation.py`
- [Cart service](https://github.com/saumya028/local-mart/blob/main/backend/app/core/cart.py): `backend/app/core/cart.py`
- [Order lifecycle](https://github.com/saumya028/local-mart/blob/main/backend/app/core/order_status.py): `backend/app/core/order_status.py`
- [Return lifecycle](https://github.com/saumya028/local-mart/blob/main/backend/app/core/return_status.py): `backend/app/core/return_status.py`

### Platform services

- [Postgres](https://github.com/saumya028/local-mart/blob/main/backend/app/core/db.py): `backend/app/core/db.py`
- [Redis client](https://github.com/saumya028/local-mart/blob/main/backend/app/core/redis_client.py): `backend/app/core/redis_client.py`
- [Rate limiting](https://github.com/saumya028/local-mart/blob/main/backend/app/core/rate_limit.py): `backend/app/core/rate_limit.py`
- [Request logging](https://github.com/saumya028/local-mart/blob/main/backend/app/core/logging_config.py): `backend/app/core/logging_config.py`

### Other components

- **Customer**
- **Shop operator**
- **Administrator**

## Connections

- Customer → Browse storefront: browses
- Customer → Product detail: views products
- Customer → Cart and checkout: checks out
- Customer → Order tracking: tracks orders
- Customer → Account and returns: manages account
- Shop operator → Shop dashboard: manages shop
- Administrator → Admin panel: manages platform
- API client → API application: sends requests (evidence: `frontend/lib/apiClient.ts`)
- API application → Authentication: registers (evidence: `backend/app/main.py`)
- API application → Catalog and shops: registers (evidence: `backend/app/main.py`)
- API application → Cart operations: registers (evidence: `backend/app/main.py`)
- API application → Orders and payments: registers (evidence: `backend/app/main.py`)
- API application → Returns: registers (evidence: `backend/app/main.py`)
- API application → Shop operations: registers (evidence: `backend/app/main.py`)
- API application → Administration: registers (evidence: `backend/app/main.py`)
- Authentication → JWT and roles: verifies identity (evidence: `backend/app/routers/auth.py`)
- Authentication → Postgres: opens session (evidence: `backend/app/routers/auth.py`)
- Cart operations → Cart service: uses cart service (evidence: `backend/app/routers/cart.py`)
- Cart operations → Postgres: opens session (evidence: `backend/app/routers/cart.py`)
- Orders and payments → Cart service: uses cart service (evidence: `backend/app/routers/orders.py`)
- Orders and payments → Payment confirmation: confirms payment (evidence: `backend/app/routers/orders.py`)
- Orders and payments → Order lifecycle: uses lifecycle (evidence: `backend/app/routers/orders.py`)
- Orders and payments → Postgres: opens session (evidence: `backend/app/routers/orders.py`)
- Returns → Return lifecycle: uses lifecycle (evidence: `backend/app/routers/returns.py`)
- Returns → Postgres: opens session (evidence: `backend/app/routers/returns.py`)
- Shop operations → Postgres: opens session
- Administration → Postgres: opens session (evidence: `backend/app/routers/admin.py`)
- Authentication → Rate limiting: limits requests (evidence: `backend/app/routers/auth.py`)
- Rate limiting → Redis client: uses Redis (evidence: `backend/app/core/rate_limit.py`)
- API application → Request logging: configures logging (evidence: `backend/app/main.py`)
