# balloprotel/tkb-shop-full architecture

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

- Interactive diagram: https://gitdiagram.com/balloprotel/tkb-shop-full
- Repository: https://github.com/balloprotel/tkb-shop-full
- Video tour (about a minute): https://gitdiagram.com/balloprotel/tkb-shop-full/video

## Overview

TKB Shop is a React storefront backed by FastAPI microservices. Shoppers browse products, manage a cart and favorites, authenticate, place orders, and pay; administrators manage catalog, orders, users, newsletter, and dashboard settings. The frontend uses the API Gateway as its sole API entry point. The README documents service ownership, while sampled service code confirms gateway routing, catalog quoting/stock operations, and backoffice aggregation. Some frontend and service internals were not excerpted, so uncertain connections are omitted.

Main entry points: [`frontend/src/App.jsx`](https://github.com/balloprotel/tkb-shop-full/blob/main/frontend/src/App.jsx) (App Routes), [`services/gateway/app/main.py`](https://github.com/balloprotel/tkb-shop-full/blob/main/services/gateway/app/main.py) (API Gateway), [`frontend/src/utils/api.js`](https://github.com/balloprotel/tkb-shop-full/blob/main/frontend/src/utils/api.js) (API Client), [`services/backoffice/app/main.py`](https://github.com/balloprotel/tkb-shop-full/blob/main/services/backoffice/app/main.py) (Backoffice Service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_storefront["Storefront"]
  node_app["App Routes<br/>[App.jsx]"]
  node_discovery["Product Discovery<br/>[Home.jsx]"]
  node_category["Category Browsing<br/>[CategoryPage.jsx]"]
  node_product["Product Details<br/>[ProductDetails.jsx]"]
  node_cartpage["Cart<br/>[Cart.jsx]"]
  node_checkout["Checkout<br/>[Checkout.jsx]"]
  node_ordersview["Order History<br/>[MyOrders.jsx]"]
  node_profile["User Profile<br/>[UserProfile.jsx]"]
  node_authui["Authentication UI<br/>[Login.jsx]"]
  node_adminui["Admin Console<br/>[DashboardHome.jsx]"]
  node_adminproducts["Catalog Admin<br/>[AdminProducts.jsx]"]
  node_api["API Client<br/>[api.js]"]
end

subgraph group_commerce["Commerce Services"]
  node_catalog[("Catalog Service<br/>[main.py]")]
  node_orders[("Orders Service<br/>[main.py]")]
  node_payments["Payments Service<br/>[main.py]"]
end

subgraph group_platform["Platform Services"]
  node_gateway["API Gateway<br/>[main.py]"]
  node_auth[("Auth Service<br/>[main.py]")]
  node_backoffice[("Backoffice Service<br/>[main.py]")]
  node_notifications["Email Delivery<br/>[main.py]"]
  node_observability["Request Observability<br/>[observability.py]"]
end

subgraph group_state["Client State"]
  node_cartstate["Cart State<br/>[CartContext.jsx]"]
  node_favorites["Favorites State"]
  node_authstorage["Auth Storage<br/>[authStorage.js]"]
end

node_shopper(("Shopper"))
node_admin(("Administrator"))
node_stripe["Stripe"]
node_paypal["PayPal"]

node_shopper -->|"uses"| node_app
node_admin -->|"uses"| node_app
node_app -->|"routes to"| node_discovery
node_app -->|"routes to"| node_category
node_app -->|"routes to"| node_product
node_app -->|"routes to"| node_cartpage
node_app -->|"routes to"| node_checkout
node_app -->|"routes to"| node_ordersview
node_app -->|"routes to"| node_profile
node_app -->|"routes to"| node_authui
node_app -->|"routes to"| node_adminui
node_app -->|"routes to"| node_adminproducts
node_checkout -->|"reads cart"| node_cartstate
node_cartpage -->|"updates cart"| node_cartstate
node_discovery -->|"uses favorites"| node_favorites
node_category -->|"uses favorites"| node_favorites
node_profile -->|"reads auth"| node_authstorage
node_discovery -->|"requests data"| node_api
node_category -->|"requests data"| node_api
node_checkout -->|"submits order"| node_api
node_ordersview -->|"loads orders"| node_api
node_authui -->|"authenticates"| node_api
node_adminui -->|"loads stats"| node_api
node_adminproducts -->|"manages products"| node_api
node_api -->|"calls API"| node_gateway
node_gateway -->|"routes products"| node_catalog
node_gateway -->|"routes auth"| node_auth
node_gateway -->|"routes orders"| node_orders
node_gateway -->|"routes payments"| node_payments
node_gateway -->|"routes backoffice"| node_backoffice
node_gateway -->|"routes notifications"| node_notifications
node_orders -->|"quotes items"| node_catalog
node_orders -->|"commits stock"| node_catalog
node_backoffice -->|"validates admin"| node_auth
node_backoffice -->|"fetches user stats"| node_auth
node_backoffice -->|"fetches catalog stats"| node_catalog
node_backoffice -->|"fetches order stats"| node_orders
node_payments -.->|"integrates"| node_stripe
node_payments -.->|"integrates"| node_paypal
node_auth -->|"installs middleware"| node_observability

click node_app "https://github.com/balloprotel/tkb-shop-full/blob/main/frontend/src/App.jsx"
click node_discovery "https://github.com/balloprotel/tkb-shop-full/blob/main/frontend/src/pages/Home.jsx"
click node_category "https://github.com/balloprotel/tkb-shop-full/blob/main/frontend/src/pages/CategoryPage.jsx"
click node_product "https://github.com/balloprotel/tkb-shop-full/blob/main/frontend/src/pages/ProductDetails.jsx"
click node_cartpage "https://github.com/balloprotel/tkb-shop-full/blob/main/frontend/src/pages/Cart.jsx"
click node_checkout "https://github.com/balloprotel/tkb-shop-full/blob/main/frontend/src/pages/Checkout.jsx"
click node_ordersview "https://github.com/balloprotel/tkb-shop-full/blob/main/frontend/src/pages/MyOrders.jsx"
click node_profile "https://github.com/balloprotel/tkb-shop-full/blob/main/frontend/src/pages/UserProfile.jsx"
click node_authui "https://github.com/balloprotel/tkb-shop-full/blob/main/frontend/src/pages/auth/Login.jsx"
click node_adminui "https://github.com/balloprotel/tkb-shop-full/blob/main/frontend/src/pages/admin/DashboardHome.jsx"
click node_adminproducts "https://github.com/balloprotel/tkb-shop-full/blob/main/frontend/src/pages/admin/AdminProducts.jsx"
click node_cartstate "https://github.com/balloprotel/tkb-shop-full/blob/main/frontend/src/context/CartContext.jsx"
click node_favorites "https://github.com/balloprotel/tkb-shop-full/blob/main/frontend/src/context/FavoritesContext.jsx"
click node_authstorage "https://github.com/balloprotel/tkb-shop-full/blob/main/frontend/src/utils/authStorage.js"
click node_api "https://github.com/balloprotel/tkb-shop-full/blob/main/frontend/src/utils/api.js"
click node_gateway "https://github.com/balloprotel/tkb-shop-full/blob/main/services/gateway/app/main.py"
click node_catalog "https://github.com/balloprotel/tkb-shop-full/blob/main/services/catalog/app/main.py"
click node_orders "https://github.com/balloprotel/tkb-shop-full/blob/main/services/orders/app/main.py"
click node_payments "https://github.com/balloprotel/tkb-shop-full/blob/main/services/payments/app/main.py"
click node_auth "https://github.com/balloprotel/tkb-shop-full/blob/main/services/auth/app/main.py"
click node_backoffice "https://github.com/balloprotel/tkb-shop-full/blob/main/services/backoffice/app/main.py"
click node_notifications "https://github.com/balloprotel/tkb-shop-full/blob/main/services/notifications/app/main.py"
click node_observability "https://github.com/balloprotel/tkb-shop-full/blob/main/services/auth/app/observability.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_app,node_discovery,node_category,node_product,node_cartpage,node_checkout,node_ordersview,node_profile,node_authui,node_adminui,node_adminproducts,node_api toneBlue
class node_catalog,node_orders,node_payments toneAmber
class node_gateway,node_auth,node_backoffice,node_notifications,node_observability toneMint
class node_cartstate,node_favorites,node_authstorage toneRose
class node_shopper,node_admin,node_stripe,node_paypal toneIndigo
```

## Components

### Storefront

- [App Routes](https://github.com/balloprotel/tkb-shop-full/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Product Discovery](https://github.com/balloprotel/tkb-shop-full/blob/main/frontend/src/pages/Home.jsx): `frontend/src/pages/Home.jsx`
- [Category Browsing](https://github.com/balloprotel/tkb-shop-full/blob/main/frontend/src/pages/CategoryPage.jsx): `frontend/src/pages/CategoryPage.jsx`
- [Product Details](https://github.com/balloprotel/tkb-shop-full/blob/main/frontend/src/pages/ProductDetails.jsx): `frontend/src/pages/ProductDetails.jsx`
- [Cart](https://github.com/balloprotel/tkb-shop-full/blob/main/frontend/src/pages/Cart.jsx): `frontend/src/pages/Cart.jsx`
- [Checkout](https://github.com/balloprotel/tkb-shop-full/blob/main/frontend/src/pages/Checkout.jsx): `frontend/src/pages/Checkout.jsx`
- [Order History](https://github.com/balloprotel/tkb-shop-full/blob/main/frontend/src/pages/MyOrders.jsx): `frontend/src/pages/MyOrders.jsx`
- [User Profile](https://github.com/balloprotel/tkb-shop-full/blob/main/frontend/src/pages/UserProfile.jsx): `frontend/src/pages/UserProfile.jsx`
- [Authentication UI](https://github.com/balloprotel/tkb-shop-full/blob/main/frontend/src/pages/auth/Login.jsx): `frontend/src/pages/auth/Login.jsx`
- [Admin Console](https://github.com/balloprotel/tkb-shop-full/blob/main/frontend/src/pages/admin/DashboardHome.jsx): `frontend/src/pages/admin/DashboardHome.jsx`
- [Catalog Admin](https://github.com/balloprotel/tkb-shop-full/blob/main/frontend/src/pages/admin/AdminProducts.jsx): `frontend/src/pages/admin/AdminProducts.jsx`
- [API Client](https://github.com/balloprotel/tkb-shop-full/blob/main/frontend/src/utils/api.js): `frontend/src/utils/api.js`

### Commerce Services

- [Catalog Service](https://github.com/balloprotel/tkb-shop-full/blob/main/services/catalog/app/main.py): `services/catalog/app/main.py`
- [Orders Service](https://github.com/balloprotel/tkb-shop-full/blob/main/services/orders/app/main.py): `services/orders/app/main.py`
- [Payments Service](https://github.com/balloprotel/tkb-shop-full/blob/main/services/payments/app/main.py): `services/payments/app/main.py`

### Platform Services

- [API Gateway](https://github.com/balloprotel/tkb-shop-full/blob/main/services/gateway/app/main.py): `services/gateway/app/main.py`
- [Auth Service](https://github.com/balloprotel/tkb-shop-full/blob/main/services/auth/app/main.py): `services/auth/app/main.py`
- [Backoffice Service](https://github.com/balloprotel/tkb-shop-full/blob/main/services/backoffice/app/main.py): `services/backoffice/app/main.py`
- [Email Delivery](https://github.com/balloprotel/tkb-shop-full/blob/main/services/notifications/app/main.py): `services/notifications/app/main.py`
- [Request Observability](https://github.com/balloprotel/tkb-shop-full/blob/main/services/auth/app/observability.py): `services/auth/app/observability.py`

### Client State

- [Cart State](https://github.com/balloprotel/tkb-shop-full/blob/main/frontend/src/context/CartContext.jsx): `frontend/src/context/CartContext.jsx`
- [Favorites State](https://github.com/balloprotel/tkb-shop-full/blob/main/frontend/src/context/FavoritesContext.jsx): `frontend/src/context/FavoritesContext.jsx`
- [Auth Storage](https://github.com/balloprotel/tkb-shop-full/blob/main/frontend/src/utils/authStorage.js): `frontend/src/utils/authStorage.js`

### Other components

- **Shopper**
- **Administrator**
- **Stripe**
- **PayPal**

## Connections

- Shopper → App Routes: uses (evidence: `README.md`)
- Administrator → App Routes: uses (evidence: `README.md`)
- App Routes → Product Discovery: routes to (evidence: `frontend/src/App.jsx`)
- App Routes → Category Browsing: routes to (evidence: `frontend/src/App.jsx`)
- App Routes → Product Details: routes to (evidence: `frontend/src/App.jsx`)
- App Routes → Cart: routes to (evidence: `frontend/src/App.jsx`)
- App Routes → Checkout: routes to (evidence: `frontend/src/App.jsx`)
- App Routes → Order History: routes to (evidence: `frontend/src/App.jsx`)
- App Routes → User Profile: routes to (evidence: `frontend/src/App.jsx`)
- App Routes → Authentication UI: routes to (evidence: `frontend/src/App.jsx`)
- App Routes → Admin Console: routes to (evidence: `frontend/src/App.jsx`)
- App Routes → Catalog Admin: routes to (evidence: `frontend/src/App.jsx`)
- Checkout → Cart State: reads cart (evidence: `frontend/src/pages/Checkout.jsx`)
- Cart → Cart State: updates cart (evidence: `frontend/src/pages/Cart.jsx`)
- Product Discovery → Favorites State: uses favorites (evidence: `frontend/src/pages/Home.jsx`)
- Category Browsing → Favorites State: uses favorites (evidence: `frontend/src/pages/CategoryPage.jsx`)
- User Profile → Auth Storage: reads auth (evidence: `frontend/src/pages/UserProfile.jsx`)
- Product Discovery → API Client: requests data (evidence: `frontend/src/pages/Home.jsx`)
- Category Browsing → API Client: requests data (evidence: `frontend/src/pages/CategoryPage.jsx`)
- Checkout → API Client: submits order (evidence: `frontend/src/pages/Checkout.jsx`)
- Order History → API Client: loads orders (evidence: `frontend/src/pages/MyOrders.jsx`)
- Authentication UI → API Client: authenticates
- Admin Console → API Client: loads stats (evidence: `frontend/src/pages/admin/DashboardHome.jsx`)
- Catalog Admin → API Client: manages products (evidence: `frontend/src/pages/admin/AdminProducts.jsx`)
- API Client → API Gateway: calls API (evidence: `README.md`)
- API Gateway → Catalog Service: routes products (evidence: `services/gateway/app/main.py`)
- API Gateway → Auth Service: routes auth (evidence: `services/gateway/app/main.py`)
- API Gateway → Orders Service: routes orders (evidence: `services/gateway/app/main.py`)
- API Gateway → Payments Service: routes payments (evidence: `README.md`)
- API Gateway → Backoffice Service: routes backoffice (evidence: `README.md`)
- API Gateway → Email Delivery: routes notifications (evidence: `README.md`)
- Orders Service → Catalog Service: quotes items (evidence: `services/orders/app/main.py`)
- Orders Service → Catalog Service: commits stock (evidence: `services/orders/app/main.py`)
- Backoffice Service → Auth Service: validates admin (evidence: `services/backoffice/app/main.py`)
- Backoffice Service → Auth Service: fetches user stats (evidence: `services/backoffice/app/main.py`)
- Backoffice Service → Catalog Service: fetches catalog stats (evidence: `services/backoffice/app/main.py`)
- Backoffice Service → Orders Service: fetches order stats (evidence: `services/backoffice/app/main.py`)
- Payments Service → Stripe: integrates (evidence: `README.md`)
- Payments Service → PayPal: integrates (evidence: `README.md`)
- Auth Service → Request Observability: installs middleware (evidence: `services/auth/app/main.py`)