# hzjanuary/gromind architecture

> Architecture diagram of the GitHub repository hzjanuary/gromind, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-11-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hzjanuary/gromind
- Repository: https://github.com/hzjanuary/gromind

## Overview

##### Project type and purpose
- GroMind is a full-stack AI-powered intelligent shopping assistant.
- Frontend: A React/Vite single-page application using Tailwind for UI.
- Backend: Node.js/Express REST API with controllers, middleware, and data models.
- AI component: A recommendation engine (via `aiController.js` and `config/gemini.js`).
- Persistence: A database (configured in `src/config/db.js`) storing users, products, categories, orders, recipes.

##### File structure
- Top-level:
- backend/ – Express API, data seeder, controllers, models, routes
- frontend/ – React code, UI components, context providers, hooks, layouts, build config
- Patterns:
- Backend follows MVC (Models in `models/`, controllers in `controllers/`, routes in `routes/`)
- Frontend uses component hierarchy and Context API for auth, cart, theme
- Config & Scripts:
- `backend/seeder.js` populates sample data
- `backend/src/scripts/claim_orders_by_phone.js` is an operational script
- Vite/Tailwind configs in frontend

##### README for additional insights
- Purpose: deliver personalized product recommendations
- AI: uses machine-learning/recommendation algorithms
- Scope: demo application simulating a smart market environment

a. Main components
1. Frontend SPA
2. Backend REST API
3. AI Recommendation Engine (internal or external service)
4. Database (e.g., MongoDB or SQL)
5. Optional: Data seeder & operational scripts
b. Relationships and data flow
1. User interacts with Frontend → UI components (Pages, Dialogs)
2. Frontend sends HTTP requests to Backend API gateway (`server.js`)
3. Requests pass through Auth middleware, then hit specific Route → Controller
4. Controller invokes Model layer or AI Controller → may query DB or external AI service
5. DB returns data → Controller formats JSON → Frontend consumes and renders
6. Seeder/script utilities interact directly with DB for batch operations
c. Architectural patterns & design principles
- MVC on the Backend (clear separation between routing, business logic, and data access)
- Context and Hooks on the Frontend for cross-cutting concerns (Auth, Cart, Theme)
- Layered architecture: UI → API → Business Logic → Data Layer → Persistence
d. Key technologies
- Frontend: React, Vite, Tailwind CSS
- Backend: Node.js, Express, JWT auth middleware
- Database: configured in `db.js` (e.g., MongoDB/Mongoose or SQL)
- AI: Gemini config + `aiController.js` (invokes ML models or external API)

##### Essential elements without over-splitting
- Backend controllers by domain (Products, Categories, Orders, Recipes, AI)
- DB as a single node, even if it contains multiple collections or tables

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interaction
    User["User"]:::external
    User -->|"interacts with"| FE["React SPA"]:::frontend

    subgraph "Frontend (React/Vite SPA)"
        direction TB
        FE_Main["main.jsx"]:::frontend
        FE_App["App.jsx"]:::frontend
        FE_HTML["index.html"]:::frontend
        FE_CSS["index.css"]:::frontend
        FE_Vite["vite.config.js"]:::frontend
        FE_Tailwind["tailwind.config.js"]:::frontend

        subgraph "Layouts & Context"
            direction TB
            FE_Layout["SimpleLayout.jsx"]:::frontend
            FE_AuthCtx["AuthContext.jsx"]:::frontend
            FE_CartCtx["CartContext.jsx"]:::frontend
            FE_ThemeCtx["ThemeContext.jsx"]:::frontend
        end

        subgraph "Pages & Components"
            direction TB
            FE_Home["Home.jsx"]:::frontend
            FE_ProductList["ProductList.jsx"]:::frontend
            FE_Checkout["Checkout.jsx"]:::frontend
            FE_MyOrders["MyOrders.jsx"]:::frontend
            FE_LoginDialog["LoginDialog.jsx"]:::frontend
            FE_RecipeSearch["RecipeSearch.jsx"]:::frontend
            FE_RecipeDialog["RecipeDialog.jsx"]:::frontend
            FE_RecipeSuggestion["RecipeSuggestion.jsx"]:::frontend
            FE_UIComponents["components/ui/*"]:::frontend
        end

        FE --> FE_Main
        FE_Main --> FE_App
        FE_App --> FE_Layout
        FE_App --> FE_AuthCtx
        FE_App --> FE_CartCtx
        FE_App --> FE_ThemeCtx
        FE_App --> FE_Home
        FE_App --> FE_ProductList
        FE_App --> FE_Checkout
        FE_App --> FE_MyOrders
        FE_App --> FE_LoginDialog
        FE_App --> FE_RecipeSearch
        FE_App --> FE_RecipeDialog
        FE_App --> FE_RecipeSuggestion
        FE_App --> FE_UIComponents
    end

    subgraph "Backend (Node.js/Express API)"
        direction TB
        BE_Server["server.js"]:::backend
        BE_DBConfig["config/db.js"]:::backend
        BE_Gemini["config/gemini.js"]:::backend
        BE_AuthMW["middleware/auth.js"]:::backend

        subgraph "Routes"
            direction TB
            BE_RoutesIndex["routes/index.js"]:::backend
            BE_AuthRoutes["routes/authRoutes.js"]:::backend
            BE_ProductRoutes["routes/productRoutes.js"]:::backend
            BE_CategoryRoutes["routes/categoryRoutes.js"]:::backend
            BE_OrderRoutes["routes/orderRoutes.js"]:::backend
            BE_RecipeRoutes["routes/recipeRoutes.js"]:::backend
        end

        subgraph "Controllers"
            direction TB
            BE_AIController["controllers/aiController.js"]:::backend
            BE_ProductCtrl["controllers/productController.js"]:::backend
            BE_CategoryCtrl["controllers/categoryController.js"]:::backend
            BE_OrderCtrl["controllers/orderController.js"]:::backend
            BE_RecipeCtrl["controllers/recipeController.js"]:::backend
        end

        subgraph "Models"
            direction TB
            BE_UserModel["models/userModel.js"]:::backend
            BE_ProductModel["models/productModel.js"]:::backend
            BE_CategoryModel["models/categoryModel.js"]:::backend
            BE_OrderModel["models/orderModel.js"]:::backend
            BE_RecipeModel["models/recipeModel.js"]:::backend
        end

        BE["Express API"]:::backend
        BE --> BE_Server
        BE_Server --> BE_AuthMW
        BE_Server --> BE_RoutesIndex
        BE_RoutesIndex --> BE_AuthRoutes
        BE_RoutesIndex --> BE_ProductRoutes
        BE_RoutesIndex --> BE_CategoryRoutes
        BE_RoutesIndex --> BE_OrderRoutes
        BE_RoutesIndex --> BE_RecipeRoutes

        BE_AuthRoutes --> BE_AuthMW
        BE_ProductRoutes --> BE_ProductCtrl
        BE_CategoryRoutes --> BE_CategoryCtrl
        BE_OrderRoutes --> BE_OrderCtrl
        BE_RecipeRoutes --> BE_RecipeCtrl

        BE_ProductCtrl --> BE_ProductModel
        BE_CategoryCtrl --> BE_CategoryModel
        BE_OrderCtrl --> BE_OrderModel
        BE_RecipeCtrl --> BE_RecipeModel
        BE_AIController --> BE_Gemini
        BE_AIController --> EXT_AI

        BE_Server --> BE_DBConfig
    end

    %% Database and External AI
    DB["Database"]:::database
    EXT_AI["AI Recommendation Engine"]:::ai

    BE_ProductModel --> DB
    BE_CategoryModel --> DB
    BE_OrderModel --> DB
    BE_RecipeModel --> DB
    BE_UserModel --> DB

    BE_AIController -->|"calls"| EXT_AI
    EXT_AI -->|"recommendations"| BE_AIController

    %% Seeder and Scripts
    subgraph "Utilities"
        direction TB
        Seeder["seeder.js"]:::scripts
        DataProducts["data/products.js"]:::scripts
        DataCategories["data/categories.js"]:::scripts
        ScriptClaim["scripts/claim_orders_by_phone.js"]:::scripts
    end
    Seeder --> DB
    DataProducts --> Seeder
    DataCategories --> Seeder
    ScriptClaim --> DB

    %% Click Events
    click FE_Main "https://github.com/hzjanuary/gromind/blob/master/frontend/src/main.jsx"
    click FE_App "https://github.com/hzjanuary/gromind/blob/master/frontend/src/App.jsx"
    click FE_HTML "https://github.com/hzjanuary/gromind/blob/master/frontend/index.html"
    click FE_CSS "https://github.com/hzjanuary/gromind/blob/master/frontend/src/index.css"
    click FE_Vite "https://github.com/hzjanuary/gromind/blob/master/frontend/vite.config.js"
    click FE_Tailwind "https://github.com/hzjanuary/gromind/blob/master/frontend/tailwind.config.js"
    click FE_Layout "https://github.com/hzjanuary/gromind/blob/master/frontend/src/layouts/SimpleLayout.jsx"
    click FE_AuthCtx "https://github.com/hzjanuary/gromind/blob/master/frontend/src/AuthContext.jsx"
    click FE_CartCtx "https://github.com/hzjanuary/gromind/blob/master/frontend/src/CartContext.jsx"
    click FE_ThemeCtx "https://github.com/hzjanuary/gromind/blob/master/frontend/src/ThemeContext.jsx"
    click FE_Home "https://github.com/hzjanuary/gromind/blob/master/frontend/src/Home.jsx"
    click FE_ProductList "https://github.com/hzjanuary/gromind/blob/master/frontend/src/ProductList.jsx"
    click FE_Checkout "https://github.com/hzjanuary/gromind/blob/master/frontend/src/Checkout.jsx"
    click FE_MyOrders "https://github.com/hzjanuary/gromind/blob/master/frontend/src/MyOrders.jsx"
    click FE_LoginDialog "https://github.com/hzjanuary/gromind/blob/master/frontend/src/LoginDialog.jsx"
    click FE_RecipeSearch "https://github.com/hzjanuary/gromind/blob/master/frontend/src/RecipeSearch.jsx"
    click FE_RecipeDialog "https://github.com/hzjanuary/gromind/blob/master/frontend/src/RecipeDialog.jsx"
    click FE_RecipeSuggestion "https://github.com/hzjanuary/gromind/blob/master/frontend/src/RecipeSuggestion.jsx"
    click FE_UIComponents "https://github.com/hzjanuary/gromind/tree/master/frontend/src/components/ui/"

    click BE_Server "https://github.com/hzjanuary/gromind/blob/master/backend/src/server.js"
    click BE_DBConfig "https://github.com/hzjanuary/gromind/blob/master/backend/src/config/db.js"
    click BE_Gemini "https://github.com/hzjanuary/gromind/blob/master/backend/src/config/gemini.js"
    click BE_AuthMW "https://github.com/hzjanuary/gromind/blob/master/backend/src/middleware/auth.js"
    click BE_RoutesIndex "https://github.com/hzjanuary/gromind/blob/master/backend/src/routes/index.js"
    click BE_AuthRoutes "https://github.com/hzjanuary/gromind/blob/master/backend/src/routes/authRoutes.js"
    click BE_ProductRoutes "https://github.com/hzjanuary/gromind/blob/master/backend/src/routes/productRoutes.js"
    click BE_CategoryRoutes "https://github.com/hzjanuary/gromind/blob/master/backend/src/routes/categoryRoutes.js"
    click BE_OrderRoutes "https://github.com/hzjanuary/gromind/blob/master/backend/src/routes/orderRoutes.js"
    click BE_RecipeRoutes "https://github.com/hzjanuary/gromind/blob/master/backend/src/routes/recipeRoutes.js"
    click BE_AIController "https://github.com/hzjanuary/gromind/blob/master/backend/src/controllers/aiController.js"
    click BE_ProductCtrl "https://github.com/hzjanuary/gromind/blob/master/backend/src/controllers/productController.js"
    click BE_CategoryCtrl "https://github.com/hzjanuary/gromind/blob/master/backend/src/controllers/categoryController.js"
    click BE_OrderCtrl "https://github.com/hzjanuary/gromind/blob/master/backend/src/controllers/orderController.js"
    click BE_RecipeCtrl "https://github.com/hzjanuary/gromind/blob/master/backend/src/controllers/recipeController.js"
    click BE_UserModel "https://github.com/hzjanuary/gromind/blob/master/backend/src/models/userModel.js"
    click BE_ProductModel "https://github.com/hzjanuary/gromind/blob/master/backend/src/models/productModel.js"
    click BE_CategoryModel "https://github.com/hzjanuary/gromind/blob/master/backend/src/models/categoryModel.js"
    click BE_OrderModel "https://github.com/hzjanuary/gromind/blob/master/backend/src/models/orderModel.js"
    click BE_RecipeModel "https://github.com/hzjanuary/gromind/blob/master/backend/src/models/recipeModel.js"
    click Seeder "https://github.com/hzjanuary/gromind/blob/master/backend/seeder.js"
    click DataProducts "https://github.com/hzjanuary/gromind/blob/master/backend/data/products.js"
    click DataCategories "https://github.com/hzjanuary/gromind/blob/master/backend/data/categories.js"
    click ScriptClaim "https://github.com/hzjanuary/gromind/blob/master/backend/src/scripts/claim_orders_by_phone.js"

    %% Styles
    classDef frontend fill:#E0F7FA,stroke:#006064,color:#006064
    classDef backend fill:#E8F5E9,stroke:#2E7D32,color:#2E7D32
    classDef database fill:#FFF3E0,stroke:#EF6C00,color:#E65100
    classDef ai fill:#F3E5F5,stroke:#6A1B9A,color:#4A148C
    classDef scripts fill:#ECEFF1,stroke:#546E7A,color:#37474F
    classDef external fill:#FFFFFF,stroke:#000000,color:#000000
```
