# suprabhsharma/tavilo-ecommerce architecture

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

- Interactive diagram: https://gitdiagram.com/suprabhsharma/tavilo-ecommerce
- Repository: https://github.com/suprabhsharma/tavilo-ecommerce

## Overview

Tavilo is a multi-vendor marketplace: customers discover products, maintain carts and wishlists, check out once into vendor-specific sub-orders, then track fulfilment and review delivered purchases. Vendors manage stores, products and fulfilment; admins oversee vendors, roles and categories. The React SPA calls a FastAPI API backed by PostgreSQL, with authentication and role checks. The graph combines documented capabilities with relationships visible in sampled files and the source index; unsampled route details are not inferred.

Main entry points: [`frontend/src/App.jsx`](https://github.com/suprabhsharma/tavilo-ecommerce/blob/main/frontend/src/App.jsx) (React app), [`frontend/src/lib/apiClient.js`](https://github.com/suprabhsharma/tavilo-ecommerce/blob/main/frontend/src/lib/apiClient.js) (API client), [`backend/src/db/models.py`](https://github.com/suprabhsharma/tavilo-ecommerce/blob/main/backend/src/db/models.py) (PostgreSQL data), [`backend/src/cart/routes.py`](https://github.com/suprabhsharma/tavilo-ecommerce/blob/main/backend/src/cart/routes.py) (Cart and wishlist)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Customer and vendor web"]
  node_spa["React app<br/>[App.jsx]"]
  node_auth_pages["Sign-in pages<br/>[Auth.jsx]"]
  node_catalog_pages["Browse catalog<br/>[ProductListing.jsx]"]
  node_cart_checkout["Cart and checkout<br/>[Checkout.jsx]"]
  node_orders_page["Order tracking<br/>[Orders.jsx]"]
  node_vendor_portal["Vendor portal<br/>[VendorPortal.jsx]"]
  node_admin_portal["Admin portal<br/>[AdminPortal.jsx]"]
  node_guest_sync["Guest sync<br/>[useGuestSync.js]"]
  node_api_client["API client<br/>[apiClient.js]"]
  node_auth_store["Session state<br/>[authStore.js]"]
end

subgraph group_api["Marketplace API"]
end

subgraph group_commerce["Commerce workflows"]
  node_catalog_api["Products and categories<br/>[routes.py]"]
  node_cart_api["Cart and wishlist<br/>[routes.py]"]
  node_cart_merge["Guest cart merge<br/>[merge_routes.py]"]
  node_checkout_api["Checkout and fulfilment<br/>[service.py]"]
  node_reviews_api["Purchase reviews<br/>[routes.py]"]
  node_vendor_api["Vendor stores<br/>[routes.py]"]
  node_services_api["Vendor services<br/>[routes.py]"]
end

subgraph group_platform["Identity and operations"]
  node_auth_api["Authentication<br/>[routers.py]"]
  node_auth_guard["Token and role guards<br/>[dependencies.py]"]
  node_admin_api["Administration<br/>[routes.py]"]
  node_audit["Audit log<br/>[audit.py]"]
end

subgraph group_data["Persistence and media"]
  node_database[("PostgreSQL data<br/>[models.py]")]
  node_db_session["Database sessions<br/>[main.py]"]
  node_image_processing["Image processing<br/>[image_storage.py]"]
  node_image_store[("Product image storage<br/>[storage.py]")]
end

node_customer(("Customer"))
node_vendor_actor(("Vendor"))
node_admin_actor(("Admin"))

node_customer -->|"uses"| node_spa
node_vendor_actor -->|"uses"| node_spa
node_admin_actor -->|"uses"| node_spa
node_spa -->|"routes to"| node_auth_pages
node_spa -->|"routes to"| node_catalog_pages
node_spa -->|"routes to"| node_cart_checkout
node_spa -->|"routes to"| node_orders_page
node_spa -->|"routes to"| node_vendor_portal
node_spa -->|"routes to"| node_admin_portal
node_spa -->|"mounts"| node_guest_sync
node_auth_pages -->|"updates session"| node_auth_store
node_spa -->|"guards routes"| node_auth_store
node_guest_sync -->|"merges guest data"| node_cart_merge
node_cart_checkout -.->|"requests API"| node_api_client
node_catalog_pages -.->|"requests API"| node_api_client
node_orders_page -.->|"requests API"| node_api_client
node_vendor_portal -.->|"requests API"| node_api_client
node_api_client -->|"reads session"| node_auth_store
node_api_client -.->|"calls API"| node_catalog_api
node_api_client -.->|"calls API"| node_cart_api
node_api_client -.->|"calls API"| node_checkout_api
node_api_client -.->|"calls API"| node_vendor_api
node_api_client -.->|"calls API"| node_admin_api
node_auth_api -.->|"validates tokens"| node_auth_guard
node_cart_api -->|"requires identity"| node_auth_guard
node_cart_merge -.->|"updates cart state"| node_cart_api
node_catalog_api -.->|"reads catalog"| node_database
node_cart_api -->|"reads and writes"| node_database
node_checkout_api -->|"commits orders"| node_database
node_reviews_api -->|"stores reviews"| node_database
node_vendor_api -->|"reads and writes"| node_database
node_services_api -.->|"reads service data"| node_database
node_admin_api -->|"records actions"| node_audit
node_admin_api -.->|"manages platform data"| node_database
node_catalog_api -->|"handles uploads"| node_image_processing
node_image_processing -->|"stores variants"| node_image_store
node_db_session -->|"opens sessions"| node_database
node_catalog_api -->|"gets session"| node_db_session
node_cart_api -->|"gets session"| node_db_session
node_checkout_api -->|"gets session"| node_db_session
node_vendor_api -->|"gets session"| node_db_session

click node_spa "https://github.com/suprabhsharma/tavilo-ecommerce/blob/main/frontend/src/App.jsx"
click node_auth_pages "https://github.com/suprabhsharma/tavilo-ecommerce/blob/main/frontend/src/pages/Auth.jsx"
click node_catalog_pages "https://github.com/suprabhsharma/tavilo-ecommerce/blob/main/frontend/src/pages/ProductListing.jsx"
click node_cart_checkout "https://github.com/suprabhsharma/tavilo-ecommerce/blob/main/frontend/src/pages/Checkout.jsx"
click node_orders_page "https://github.com/suprabhsharma/tavilo-ecommerce/blob/main/frontend/src/pages/Orders.jsx"
click node_vendor_portal "https://github.com/suprabhsharma/tavilo-ecommerce/blob/main/frontend/src/pages/VendorPortal.jsx"
click node_admin_portal "https://github.com/suprabhsharma/tavilo-ecommerce/blob/main/frontend/src/pages/AdminPortal.jsx"
click node_guest_sync "https://github.com/suprabhsharma/tavilo-ecommerce/blob/main/frontend/src/hooks/useGuestSync.js"
click node_api_client "https://github.com/suprabhsharma/tavilo-ecommerce/blob/main/frontend/src/lib/apiClient.js"
click node_auth_store "https://github.com/suprabhsharma/tavilo-ecommerce/blob/main/frontend/src/store/authStore.js"
click node_auth_api "https://github.com/suprabhsharma/tavilo-ecommerce/blob/main/backend/src/auth/routers.py"
click node_auth_guard "https://github.com/suprabhsharma/tavilo-ecommerce/blob/main/backend/src/auth/dependencies.py"
click node_catalog_api "https://github.com/suprabhsharma/tavilo-ecommerce/blob/main/backend/src/products/routes.py"
click node_cart_api "https://github.com/suprabhsharma/tavilo-ecommerce/blob/main/backend/src/cart/routes.py"
click node_cart_merge "https://github.com/suprabhsharma/tavilo-ecommerce/blob/main/backend/src/cart/merge_routes.py"
click node_checkout_api "https://github.com/suprabhsharma/tavilo-ecommerce/blob/main/backend/src/orders/service.py"
click node_reviews_api "https://github.com/suprabhsharma/tavilo-ecommerce/blob/main/backend/src/reviews/routes.py"
click node_vendor_api "https://github.com/suprabhsharma/tavilo-ecommerce/blob/main/backend/src/vendors/routes.py"
click node_services_api "https://github.com/suprabhsharma/tavilo-ecommerce/blob/main/backend/src/services/routes.py"
click node_admin_api "https://github.com/suprabhsharma/tavilo-ecommerce/blob/main/backend/src/admin/routes.py"
click node_audit "https://github.com/suprabhsharma/tavilo-ecommerce/blob/main/backend/src/audit.py"
click node_database "https://github.com/suprabhsharma/tavilo-ecommerce/blob/main/backend/src/db/models.py"
click node_db_session "https://github.com/suprabhsharma/tavilo-ecommerce/blob/main/backend/src/db/main.py"
click node_image_processing "https://github.com/suprabhsharma/tavilo-ecommerce/blob/main/backend/src/products/image_storage.py"
click node_image_store "https://github.com/suprabhsharma/tavilo-ecommerce/blob/main/backend/src/products/storage.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_spa,node_auth_pages,node_catalog_pages,node_cart_checkout,node_orders_page,node_vendor_portal,node_admin_portal,node_guest_sync,node_api_client,node_auth_store toneBlue
class node_catalog_api,node_cart_api,node_cart_merge,node_checkout_api,node_reviews_api,node_vendor_api,node_services_api toneMint
class node_auth_api,node_auth_guard,node_admin_api,node_audit toneRose
class node_database,node_db_session,node_image_processing,node_image_store,node_customer,node_vendor_actor,node_admin_actor toneIndigo
```

## Components

### Customer and vendor web

- [React app](https://github.com/suprabhsharma/tavilo-ecommerce/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Sign-in pages](https://github.com/suprabhsharma/tavilo-ecommerce/blob/main/frontend/src/pages/Auth.jsx): `frontend/src/pages/Auth.jsx`
- [Browse catalog](https://github.com/suprabhsharma/tavilo-ecommerce/blob/main/frontend/src/pages/ProductListing.jsx): `frontend/src/pages/ProductListing.jsx`
- [Cart and checkout](https://github.com/suprabhsharma/tavilo-ecommerce/blob/main/frontend/src/pages/Checkout.jsx): `frontend/src/pages/Checkout.jsx`
- [Order tracking](https://github.com/suprabhsharma/tavilo-ecommerce/blob/main/frontend/src/pages/Orders.jsx): `frontend/src/pages/Orders.jsx`
- [Vendor portal](https://github.com/suprabhsharma/tavilo-ecommerce/blob/main/frontend/src/pages/VendorPortal.jsx): `frontend/src/pages/VendorPortal.jsx`
- [Admin portal](https://github.com/suprabhsharma/tavilo-ecommerce/blob/main/frontend/src/pages/AdminPortal.jsx): `frontend/src/pages/AdminPortal.jsx`
- [Guest sync](https://github.com/suprabhsharma/tavilo-ecommerce/blob/main/frontend/src/hooks/useGuestSync.js): `frontend/src/hooks/useGuestSync.js`
- [API client](https://github.com/suprabhsharma/tavilo-ecommerce/blob/main/frontend/src/lib/apiClient.js): `frontend/src/lib/apiClient.js`
- [Session state](https://github.com/suprabhsharma/tavilo-ecommerce/blob/main/frontend/src/store/authStore.js): `frontend/src/store/authStore.js`

### Commerce workflows

- [Products and categories](https://github.com/suprabhsharma/tavilo-ecommerce/blob/main/backend/src/products/routes.py): `backend/src/products/routes.py`
- [Cart and wishlist](https://github.com/suprabhsharma/tavilo-ecommerce/blob/main/backend/src/cart/routes.py): `backend/src/cart/routes.py`
- [Guest cart merge](https://github.com/suprabhsharma/tavilo-ecommerce/blob/main/backend/src/cart/merge_routes.py): `backend/src/cart/merge_routes.py`
- [Checkout and fulfilment](https://github.com/suprabhsharma/tavilo-ecommerce/blob/main/backend/src/orders/service.py): `backend/src/orders/service.py`
- [Purchase reviews](https://github.com/suprabhsharma/tavilo-ecommerce/blob/main/backend/src/reviews/routes.py): `backend/src/reviews/routes.py`
- [Vendor stores](https://github.com/suprabhsharma/tavilo-ecommerce/blob/main/backend/src/vendors/routes.py): `backend/src/vendors/routes.py`
- [Vendor services](https://github.com/suprabhsharma/tavilo-ecommerce/blob/main/backend/src/services/routes.py): `backend/src/services/routes.py`

### Identity and operations

- [Authentication](https://github.com/suprabhsharma/tavilo-ecommerce/blob/main/backend/src/auth/routers.py): `backend/src/auth/routers.py`
- [Token and role guards](https://github.com/suprabhsharma/tavilo-ecommerce/blob/main/backend/src/auth/dependencies.py): `backend/src/auth/dependencies.py`
- [Administration](https://github.com/suprabhsharma/tavilo-ecommerce/blob/main/backend/src/admin/routes.py): `backend/src/admin/routes.py`
- [Audit log](https://github.com/suprabhsharma/tavilo-ecommerce/blob/main/backend/src/audit.py): `backend/src/audit.py`

### Persistence and media

- [PostgreSQL data](https://github.com/suprabhsharma/tavilo-ecommerce/blob/main/backend/src/db/models.py): `backend/src/db/models.py`
- [Database sessions](https://github.com/suprabhsharma/tavilo-ecommerce/blob/main/backend/src/db/main.py): `backend/src/db/main.py`
- [Image processing](https://github.com/suprabhsharma/tavilo-ecommerce/blob/main/backend/src/products/image_storage.py): `backend/src/products/image_storage.py`
- [Product image storage](https://github.com/suprabhsharma/tavilo-ecommerce/blob/main/backend/src/products/storage.py): `backend/src/products/storage.py`

### Other components

- **Customer**
- **Vendor**
- **Admin**

## Connections

- Customer → React app: uses (evidence: `README.md`)
- Vendor → React app: uses (evidence: `README.md`)
- Admin → React app: uses (evidence: `README.md`)
- React app → Sign-in pages: routes to (evidence: `frontend/src/App.jsx`)
- React app → Browse catalog: routes to (evidence: `frontend/src/App.jsx`)
- React app → Cart and checkout: routes to (evidence: `frontend/src/App.jsx`)
- React app → Order tracking: routes to (evidence: `frontend/src/App.jsx`)
- React app → Vendor portal: routes to (evidence: `frontend/src/App.jsx`)
- React app → Admin portal: routes to (evidence: `frontend/src/App.jsx`)
- React app → Guest sync: mounts (evidence: `frontend/src/App.jsx`)
- Sign-in pages → Session state: updates session (evidence: `frontend/src/pages/Auth.jsx`)
- React app → Session state: guards routes (evidence: `frontend/src/App.jsx`)
- Guest sync → Guest cart merge: merges guest data (evidence: `frontend/src/hooks/useGuestSync.js`)
- Cart and checkout → API client: requests API
- Browse catalog → API client: requests API
- Order tracking → API client: requests API
- Vendor portal → API client: requests API
- API client → Session state: reads session (evidence: `frontend/src/lib/apiClient.js`)
- API client → Products and categories: calls API
- API client → Cart and wishlist: calls API
- API client → Checkout and fulfilment: calls API
- API client → Vendor stores: calls API
- API client → Administration: calls API
- Authentication → Token and role guards: validates tokens
- Cart and wishlist → Token and role guards: requires identity (evidence: `backend/src/cart/routes.py`)
- Guest cart merge → Cart and wishlist: updates cart state
- Products and categories → PostgreSQL data: reads catalog (evidence: `backend/src/products/routes.py`)
- Cart and wishlist → PostgreSQL data: reads and writes (evidence: `backend/src/cart/routes.py`)
- Checkout and fulfilment → PostgreSQL data: commits orders (evidence: `backend/src/orders/service.py`)
- Purchase reviews → PostgreSQL data: stores reviews (evidence: `backend/src/reviews/routes.py`)
- Vendor stores → PostgreSQL data: reads and writes (evidence: `backend/src/vendors/routes.py`)
- Vendor services → PostgreSQL data: reads service data (evidence: `backend/src/services/routes.py`)
- Administration → Audit log: records actions (evidence: `backend/src/admin/routes.py`)
- Administration → PostgreSQL data: manages platform data (evidence: `backend/src/admin/routes.py`)
- Products and categories → Image processing: handles uploads (evidence: `backend/src/products/routes.py`)
- Image processing → Product image storage: stores variants (evidence: `backend/src/products/image_storage.py`)
- Database sessions → PostgreSQL data: opens sessions (evidence: `backend/src/db/main.py`)
- Products and categories → Database sessions: gets session (evidence: `backend/src/products/routes.py`)
- Cart and wishlist → Database sessions: gets session (evidence: `backend/src/cart/routes.py`)
- Checkout and fulfilment → Database sessions: gets session (evidence: `backend/src/orders/routes.py`)
- Vendor stores → Database sessions: gets session (evidence: `backend/src/vendors/routes.py`)
