# quuuuj/mall architecture

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

- Interactive diagram: https://gitdiagram.com/quuuuj/mall
- Repository: https://github.com/quuuuj/mall

## Overview

This repository combines a B2C shopping platform (portal, operations console, and Spring REST backend) with a separate multi-agent customer-service API. The documented shopping journey runs from browsing and cart through order creation and simulated payment to administrative fulfillment and receipt. The backend also documents search, dashboard, Excel, and high-concurrency seckill capabilities. The README supplies architecture and workflow evidence; sampled code confirms selected API, search, and customer-service behavior, but most business implementations were not sampled.

Main entry points: [`mall-portal/src/views`](https://github.com/quuuuj/mall/tree/dev/mall-portal/src/views) (Storefront), [`mall-server/src/main/java/com/qiujie/controller/portal`](https://github.com/quuuuj/mall/tree/dev/mall-server/src/main/java/com/qiujie/controller/portal) (Portal endpoints), [`mall-server/src/main/java/com/qiujie/controller/admin`](https://github.com/quuuuj/mall/tree/dev/mall-server/src/main/java/com/qiujie/controller/admin) (Admin endpoints), [`mall-customer/api/main.py`](https://github.com/quuuuj/mall/blob/dev/mall-customer/api/main.py) (Chat API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_portal["Customer portal"]
  node_portal_ui["Storefront"]
  node_portal_api["Portal API clients"]
end

subgraph group_admin["Operations console"]
  node_admin_ui["Admin console"]
  node_admin_api["Admin API clients"]
end

subgraph group_commerce["Commerce backend"]
  node_portal_routes["Portal endpoints"]
  node_admin_routes["Admin endpoints"]
  node_identity["Authentication"]
  node_catalog["Catalog services"]
  node_cart["Cart services"]
  node_orders["Order services"]
  node_product_store[("Product persistence")]
  node_order_store[("Order persistence<br/>[OrderMapper.java]")]
  node_dashboard["Sales dashboard"]
  node_db_models["Commerce entities"]
  node_api_response["API responses"]
end

subgraph group_platform["Search and async"]
  node_search_service["Product search"]
  node_es_index[("Search index")]
  node_sync_job["Index sync<br/>[EsSyncService.java]"]
  node_seckill["Seckill workflow"]
  node_message_queue["RabbitMQ queues"]
  node_seckill_consumer["Seckill consumer"]
  node_timeout_consumer["Order timeout"]
end

subgraph group_support["AI customer support"]
  node_support_client(("Chat client"))
  node_support_api["Chat API<br/>[main.py]"]
  node_supervisor["Agent supervisor<br/>[supervisor.py]"]
  node_agent_modules["Support agents"]
  node_support_memory[("Conversation memory<br/>[long_term.py]")]
  node_mcp_tools["MCP tools<br/>[mcp_server.py]"]
  node_tracing["Agent tracing<br/>[otel_config.py]"]
end

node_shopper(("Shopper"))
node_admin_user(("Administrator"))

node_shopper -->|"uses"| node_portal_ui
node_portal_ui -->|"requests"| node_portal_api
node_portal_api -->|"calls REST"| node_portal_routes
node_portal_routes -.->|"authenticates"| node_identity
node_portal_routes -.->|"serves browsing"| node_catalog
node_portal_routes -.->|"serves cart"| node_cart
node_portal_routes -->|"creates orders"| node_orders
node_shopper -->|"browses products"| node_portal_ui
node_portal_ui -->|"adds to cart"| node_portal_ui
node_portal_ui -->|"confirms order"| node_portal_ui
node_portal_ui -->|"simulates payment"| node_portal_ui
node_admin_user -->|"operates"| node_admin_ui
node_admin_ui -->|"requests"| node_admin_api
node_admin_api -->|"calls REST"| node_admin_routes
node_admin_routes -.->|"manages orders"| node_orders
node_admin_routes -.->|"loads dashboard"| node_dashboard
node_orders -.->|"persists orders"| node_order_store
node_catalog -.->|"reads products"| node_product_store
node_catalog -.->|"uses entities"| node_db_models
node_orders -->|"uses entities"| node_db_models
node_admin_routes -->|"returns DTOs"| node_api_response
node_orders -->|"fulfills order"| node_admin_ui
node_admin_ui -->|"supports receipt"| node_shopper
node_portal_routes -.->|"searches catalog"| node_search_service
node_search_service -->|"queries index"| node_es_index
node_search_service -->|"falls back"| node_product_store
node_sync_job -->|"syncs documents"| node_es_index
node_sync_job -->|"reads products"| node_product_store
node_admin_routes -->|"manages sessions"| node_seckill
node_portal_routes -->|"starts purchase"| node_seckill
node_seckill -->|"publishes messages"| node_message_queue
node_message_queue -->|"dispatches"| node_seckill_consumer
node_seckill_consumer -->|"creates order"| node_order_store
node_message_queue -->|"dispatches expiry"| node_timeout_consumer
node_support_client -.->|"sends chat"| node_support_api
node_support_api -->|"invokes graph"| node_supervisor
node_support_api -->|"stores history"| node_support_memory
node_support_api -->|"dispatches tools"| node_mcp_tools
node_supervisor -.->|"routes requests"| node_agent_modules
node_support_api -->|"initializes tracing"| node_tracing

click node_portal_ui "https://github.com/quuuuj/mall/tree/dev/mall-portal/src/views"
click node_portal_api "https://github.com/quuuuj/mall/tree/dev/mall-portal/src/api"
click node_admin_ui "https://github.com/quuuuj/mall/tree/dev/mall-admin/src/views"
click node_admin_api "https://github.com/quuuuj/mall/tree/dev/mall-admin/src/api"
click node_portal_routes "https://github.com/quuuuj/mall/tree/dev/mall-server/src/main/java/com/qiujie/controller/portal"
click node_admin_routes "https://github.com/quuuuj/mall/tree/dev/mall-server/src/main/java/com/qiujie/controller/admin"
click node_identity "https://github.com/quuuuj/mall/blob/dev/mall-server/src/main/java/com/qiujie/service/impl/AuthServiceImpl.java"
click node_catalog "https://github.com/quuuuj/mall/blob/dev/mall-server/src/main/java/com/qiujie/service/impl/ProductViewServiceImpl.java"
click node_cart "https://github.com/quuuuj/mall/blob/dev/mall-server/src/main/java/com/qiujie/service/impl/CartServiceImpl.java"
click node_orders "https://github.com/quuuuj/mall/blob/dev/mall-server/src/main/java/com/qiujie/service/impl/OrderServiceImpl.java"
click node_product_store "https://github.com/quuuuj/mall/tree/dev/mall-server/src/main/java/com/qiujie/mapper"
click node_order_store "https://github.com/quuuuj/mall/blob/dev/mall-server/src/main/java/com/qiujie/mapper/OrderMapper.java"
click node_dashboard "https://github.com/quuuuj/mall/blob/dev/mall-server/src/main/java/com/qiujie/service/impl/HomeServiceImpl.java"
click node_search_service "https://github.com/quuuuj/mall/blob/dev/mall-server/src/main/java/com/qiujie/service/impl/ProductSearchServiceImpl.java"
click node_es_index "https://github.com/quuuuj/mall/blob/dev/mall-server/src/main/java/com/qiujie/document/ProductDocument.java"
click node_sync_job "https://github.com/quuuuj/mall/blob/dev/mall-server/src/main/java/com/qiujie/service/EsSyncService.java"
click node_seckill "https://github.com/quuuuj/mall/blob/dev/mall-server/src/main/java/com/qiujie/service/impl/SeckillServiceImpl.java"
click node_message_queue "https://github.com/quuuuj/mall/blob/dev/mall-server/src/main/java/com/qiujie/config/RabbitMQConfig.java"
click node_seckill_consumer "https://github.com/quuuuj/mall/blob/dev/mall-server/src/main/java/com/qiujie/mq/SeckillMessageListener.java"
click node_timeout_consumer "https://github.com/quuuuj/mall/blob/dev/mall-server/src/main/java/com/qiujie/mq/OrderTimeoutListener.java"
click node_db_models "https://github.com/quuuuj/mall/tree/dev/mall-server/src/main/java/com/qiujie/entity"
click node_api_response "https://github.com/quuuuj/mall/tree/dev/mall-server/src/main/java/com/qiujie/dto"
click node_support_api "https://github.com/quuuuj/mall/blob/dev/mall-customer/api/main.py"
click node_supervisor "https://github.com/quuuuj/mall/blob/dev/mall-customer/agents/supervisor.py"
click node_agent_modules "https://github.com/quuuuj/mall/tree/dev/mall-customer/agents"
click node_support_memory "https://github.com/quuuuj/mall/blob/dev/mall-customer/memory/long_term.py"
click node_mcp_tools "https://github.com/quuuuj/mall/blob/dev/mall-customer/mcp/mcp_server.py"
click node_tracing "https://github.com/quuuuj/mall/blob/dev/mall-customer/tracing/otel_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_portal_ui,node_portal_api toneBlue
class node_admin_ui,node_admin_api toneAmber
class node_portal_routes,node_admin_routes,node_identity,node_catalog,node_cart,node_orders,node_product_store,node_order_store,node_dashboard,node_db_models,node_api_response toneMint
class node_search_service,node_es_index,node_sync_job,node_seckill,node_message_queue,node_seckill_consumer,node_timeout_consumer toneRose
class node_support_client,node_support_api,node_supervisor,node_agent_modules,node_support_memory,node_mcp_tools,node_tracing,node_shopper,node_admin_user toneIndigo
```

## Components

### Customer portal

- [Storefront](https://github.com/quuuuj/mall/tree/dev/mall-portal/src/views): `mall-portal/src/views`
- [Portal API clients](https://github.com/quuuuj/mall/tree/dev/mall-portal/src/api): `mall-portal/src/api`

### Operations console

- [Admin console](https://github.com/quuuuj/mall/tree/dev/mall-admin/src/views): `mall-admin/src/views`
- [Admin API clients](https://github.com/quuuuj/mall/tree/dev/mall-admin/src/api): `mall-admin/src/api`

### Commerce backend

- [Portal endpoints](https://github.com/quuuuj/mall/tree/dev/mall-server/src/main/java/com/qiujie/controller/portal): `mall-server/src/main/java/com/qiujie/controller/portal`
- [Admin endpoints](https://github.com/quuuuj/mall/tree/dev/mall-server/src/main/java/com/qiujie/controller/admin): `mall-server/src/main/java/com/qiujie/controller/admin`
- [Authentication](https://github.com/quuuuj/mall/blob/dev/mall-server/src/main/java/com/qiujie/service/impl/AuthServiceImpl.java): `mall-server/src/main/java/com/qiujie/service/impl/AuthServiceImpl.java`
- [Catalog services](https://github.com/quuuuj/mall/blob/dev/mall-server/src/main/java/com/qiujie/service/impl/ProductViewServiceImpl.java): `mall-server/src/main/java/com/qiujie/service/impl/ProductViewServiceImpl.java`
- [Cart services](https://github.com/quuuuj/mall/blob/dev/mall-server/src/main/java/com/qiujie/service/impl/CartServiceImpl.java): `mall-server/src/main/java/com/qiujie/service/impl/CartServiceImpl.java`
- [Order services](https://github.com/quuuuj/mall/blob/dev/mall-server/src/main/java/com/qiujie/service/impl/OrderServiceImpl.java): `mall-server/src/main/java/com/qiujie/service/impl/OrderServiceImpl.java`
- [Product persistence](https://github.com/quuuuj/mall/tree/dev/mall-server/src/main/java/com/qiujie/mapper): `mall-server/src/main/java/com/qiujie/mapper`
- [Order persistence](https://github.com/quuuuj/mall/blob/dev/mall-server/src/main/java/com/qiujie/mapper/OrderMapper.java): `mall-server/src/main/java/com/qiujie/mapper/OrderMapper.java`
- [Sales dashboard](https://github.com/quuuuj/mall/blob/dev/mall-server/src/main/java/com/qiujie/service/impl/HomeServiceImpl.java): `mall-server/src/main/java/com/qiujie/service/impl/HomeServiceImpl.java`
- [Commerce entities](https://github.com/quuuuj/mall/tree/dev/mall-server/src/main/java/com/qiujie/entity): `mall-server/src/main/java/com/qiujie/entity`
- [API responses](https://github.com/quuuuj/mall/tree/dev/mall-server/src/main/java/com/qiujie/dto): `mall-server/src/main/java/com/qiujie/dto`

### Search and async

- [Product search](https://github.com/quuuuj/mall/blob/dev/mall-server/src/main/java/com/qiujie/service/impl/ProductSearchServiceImpl.java): `mall-server/src/main/java/com/qiujie/service/impl/ProductSearchServiceImpl.java`
- [Search index](https://github.com/quuuuj/mall/blob/dev/mall-server/src/main/java/com/qiujie/document/ProductDocument.java): `mall-server/src/main/java/com/qiujie/document/ProductDocument.java`
- [Index sync](https://github.com/quuuuj/mall/blob/dev/mall-server/src/main/java/com/qiujie/service/EsSyncService.java): `mall-server/src/main/java/com/qiujie/service/EsSyncService.java`
- [Seckill workflow](https://github.com/quuuuj/mall/blob/dev/mall-server/src/main/java/com/qiujie/service/impl/SeckillServiceImpl.java): `mall-server/src/main/java/com/qiujie/service/impl/SeckillServiceImpl.java`
- [RabbitMQ queues](https://github.com/quuuuj/mall/blob/dev/mall-server/src/main/java/com/qiujie/config/RabbitMQConfig.java): `mall-server/src/main/java/com/qiujie/config/RabbitMQConfig.java`
- [Seckill consumer](https://github.com/quuuuj/mall/blob/dev/mall-server/src/main/java/com/qiujie/mq/SeckillMessageListener.java): `mall-server/src/main/java/com/qiujie/mq/SeckillMessageListener.java`
- [Order timeout](https://github.com/quuuuj/mall/blob/dev/mall-server/src/main/java/com/qiujie/mq/OrderTimeoutListener.java): `mall-server/src/main/java/com/qiujie/mq/OrderTimeoutListener.java`

### AI customer support

- **Chat client**
- [Chat API](https://github.com/quuuuj/mall/blob/dev/mall-customer/api/main.py): `mall-customer/api/main.py`
- [Agent supervisor](https://github.com/quuuuj/mall/blob/dev/mall-customer/agents/supervisor.py): `mall-customer/agents/supervisor.py`
- [Support agents](https://github.com/quuuuj/mall/tree/dev/mall-customer/agents): `mall-customer/agents`
- [Conversation memory](https://github.com/quuuuj/mall/blob/dev/mall-customer/memory/long_term.py): `mall-customer/memory/long_term.py`
- [MCP tools](https://github.com/quuuuj/mall/blob/dev/mall-customer/mcp/mcp_server.py): `mall-customer/mcp/mcp_server.py`
- [Agent tracing](https://github.com/quuuuj/mall/blob/dev/mall-customer/tracing/otel_config.py): `mall-customer/tracing/otel_config.py`

### Other components

- **Shopper**
- **Administrator**

## Connections

- Shopper → Storefront: uses
- Storefront → Portal API clients: requests (evidence: `mall-portal/src/views/Search.vue`)
- Portal API clients → Portal endpoints: calls REST
- Portal endpoints → Authentication: authenticates
- Portal endpoints → Catalog services: serves browsing
- Portal endpoints → Cart services: serves cart
- Portal endpoints → Order services: creates orders (evidence: `mall-server/src/main/java/com/qiujie/controller/portal/OrderController.java`)
- Shopper → Storefront: browses products
- Storefront → Storefront: adds to cart
- Storefront → Storefront: confirms order
- Storefront → Storefront: simulates payment
- Administrator → Admin console: operates
- Admin console → Admin API clients: requests
- Admin API clients → Admin endpoints: calls REST
- Admin endpoints → Order services: manages orders
- Admin endpoints → Sales dashboard: loads dashboard
- Order services → Order persistence: persists orders
- Catalog services → Product persistence: reads products
- Catalog services → Commerce entities: uses entities
- Order services → Commerce entities: uses entities
- Admin endpoints → API responses: returns DTOs (evidence: `mall-server/src/main/java/com/qiujie/controller/admin/UserController.java`)
- Order services → Admin console: fulfills order
- Admin console → Shopper: supports receipt
- Portal endpoints → Product search: searches catalog
- Product search → Search index: queries index (evidence: `mall-server/src/main/java/com/qiujie/service/impl/ProductSearchServiceImpl.java`)
- Product search → Product persistence: falls back (evidence: `mall-server/src/main/java/com/qiujie/service/impl/ProductSearchServiceImpl.java`)
- Index sync → Search index: syncs documents (evidence: `mall-server/src/main/java/com/qiujie/service/EsSyncService.java`)
- Index sync → Product persistence: reads products (evidence: `mall-server/src/main/java/com/qiujie/service/EsSyncService.java`)
- Admin endpoints → Seckill workflow: manages sessions
- Portal endpoints → Seckill workflow: starts purchase
- Seckill workflow → RabbitMQ queues: publishes messages
- RabbitMQ queues → Seckill consumer: dispatches
- Seckill consumer → Order persistence: creates order
- RabbitMQ queues → Order timeout: dispatches expiry
- Chat client → Chat API: sends chat
- Chat API → Agent supervisor: invokes graph (evidence: `mall-customer/api/main.py`)
- Chat API → Conversation memory: stores history (evidence: `mall-customer/api/main.py`)
- Chat API → MCP tools: dispatches tools (evidence: `mall-customer/api/main.py`)
- Agent supervisor → Support agents: routes requests
- Chat API → Agent tracing: initializes tracing (evidence: `mall-customer/api/main.py`)
