# lbbz/hotshop architecture

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

- Interactive diagram: https://gitdiagram.com/lbbz/hotshop
- Repository: https://github.com/lbbz/hotshop

## Overview

HotShop is a modular commerce system with a React user/admin experience, Java transaction and operations services, asynchronous workers, and a Python shopping Agent. The main journey runs from browsing or purchase intent through regular ordering or flash-sale reservation, payment, and progress updates; Agent-generated purchase drafts require a separate user confirmation. The README also documents operations, audit, reconciliation, and knowledge retrieval. The graph follows those documented responsibilities; sampled source confirms selected order, confirmation, callback, audit-query, and reservation-processing behavior, while unsampled links rely on README descriptions.

Main entry points: [`web/src`](https://github.com/lbbz/hotshop/tree/master/web/src) (Web application), [`portal/src/main/java/com/real/portal`](https://github.com/lbbz/hotshop/tree/master/portal/src/main/java/com/real/portal) (Portal API), [`agent/src/hotshop_agent`](https://github.com/lbbz/hotshop/tree/master/agent/src/hotshop_agent) (Agent service), [`admin/src/main/java/com/real/admin`](https://github.com/lbbz/hotshop/tree/master/admin/src/main/java/com/real/admin) (Admin API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Web experience"]
  node_webapp["Web application"]
  node_catalog_ui["Catalog and activities"]
  node_transactions_ui["Purchase and progress"]
  node_agent_ui["Agent workspaces"]
  node_admin_ui["Admin pages"]
end

subgraph group_commerce["Commerce APIs"]
  node_portal["Portal API"]
  node_orders["Order lifecycle"]
  node_order_state["Order state and stock"]
  node_flash_sale["Flash-sale reservations"]
  node_purchase_confirm["Purchase confirmation"]
  node_payment["Mock payment callbacks"]
  node_timeline["Transaction timeline"]
end

subgraph group_async["Async processing"]
  node_task["Task workers"]
  node_reservation_worker["Reservation processing"]
  node_timeout["Timeout and recovery"]
  node_outbox["Outbox publishing"]
end

subgraph group_assistant["Agent capabilities"]
  node_agent["Agent service"]
  node_rag["Knowledge retrieval<br/>[rag.py]"]
  node_model["Model providers"]
end

subgraph group_operations["Operations and identity"]
  node_admin_api["Admin API"]
  node_admin_ops["Operations and audit"]
  node_admin_agent["Admin Agent tools"]
  node_security["Identity and delegation"]
end

node_shopper(("Shopper / admin"))
node_mysql[("MySQL")]
node_redis[("Redis cache and streams")]
node_rabbit["RabbitMQ"]
node_qdrant[("Qdrant")]
node_llm["Model service"]

node_shopper -->|"uses"| node_webapp
node_webapp -->|"calls APIs"| node_portal
node_webapp -->|"calls APIs"| node_admin_api
node_webapp -->|"streams questions"| node_agent
node_webapp -->|"renders"| node_catalog_ui
node_webapp -->|"renders"| node_transactions_ui
node_webapp -->|"renders"| node_agent_ui
node_webapp -->|"renders"| node_admin_ui
node_catalog_ui -->|"queries catalog"| node_portal
node_transactions_ui -->|"submits purchases"| node_portal
node_portal -->|"creates orders"| node_orders
node_orders -->|"applies transitions"| node_order_state
node_order_state -->|"writes orders and outbox"| node_mysql
node_portal -->|"accepts reservations"| node_flash_sale
node_flash_sale -->|"reserves stock and emits"| node_redis
node_redis -->|"delivers stream events"| node_reservation_worker
node_reservation_worker -->|"creates orders"| node_mysql
node_portal -->|"accepts callbacks"| node_payment
node_payment -->|"records payment and outbox"| node_mysql
node_task -->|"processes expiries"| node_timeout
node_timeout -->|"closes and compensates"| node_mysql
node_task -->|"publishes events"| node_outbox
node_outbox -->|"publishes messages"| node_rabbit
node_rabbit -->|"delivers messages"| node_task
node_portal -->|"serves progress"| node_timeline
node_timeline -->|"reads reservation status"| node_redis
node_agent -->|"calls user tools"| node_portal
node_agent -->|"calls admin tools"| node_admin_api
node_agent -->|"routes knowledge queries"| node_rag
node_rag -->|"searches evidence"| node_qdrant
node_agent -->|"orchestrates responses"| node_model
node_model -->|"generates answers"| node_llm
node_agent -->|"stores session state"| node_redis
node_agent -->|"creates purchase drafts"| node_purchase_confirm
node_webapp -->|"confirms purchase"| node_purchase_confirm
node_purchase_confirm -->|"consumes token and creates order"| node_mysql
node_admin_api -->|"serves operations"| node_admin_ops
node_admin_ops -->|"queries operations and audit"| node_mysql
node_admin_api -->|"serves admin tools"| node_admin_agent
node_admin_agent -->|"reads operational facts"| node_mysql
node_portal -->|"validates identity"| node_security
node_admin_api -->|"validates identity"| node_security
node_security -->|"stores refresh sessions"| node_mysql

click node_webapp "https://github.com/lbbz/hotshop/tree/master/web/src"
click node_catalog_ui "https://github.com/lbbz/hotshop/tree/master/web/src/features/catalog"
click node_transactions_ui "https://github.com/lbbz/hotshop/tree/master/web/src/features/transactions"
click node_agent_ui "https://github.com/lbbz/hotshop/tree/master/web/src/features/agent"
click node_admin_ui "https://github.com/lbbz/hotshop/tree/master/web/src/features/admin"
click node_portal "https://github.com/lbbz/hotshop/tree/master/portal/src/main/java/com/real/portal"
click node_orders "https://github.com/lbbz/hotshop/tree/master/domain/src/main/java/com/real/domain/service"
click node_order_state "https://github.com/lbbz/hotshop/blob/master/domain/src/main/java/com/real/domain/service/advance/OrderStateService.java"
click node_flash_sale "https://github.com/lbbz/hotshop/tree/master/domain/src/main/java/com/real/domain/service/seckill"
click node_purchase_confirm "https://github.com/lbbz/hotshop/blob/master/domain/src/main/java/com/real/domain/agenttools/PurchaseConfirmationService.java"
click node_payment "https://github.com/lbbz/hotshop/blob/master/portal/src/main/java/com/real/portal/payment/MockPaymentCallbackService.java"
click node_timeline "https://github.com/lbbz/hotshop/blob/master/portal/src/main/java/com/real/portal/timeline/TransactionTimelineService.java"
click node_task "https://github.com/lbbz/hotshop/tree/master/task/src/main/java/com/real/task"
click node_reservation_worker "https://github.com/lbbz/hotshop/blob/master/task/src/main/java/com/real/task/seckill/SeckillProcessingService.java"
click node_timeout "https://github.com/lbbz/hotshop/blob/master/task/src/main/java/com/real/task/timeoutOrderTask/OrderTimeoutService.java"
click node_outbox "https://github.com/lbbz/hotshop/tree/master/task/src/main/java/com/real/task/outbox"
click node_agent "https://github.com/lbbz/hotshop/tree/master/agent/src/hotshop_agent"
click node_rag "https://github.com/lbbz/hotshop/blob/master/agent/src/hotshop_agent/rag.py"
click node_model "https://github.com/lbbz/hotshop/tree/master/agent/src/hotshop_agent/providers"
click node_admin_api "https://github.com/lbbz/hotshop/tree/master/admin/src/main/java/com/real/admin"
click node_admin_ops "https://github.com/lbbz/hotshop/blob/master/admin/src/main/java/com/real/admin/service/AdminOperationsService.java"
click node_admin_agent "https://github.com/lbbz/hotshop/blob/master/admin/src/main/java/com/real/admin/agenttools/AdminAgentToolService.java"
click node_security "https://github.com/lbbz/hotshop/tree/master/security/src/main/java/com/real/security"

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_webapp,node_catalog_ui,node_transactions_ui,node_agent_ui,node_admin_ui toneBlue
class node_portal,node_orders,node_order_state,node_flash_sale,node_purchase_confirm,node_payment,node_timeline,node_mysql,node_redis,node_qdrant toneAmber
class node_task,node_reservation_worker,node_timeout,node_outbox toneMint
class node_agent,node_rag,node_model toneRose
class node_admin_api,node_admin_ops,node_admin_agent,node_security,node_shopper,node_rabbit,node_llm toneIndigo
```

## Components

### Web experience

- [Web application](https://github.com/lbbz/hotshop/tree/master/web/src): `web/src`
- [Catalog and activities](https://github.com/lbbz/hotshop/tree/master/web/src/features/catalog): `web/src/features/catalog`
- [Purchase and progress](https://github.com/lbbz/hotshop/tree/master/web/src/features/transactions): `web/src/features/transactions`
- [Agent workspaces](https://github.com/lbbz/hotshop/tree/master/web/src/features/agent): `web/src/features/agent`
- [Admin pages](https://github.com/lbbz/hotshop/tree/master/web/src/features/admin): `web/src/features/admin`

### Commerce APIs

- [Portal API](https://github.com/lbbz/hotshop/tree/master/portal/src/main/java/com/real/portal): `portal/src/main/java/com/real/portal`
- [Order lifecycle](https://github.com/lbbz/hotshop/tree/master/domain/src/main/java/com/real/domain/service): `domain/src/main/java/com/real/domain/service`
- [Order state and stock](https://github.com/lbbz/hotshop/blob/master/domain/src/main/java/com/real/domain/service/advance/OrderStateService.java): `domain/src/main/java/com/real/domain/service/advance/OrderStateService.java`
- [Flash-sale reservations](https://github.com/lbbz/hotshop/tree/master/domain/src/main/java/com/real/domain/service/seckill): `domain/src/main/java/com/real/domain/service/seckill`
- [Purchase confirmation](https://github.com/lbbz/hotshop/blob/master/domain/src/main/java/com/real/domain/agenttools/PurchaseConfirmationService.java): `domain/src/main/java/com/real/domain/agenttools/PurchaseConfirmationService.java`
- [Mock payment callbacks](https://github.com/lbbz/hotshop/blob/master/portal/src/main/java/com/real/portal/payment/MockPaymentCallbackService.java): `portal/src/main/java/com/real/portal/payment/MockPaymentCallbackService.java`
- [Transaction timeline](https://github.com/lbbz/hotshop/blob/master/portal/src/main/java/com/real/portal/timeline/TransactionTimelineService.java): `portal/src/main/java/com/real/portal/timeline/TransactionTimelineService.java`

### Async processing

- [Task workers](https://github.com/lbbz/hotshop/tree/master/task/src/main/java/com/real/task): `task/src/main/java/com/real/task`
- [Reservation processing](https://github.com/lbbz/hotshop/blob/master/task/src/main/java/com/real/task/seckill/SeckillProcessingService.java): `task/src/main/java/com/real/task/seckill/SeckillProcessingService.java`
- [Timeout and recovery](https://github.com/lbbz/hotshop/blob/master/task/src/main/java/com/real/task/timeoutOrderTask/OrderTimeoutService.java): `task/src/main/java/com/real/task/timeoutOrderTask/OrderTimeoutService.java`
- [Outbox publishing](https://github.com/lbbz/hotshop/tree/master/task/src/main/java/com/real/task/outbox): `task/src/main/java/com/real/task/outbox`

### Agent capabilities

- [Agent service](https://github.com/lbbz/hotshop/tree/master/agent/src/hotshop_agent): `agent/src/hotshop_agent`
- [Knowledge retrieval](https://github.com/lbbz/hotshop/blob/master/agent/src/hotshop_agent/rag.py): `agent/src/hotshop_agent/rag.py`
- [Model providers](https://github.com/lbbz/hotshop/tree/master/agent/src/hotshop_agent/providers): `agent/src/hotshop_agent/providers`

### Operations and identity

- [Admin API](https://github.com/lbbz/hotshop/tree/master/admin/src/main/java/com/real/admin): `admin/src/main/java/com/real/admin`
- [Operations and audit](https://github.com/lbbz/hotshop/blob/master/admin/src/main/java/com/real/admin/service/AdminOperationsService.java): `admin/src/main/java/com/real/admin/service/AdminOperationsService.java`
- [Admin Agent tools](https://github.com/lbbz/hotshop/blob/master/admin/src/main/java/com/real/admin/agenttools/AdminAgentToolService.java): `admin/src/main/java/com/real/admin/agenttools/AdminAgentToolService.java`
- [Identity and delegation](https://github.com/lbbz/hotshop/tree/master/security/src/main/java/com/real/security): `security/src/main/java/com/real/security`

### Other components

- **Shopper / admin**
- **MySQL**
- **Redis cache and streams**
- **RabbitMQ**
- **Qdrant**
- **Model service**

## Connections

- Shopper / admin → Web application: uses (evidence: `README.md`)
- Web application → Portal API: calls APIs (evidence: `README.md`)
- Web application → Admin API: calls APIs (evidence: `README.md`)
- Web application → Agent service: streams questions (evidence: `README.md`)
- Web application → Catalog and activities: renders (evidence: `README.md`)
- Web application → Purchase and progress: renders (evidence: `README.md`)
- Web application → Agent workspaces: renders (evidence: `README.md`)
- Web application → Admin pages: renders (evidence: `README.md`)
- Catalog and activities → Portal API: queries catalog (evidence: `README.md`)
- Purchase and progress → Portal API: submits purchases (evidence: `README.md`)
- Portal API → Order lifecycle: creates orders (evidence: `README.md`)
- Order lifecycle → Order state and stock: applies transitions (evidence: `domain/src/main/java/com/real/domain/service/advance/OrderStateService.java`)
- Order state and stock → MySQL: writes orders and outbox (evidence: `domain/src/main/java/com/real/domain/service/advance/OrderStateService.java`)
- Portal API → Flash-sale reservations: accepts reservations (evidence: `README.md`)
- Flash-sale reservations → Redis cache and streams: reserves stock and emits (evidence: `README.md`)
- Redis cache and streams → Reservation processing: delivers stream events (evidence: `README.md`)
- Reservation processing → MySQL: creates orders (evidence: `task/src/main/java/com/real/task/seckill/SeckillProcessingService.java`)
- Portal API → Mock payment callbacks: accepts callbacks (evidence: `README.md`)
- Mock payment callbacks → MySQL: records payment and outbox (evidence: `portal/src/main/java/com/real/portal/payment/MockPaymentCallbackService.java`)
- Task workers → Timeout and recovery: processes expiries (evidence: `README.md`)
- Timeout and recovery → MySQL: closes and compensates (evidence: `README.md`)
- Task workers → Outbox publishing: publishes events (evidence: `README.md`)
- Outbox publishing → RabbitMQ: publishes messages (evidence: `README.md`)
- RabbitMQ → Task workers: delivers messages (evidence: `README.md`)
- Portal API → Transaction timeline: serves progress (evidence: `portal/src/main/java/com/real/portal/sse/TransactionEventStreamService.java`)
- Transaction timeline → Redis cache and streams: reads reservation status (evidence: `portal/src/main/java/com/real/portal/timeline/TransactionTimelineService.java`)
- Agent service → Portal API: calls user tools (evidence: `README.md`)
- Agent service → Admin API: calls admin tools (evidence: `README.md`)
- Agent service → Knowledge retrieval: routes knowledge queries (evidence: `README.md`)
- Knowledge retrieval → Qdrant: searches evidence (evidence: `README.md`)
- Agent service → Model providers: orchestrates responses (evidence: `README.md`)
- Model providers → Model service: generates answers (evidence: `README.md`)
- Agent service → Redis cache and streams: stores session state (evidence: `README.md`)
- Agent service → Purchase confirmation: creates purchase drafts (evidence: `README.md`)
- Web application → Purchase confirmation: confirms purchase (evidence: `README.md`)
- Purchase confirmation → MySQL: consumes token and creates order (evidence: `domain/src/main/java/com/real/domain/agenttools/PurchaseConfirmationService.java`)
- Admin API → Operations and audit: serves operations (evidence: `admin/src/main/java/com/real/admin/service/AdminOperationsService.java`)
- Operations and audit → MySQL: queries operations and audit
- Admin API → Admin Agent tools: serves admin tools (evidence: `admin/src/main/java/com/real/admin/agenttools/AdminAgentToolService.java`)
- Admin Agent tools → MySQL: reads operational facts (evidence: `README.md`)
- Portal API → Identity and delegation: validates identity (evidence: `README.md`)
- Admin API → Identity and delegation: validates identity (evidence: `README.md`)
- Identity and delegation → MySQL: stores refresh sessions (evidence: `security/src/main/java/com/real/security/service/RefreshSessionService.java`)
