# lindsey5/zhiyuan-backend architecture

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

- Interactive diagram: https://gitdiagram.com/lindsey5/zhiyuan-backend
- Repository: https://github.com/lindsey5/zhiyuan-backend

## Overview

Zhiyuan Backend is an Express API for identity and permissions, catalog and orders, and distributor inventory and sales operations. A client request enters through the app’s mounted routes and is handled by domain controllers; selected workflows also use service-layer logic, persistent models, caching, media storage, or real-time notifications. The README documents audit logging, reviews, returns, sponsored items, and other capabilities beyond the sampled source. Their route mounts are visible, but unsampled handler wiring is not inferred.

Main entry points: [`app.ts`](https://github.com/lindsey5/zhiyuan-backend/blob/main/app.ts) (Express app), [`controllers/productController.ts`](https://github.com/lindsey5/zhiyuan-backend/blob/main/controllers/productController.ts) (Catalog management), [`controllers/reviewController.ts`](https://github.com/lindsey5/zhiyuan-backend/blob/main/controllers/reviewController.ts) (Review handling), [`routes/distributorRoutes.ts`](https://github.com/lindsey5/zhiyuan-backend/blob/main/routes/distributorRoutes.ts) (Distributor routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and access"]
  node_app["Express app<br/>[app.ts]"]
  node_auth_routes["Auth routes<br/>[authRoutes.ts]"]
  node_auth_controller["Authentication<br/>[authController.ts]"]
  node_auth_middleware["Auth and permissions<br/>[authMiddleware.ts]"]
  node_user_routes["User routes<br/>[userRoutes.ts]"]
  node_user_controller["User management<br/>[userController.ts]"]
  node_role_routes["Role routes<br/>[roleRoutes.ts]"]
end

subgraph group_commerce["Catalog and commerce"]
  node_product_routes["Product routes<br/>[productRoutes.ts]"]
  node_product_controller["Catalog management"]
  node_order_routes["Order routes<br/>[orderRoutes.ts]"]
  node_order_controller["Order handling<br/>[orderController.ts]"]
  node_review_routes["Review routes<br/>[reviewRoutes.ts]"]
  node_review_controller["Review handling"]
end

subgraph group_distribution["Distributor operations"]
  node_distributor_routes["Distributor routes"]
  node_distributor_controller["Distributor management"]
  node_sales_routes["Sales routes"]
  node_sales_controller["Sales reporting"]
  node_return_routes["Return routes"]
  node_return_controller["Return handling"]
  node_transfer_service["Stock transfer logic"]
end

subgraph group_runtime["Runtime services"]
  node_cloudinary["Cloudinary media<br/>[cloudinary.ts]"]
  node_socket["Socket.IO<br/>[socket.ts]"]
  node_notifications["Notification service"]
  node_distributor_socket["Distributor notifications"]
end

subgraph group_state["Persistence and cache"]
  node_mongo[("MongoDB<br/>[db.ts]")]
  node_redis[("Redis cache<br/>[redis.ts]")]
end

node_client(("API client"))

node_client -->|"sends request"| node_app
node_app -->|"mounts routes"| node_auth_routes
node_app -->|"mounts routes"| node_user_routes
node_app -->|"mounts routes"| node_role_routes
node_app -->|"mounts routes"| node_product_routes
node_app -->|"mounts routes"| node_order_routes
node_app -->|"mounts routes"| node_review_routes
node_app -->|"mounts routes"| node_distributor_routes
node_app -->|"mounts routes"| node_sales_routes
node_app -->|"mounts routes"| node_return_routes
node_auth_routes -->|"dispatches to"| node_auth_controller
node_user_routes -->|"dispatches to"| node_user_controller
node_product_routes -->|"dispatches to"| node_product_controller
node_review_routes -->|"dispatches to"| node_review_controller
node_distributor_routes -->|"checks access"| node_auth_middleware
node_distributor_routes -->|"dispatches to"| node_distributor_controller
node_sales_routes -->|"checks access"| node_auth_middleware
node_sales_routes -->|"dispatches to"| node_sales_controller
node_return_routes -->|"dispatches to"| node_return_controller
node_review_controller -->|"reads and writes cache"| node_redis
node_product_controller -->|"uploads media"| node_cloudinary
node_return_controller -->|"emits notification"| node_distributor_socket
node_transfer_service -->|"emits notification"| node_distributor_socket
node_notifications -->|"emits events"| node_socket
node_transfer_service -->|"invalidates cache"| node_redis
node_return_controller -->|"persists workflow"| node_mongo
node_product_controller -->|"reads and writes catalog"| node_mongo
node_review_controller -->|"reads and writes reviews"| node_mongo

click node_app "https://github.com/lindsey5/zhiyuan-backend/blob/main/app.ts"
click node_auth_routes "https://github.com/lindsey5/zhiyuan-backend/blob/main/routes/authRoutes.ts"
click node_auth_controller "https://github.com/lindsey5/zhiyuan-backend/blob/main/controllers/authController.ts"
click node_auth_middleware "https://github.com/lindsey5/zhiyuan-backend/blob/main/middlewares/authMiddleware.ts"
click node_user_routes "https://github.com/lindsey5/zhiyuan-backend/blob/main/routes/userRoutes.ts"
click node_user_controller "https://github.com/lindsey5/zhiyuan-backend/blob/main/controllers/userController.ts"
click node_role_routes "https://github.com/lindsey5/zhiyuan-backend/blob/main/routes/roleRoutes.ts"
click node_product_routes "https://github.com/lindsey5/zhiyuan-backend/blob/main/routes/productRoutes.ts"
click node_product_controller "https://github.com/lindsey5/zhiyuan-backend/blob/main/controllers/productController.ts"
click node_order_routes "https://github.com/lindsey5/zhiyuan-backend/blob/main/routes/orderRoutes.ts"
click node_order_controller "https://github.com/lindsey5/zhiyuan-backend/blob/main/controllers/orderController.ts"
click node_review_routes "https://github.com/lindsey5/zhiyuan-backend/blob/main/routes/reviewRoutes.ts"
click node_review_controller "https://github.com/lindsey5/zhiyuan-backend/blob/main/controllers/reviewController.ts"
click node_distributor_routes "https://github.com/lindsey5/zhiyuan-backend/blob/main/routes/distributorRoutes.ts"
click node_distributor_controller "https://github.com/lindsey5/zhiyuan-backend/blob/main/controllers/distributorController.ts"
click node_sales_routes "https://github.com/lindsey5/zhiyuan-backend/blob/main/routes/distributorSaleRoutes.ts"
click node_sales_controller "https://github.com/lindsey5/zhiyuan-backend/blob/main/controllers/distributorSaleController.ts"
click node_return_routes "https://github.com/lindsey5/zhiyuan-backend/blob/main/routes/returnRequestRoutes.ts"
click node_return_controller "https://github.com/lindsey5/zhiyuan-backend/blob/main/controllers/returnRequestController.ts"
click node_transfer_service "https://github.com/lindsey5/zhiyuan-backend/blob/main/services/StockTransferService.ts"
click node_mongo "https://github.com/lindsey5/zhiyuan-backend/blob/main/config/db.ts"
click node_redis "https://github.com/lindsey5/zhiyuan-backend/blob/main/config/redis.ts"
click node_cloudinary "https://github.com/lindsey5/zhiyuan-backend/blob/main/utils/cloudinary.ts"
click node_socket "https://github.com/lindsey5/zhiyuan-backend/blob/main/sockets/socket.ts"
click node_notifications "https://github.com/lindsey5/zhiyuan-backend/blob/main/services/NotificationService.ts"
click node_distributor_socket "https://github.com/lindsey5/zhiyuan-backend/blob/main/sockets/namespaces/distributorNotification.namespace.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_app,node_auth_routes,node_auth_controller,node_auth_middleware,node_user_routes,node_user_controller,node_role_routes,node_client toneBlue
class node_product_routes,node_product_controller,node_order_routes,node_order_controller,node_review_routes,node_review_controller toneAmber
class node_distributor_routes,node_distributor_controller,node_sales_routes,node_sales_controller,node_return_routes,node_return_controller,node_transfer_service toneMint
class node_cloudinary,node_socket,node_notifications,node_distributor_socket toneRose
class node_mongo,node_redis toneIndigo
```

## Components

### API and access

- [Express app](https://github.com/lindsey5/zhiyuan-backend/blob/main/app.ts): `app.ts`
- [Auth routes](https://github.com/lindsey5/zhiyuan-backend/blob/main/routes/authRoutes.ts): `routes/authRoutes.ts`
- [Authentication](https://github.com/lindsey5/zhiyuan-backend/blob/main/controllers/authController.ts): `controllers/authController.ts`
- [Auth and permissions](https://github.com/lindsey5/zhiyuan-backend/blob/main/middlewares/authMiddleware.ts): `middlewares/authMiddleware.ts`
- [User routes](https://github.com/lindsey5/zhiyuan-backend/blob/main/routes/userRoutes.ts): `routes/userRoutes.ts`
- [User management](https://github.com/lindsey5/zhiyuan-backend/blob/main/controllers/userController.ts): `controllers/userController.ts`
- [Role routes](https://github.com/lindsey5/zhiyuan-backend/blob/main/routes/roleRoutes.ts): `routes/roleRoutes.ts`

### Catalog and commerce

- [Product routes](https://github.com/lindsey5/zhiyuan-backend/blob/main/routes/productRoutes.ts): `routes/productRoutes.ts`
- [Catalog management](https://github.com/lindsey5/zhiyuan-backend/blob/main/controllers/productController.ts): `controllers/productController.ts`
- [Order routes](https://github.com/lindsey5/zhiyuan-backend/blob/main/routes/orderRoutes.ts): `routes/orderRoutes.ts`
- [Order handling](https://github.com/lindsey5/zhiyuan-backend/blob/main/controllers/orderController.ts): `controllers/orderController.ts`
- [Review routes](https://github.com/lindsey5/zhiyuan-backend/blob/main/routes/reviewRoutes.ts): `routes/reviewRoutes.ts`
- [Review handling](https://github.com/lindsey5/zhiyuan-backend/blob/main/controllers/reviewController.ts): `controllers/reviewController.ts`

### Distributor operations

- [Distributor routes](https://github.com/lindsey5/zhiyuan-backend/blob/main/routes/distributorRoutes.ts): `routes/distributorRoutes.ts`
- [Distributor management](https://github.com/lindsey5/zhiyuan-backend/blob/main/controllers/distributorController.ts): `controllers/distributorController.ts`
- [Sales routes](https://github.com/lindsey5/zhiyuan-backend/blob/main/routes/distributorSaleRoutes.ts): `routes/distributorSaleRoutes.ts`
- [Sales reporting](https://github.com/lindsey5/zhiyuan-backend/blob/main/controllers/distributorSaleController.ts): `controllers/distributorSaleController.ts`
- [Return routes](https://github.com/lindsey5/zhiyuan-backend/blob/main/routes/returnRequestRoutes.ts): `routes/returnRequestRoutes.ts`
- [Return handling](https://github.com/lindsey5/zhiyuan-backend/blob/main/controllers/returnRequestController.ts): `controllers/returnRequestController.ts`
- [Stock transfer logic](https://github.com/lindsey5/zhiyuan-backend/blob/main/services/StockTransferService.ts): `services/StockTransferService.ts`

### Runtime services

- [Cloudinary media](https://github.com/lindsey5/zhiyuan-backend/blob/main/utils/cloudinary.ts): `utils/cloudinary.ts`
- [Socket.IO](https://github.com/lindsey5/zhiyuan-backend/blob/main/sockets/socket.ts): `sockets/socket.ts`
- [Notification service](https://github.com/lindsey5/zhiyuan-backend/blob/main/services/NotificationService.ts): `services/NotificationService.ts`
- [Distributor notifications](https://github.com/lindsey5/zhiyuan-backend/blob/main/sockets/namespaces/distributorNotification.namespace.ts): `sockets/namespaces/distributorNotification.namespace.ts`

### Persistence and cache

- [MongoDB](https://github.com/lindsey5/zhiyuan-backend/blob/main/config/db.ts): `config/db.ts`
- [Redis cache](https://github.com/lindsey5/zhiyuan-backend/blob/main/config/redis.ts): `config/redis.ts`

### Other components

- **API client**

## Connections

- API client → Express app: sends request
- Express app → Auth routes: mounts routes
- Express app → User routes: mounts routes
- Express app → Role routes: mounts routes
- Express app → Product routes: mounts routes
- Express app → Order routes: mounts routes
- Express app → Review routes: mounts routes
- Express app → Distributor routes: mounts routes
- Express app → Sales routes: mounts routes
- Express app → Return routes: mounts routes
- Auth routes → Authentication: dispatches to
- User routes → User management: dispatches to
- Product routes → Catalog management: dispatches to
- Review routes → Review handling: dispatches to
- Distributor routes → Auth and permissions: checks access
- Distributor routes → Distributor management: dispatches to
- Sales routes → Auth and permissions: checks access
- Sales routes → Sales reporting: dispatches to
- Return routes → Return handling: dispatches to
- Review handling → Redis cache: reads and writes cache
- Catalog management → Cloudinary media: uploads media
- Return handling → Distributor notifications: emits notification
- Stock transfer logic → Distributor notifications: emits notification
- Notification service → Socket.IO: emits events
- Stock transfer logic → Redis cache: invalidates cache
- Return handling → MongoDB: persists workflow
- Catalog management → MongoDB: reads and writes catalog
- Review handling → MongoDB: reads and writes reviews