# adamwhite625/bach-hoa-project architecture

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

- Interactive diagram: https://gitdiagram.com/adamwhite625/bach-hoa-project
- Repository: https://github.com/adamwhite625/bach-hoa-project

## Overview

#### Purpose and Deployable Units
Bach Hoa is a multi-client e-commerce platform: a Node.js commerce API, React admin portal, native Android shopper app, and Python RAG chatbot. Main service entry points are `backend/server.js`, `admin-web/src/main.jsx`, `android/app/src/main/java/com/example/frontend2/ui/main/MainActivity.java`, and `chatbotRAG/main.py`.

#### Commerce API Core
The backend is the system-of-record boundary, exposing REST routes from `backend/routes/` and delegating request logic to `backend/controllers/`. `backend/server.js` initializes the service; domain persistence is represented by MongoDB-oriented models such as `backend/models/productModel.js`, `backend/models/orderModel.js`, and `backend/models/userModel.js`.

Primary flow: web/mobile clients → route → authentication/upload middleware where applicable → controller → model/database → JSON response.

#### Identity, Administration, and Customer State
JWT-based authorization is centralized in `backend/middlewares/authMiddleware.js`; authentication and password workflows reside in `backend/controllers/authController.js` and `backend/controllers/passwordController.js`. The admin React application protects privileged UI through `admin-web/src/components/common/AdminGuard.jsx`, with auth state exposed through `admin-web/src/hooks/useAuth.js`.

Admin operations cover products, categories, discounts, orders, and users via pages including `admin-web/src/pages/Admin/ProductManager.jsx`, `admin-web/src/pages/Admin/OrderManager.jsx`, and `admin-web/src/pages/Admin/UserManager.jsx`.

#### Shopping and Order Lifecycle
Customer shopping flow spans product browsing, cart changes, voucher application, checkout/payment, and post-order status. Backend ownership is separated into `backend/controllers/productController.js`, `backend/controllers/cartController.js`, `backend/controllers/discountController.js`, `backend/controllers/orderController.js`, and `backend/controllers/paymentController.js`.

The Android app presents this flow through `android/app/src/main/java/com/example/frontend2/ui/fragment/HomeFragment.java`, `android/app/src/main/java/com/example/frontend2/ui/fragment/CartFragment.java`, and `android/app/src/main/java/com/example/frontend2/ui/main/OrderDetailsActivity.java`. Shared cart UI state is managed by `android/app/src/main/java/com/example/frontend2/ui/main/CartSharedViewModel.java`.

#### Android Client Boundary
The Android app is a Java/Gradle native client using Retrofit-style API access. `android/app/src/main/java/com/example/frontend2/data/remote/ApiClient.java`, `android/app/src/main/java/com/example/frontend2/data/remote/ApiService.java`, and `android/app/src/main/java/com/example/frontend2/data/model/` define the remote boundary and API DTOs. `android/app/src/main/java/com/example/frontend2/utils/SharedPrefManager.java` provides local persisted client state, likely including session information.

#### AI Chatbot Pipeline
`chatbotRAG` is an independent FastAPI service, not part of the Node API tree. `chatbotRAG/build_db.py` ingests markdown knowledge from `chatbotRAG/data/` into the committed Chroma vector store at `chatbotRAG/chroma_db/`. `chatbotRAG/main.py` exposes the chat API, while `chatbotRAG/chatbot_core.py` implements retrieval/generation using OpenAI credentials. The Android chat UI models include `android/app/src/main/java/com/example/frontend2/data/model/ChatMessage.java` and `ChatMessageRequest.java`.

#### Infrastructure and External Dependencies
MongoDB is the primary database, configurable through `backend/config/db.js`. Cloudinary handles image uploads via `backend/config/cloudinary.js` and upload middleware; Gmail-backed email is encapsulated by `backend/services/emailService.js`. The chatbot requires OpenAI and Chroma. Docker deployment artifacts exist at `Dockerfile`, `backend/Dockerfile`, `chatbotRAG/Dockerfile`, and `docker-compose.yml`; CI/CD is defined in `.github/workflows/deploy.yml`.

Main entry points: [`backend/controllers/orderController.js`](https://github.com/adamwhite625/bach-hoa-project/blob/main/backend/controllers/orderController.js) (Commerce controllers), [`admin-web/src/components/common/AdminGuard.jsx`](https://github.com/adamwhite625/bach-hoa-project/blob/main/admin-web/src/components/common/AdminGuard.jsx) (Admin access guard), [`chatbotRAG/chatbot_core.py`](https://github.com/adamwhite625/bach-hoa-project/blob/main/chatbotRAG/chatbot_core.py) (Retrieval & generation), [`backend/server.js`](https://github.com/adamwhite625/bach-hoa-project/blob/main/backend/server.js) (Commerce API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["Client apps"]
  node_admin["Admin portal<br/>React app<br/>[main.jsx]"]
  node_admin_guard["Admin access guard<br/>route guard<br/>[AdminGuard.jsx]"]
  node_admin_auth["Admin auth state<br/>React hook<br/>[useAuth.js]"]
  node_admin_operations["Admin operations<br/>management pages<br/>[ProductManager.jsx]"]
  node_android["Android shopper app<br/>Java/Gradle app<br/>[MainActivity.java]"]
  node_shopping_ui["Shopping &amp; orders UI<br/>Android screens<br/>[HomeFragment.java]"]
  node_android_api["Commerce API client<br/>Retrofit boundary<br/>[ApiClient.java]"]
  node_chat_ui["Chat UI messages<br/>Android DTOs<br/>[ChatMessage.java]"]
end

subgraph group_commerce["Commerce API"]
  node_api["Commerce API<br/>Node.js REST service<br/>[server.js]"]
  node_routes["REST routes<br/>route layer"]
  node_auth["JWT authorization<br/>middleware<br/>[authMiddleware.js]"]
  node_controllers["Commerce controllers<br/>domain controllers<br/>[orderController.js]"]
  node_models["Commerce models<br/>MongoDB models<br/>[orderModel.js]"]
  node_uploads["Image upload integration<br/>upload middleware<br/>[cloudinary.js]"]
  node_email["Email service<br/>Gmail integration<br/>[emailService.js]"]
end

subgraph group_rag["RAG chatbot"]
  node_chat_api["Chat API<br/>FastAPI service<br/>[main.py]"]
  node_rag_core["Retrieval &amp; generation<br/>RAG core<br/>[chatbot_core.py]"]
  node_knowledge_ingest["Knowledge ingestion<br/>vector-store builder<br/>[build_db.py]"]
  node_chroma[("Chroma vector store<br/>vector database")]
end

subgraph group_external["Data &amp; external services"]
  node_mongodb[("MongoDB<br/>primary database<br/>[db.js]")]
  node_cloudinary["Cloudinary<br/>image storage"]
  node_gmail["Gmail<br/>email provider"]
  node_openai["OpenAI<br/>generation provider"]
end

node_admin -->|"protects UI"| node_admin_guard
node_admin_guard -->|"reads session"| node_admin_auth
node_admin_guard -->|"permits"| node_admin_operations
node_admin_operations -->|"REST requests"| node_api
node_android -->|"hosts"| node_shopping_ui
node_shopping_ui -->|"uses"| node_android_api
node_android_api -->|"REST requests"| node_api
node_android -->|"hosts"| node_chat_ui
node_chat_ui -->|"chat requests"| node_chat_api
node_api -->|"mounts"| node_routes
node_routes -->|"authorizes protected routes"| node_auth
node_routes -->|"delegates"| node_controllers
node_controllers -->|"reads and writes"| node_models
node_models -->|"persists"| node_mongodb
node_controllers -->|"handles uploads"| node_uploads
node_uploads -->|"stores images"| node_cloudinary
node_controllers -->|"sends notifications"| node_email
node_email -->|"delivers through"| node_gmail
node_chat_api -->|"serves queries"| node_rag_core
node_rag_core -->|"retrieves context"| node_chroma
node_rag_core -->|"generates response"| node_openai
node_knowledge_ingest -->|"builds index"| node_chroma

click node_admin "https://github.com/adamwhite625/bach-hoa-project/blob/main/admin-web/src/main.jsx"
click node_admin_guard "https://github.com/adamwhite625/bach-hoa-project/blob/main/admin-web/src/components/common/AdminGuard.jsx"
click node_admin_auth "https://github.com/adamwhite625/bach-hoa-project/blob/main/admin-web/src/hooks/useAuth.js"
click node_admin_operations "https://github.com/adamwhite625/bach-hoa-project/blob/main/admin-web/src/pages/Admin/ProductManager.jsx"
click node_android "https://github.com/adamwhite625/bach-hoa-project/blob/main/android/app/src/main/java/com/example/frontend2/ui/main/MainActivity.java"
click node_shopping_ui "https://github.com/adamwhite625/bach-hoa-project/blob/main/android/app/src/main/java/com/example/frontend2/ui/fragment/HomeFragment.java"
click node_android_api "https://github.com/adamwhite625/bach-hoa-project/blob/main/android/app/src/main/java/com/example/frontend2/data/remote/ApiClient.java"
click node_chat_ui "https://github.com/adamwhite625/bach-hoa-project/blob/main/android/app/src/main/java/com/example/frontend2/data/model/ChatMessage.java"
click node_api "https://github.com/adamwhite625/bach-hoa-project/blob/main/backend/server.js"
click node_auth "https://github.com/adamwhite625/bach-hoa-project/blob/main/backend/middlewares/authMiddleware.js"
click node_controllers "https://github.com/adamwhite625/bach-hoa-project/blob/main/backend/controllers/orderController.js"
click node_models "https://github.com/adamwhite625/bach-hoa-project/blob/main/backend/models/orderModel.js"
click node_uploads "https://github.com/adamwhite625/bach-hoa-project/blob/main/backend/config/cloudinary.js"
click node_email "https://github.com/adamwhite625/bach-hoa-project/blob/main/backend/services/emailService.js"
click node_chat_api "https://github.com/adamwhite625/bach-hoa-project/blob/main/chatbotRAG/main.py"
click node_rag_core "https://github.com/adamwhite625/bach-hoa-project/blob/main/chatbotRAG/chatbot_core.py"
click node_knowledge_ingest "https://github.com/adamwhite625/bach-hoa-project/blob/main/chatbotRAG/build_db.py"
click node_mongodb "https://github.com/adamwhite625/bach-hoa-project/blob/main/backend/config/db.js"

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_admin,node_admin_guard,node_admin_auth,node_admin_operations,node_android,node_shopping_ui,node_android_api,node_chat_ui toneBlue
class node_api,node_routes,node_auth,node_controllers,node_models,node_uploads,node_email toneAmber
class node_chat_api,node_rag_core,node_knowledge_ingest,node_chroma toneMint
class node_mongodb,node_cloudinary,node_gmail,node_openai toneRose
```

## Components

### Client apps

- [Admin portal](https://github.com/adamwhite625/bach-hoa-project/blob/main/admin-web/src/main.jsx): React app · `admin-web/src/main.jsx`
- [Admin access guard](https://github.com/adamwhite625/bach-hoa-project/blob/main/admin-web/src/components/common/AdminGuard.jsx): route guard · Protects privileged administration UI. · `admin-web/src/components/common/AdminGuard.jsx`
- [Admin auth state](https://github.com/adamwhite625/bach-hoa-project/blob/main/admin-web/src/hooks/useAuth.js): React hook · `admin-web/src/hooks/useAuth.js`
- [Admin operations](https://github.com/adamwhite625/bach-hoa-project/blob/main/admin-web/src/pages/Admin/ProductManager.jsx): management pages · Manages products, orders, users, categories, and discounts. · `admin-web/src/pages/Admin/ProductManager.jsx`
- [Android shopper app](https://github.com/adamwhite625/bach-hoa-project/blob/main/android/app/src/main/java/com/example/frontend2/ui/main/MainActivity.java): Java/Gradle app · `android/app/src/main/java/com/example/frontend2/ui/main/MainActivity.java`
- [Shopping & orders UI](https://github.com/adamwhite625/bach-hoa-project/blob/main/android/app/src/main/java/com/example/frontend2/ui/fragment/HomeFragment.java): Android screens · Supports browsing, cart, and order-status flows. · `android/app/src/main/java/com/example/frontend2/ui/fragment/HomeFragment.java`
- [Commerce API client](https://github.com/adamwhite625/bach-hoa-project/blob/main/android/app/src/main/java/com/example/frontend2/data/remote/ApiClient.java): Retrofit boundary · `android/app/src/main/java/com/example/frontend2/data/remote/ApiClient.java`
- [Chat UI messages](https://github.com/adamwhite625/bach-hoa-project/blob/main/android/app/src/main/java/com/example/frontend2/data/model/ChatMessage.java): Android DTOs · `android/app/src/main/java/com/example/frontend2/data/model/ChatMessage.java`

### Commerce API

- [Commerce API](https://github.com/adamwhite625/bach-hoa-project/blob/main/backend/server.js): Node.js REST service · System of record for commerce and identity. · `backend/server.js`
- **REST routes**: route layer
- [JWT authorization](https://github.com/adamwhite625/bach-hoa-project/blob/main/backend/middlewares/authMiddleware.js): middleware · `backend/middlewares/authMiddleware.js`
- [Commerce controllers](https://github.com/adamwhite625/bach-hoa-project/blob/main/backend/controllers/orderController.js): domain controllers · Own products, carts, discounts, orders, payments, and identity workflows. · `backend/controllers/orderController.js`
- [Commerce models](https://github.com/adamwhite625/bach-hoa-project/blob/main/backend/models/orderModel.js): MongoDB models · Persists products, orders, and users. · `backend/models/orderModel.js`
- [Image upload integration](https://github.com/adamwhite625/bach-hoa-project/blob/main/backend/config/cloudinary.js): upload middleware · `backend/config/cloudinary.js`
- [Email service](https://github.com/adamwhite625/bach-hoa-project/blob/main/backend/services/emailService.js): Gmail integration · `backend/services/emailService.js`

### RAG chatbot

- [Chat API](https://github.com/adamwhite625/bach-hoa-project/blob/main/chatbotRAG/main.py): FastAPI service · Independent chatbot service. · `chatbotRAG/main.py`
- [Retrieval & generation](https://github.com/adamwhite625/bach-hoa-project/blob/main/chatbotRAG/chatbot_core.py): RAG core · `chatbotRAG/chatbot_core.py`
- [Knowledge ingestion](https://github.com/adamwhite625/bach-hoa-project/blob/main/chatbotRAG/build_db.py): vector-store builder · Loads markdown knowledge into Chroma. · `chatbotRAG/build_db.py`
- **Chroma vector store**: vector database

### Data & external services

- [MongoDB](https://github.com/adamwhite625/bach-hoa-project/blob/main/backend/config/db.js): primary database · `backend/config/db.js`
- **Cloudinary**: image storage
- **Gmail**: email provider
- **OpenAI**: generation provider

## Connections

- Admin portal → Admin access guard: protects UI
- Admin access guard → Admin auth state: reads session
- Admin access guard → Admin operations: permits
- Admin operations → Commerce API: REST requests
- Android shopper app → Shopping & orders UI: hosts
- Shopping & orders UI → Commerce API client: uses
- Commerce API client → Commerce API: REST requests
- Android shopper app → Chat UI messages: hosts
- Chat UI messages → Chat API: chat requests
- Commerce API → REST routes: mounts
- REST routes → JWT authorization: authorizes protected routes
- REST routes → Commerce controllers: delegates
- Commerce controllers → Commerce models: reads and writes
- Commerce models → MongoDB: persists
- Commerce controllers → Image upload integration: handles uploads
- Image upload integration → Cloudinary: stores images
- Commerce controllers → Email service: sends notifications
- Email service → Gmail: delivers through
- Chat API → Retrieval & generation: serves queries
- Retrieval & generation → Chroma vector store: retrieves context
- Retrieval & generation → OpenAI: generates response
- Knowledge ingestion → Chroma vector store: builds index