# meruemvn/ocop_be architecture

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

- Interactive diagram: https://gitdiagram.com/meruemvn/ocop_be
- Repository: https://github.com/meruemvn/ocop_be

## Overview

##### Project type and purpose
- This is a RESTful backend service (“OCOPBE”) built on Node.js/Express, backed by MongoDB, that provides CRUD endpoints for users, products, orders, carts, distributors, admins, and an AI-based recommendation engine. Precomputed recommendation artifacts are produced and consumed by Python scripts and a Node.js “recommender” service.

##### Main architectural components
a. Entry point / API layer
- app.js – initializes Express, loads config, connects to MongoDB, mounts routes
- config/db.js – MongoDB/Mongoose connection setup
b. Routing & Middleware
- routes/*.js – define HTTP endpoints per resource (user, product, order, cart, distributor, admin, recommendation)
- middlewares/authMiddleware.js – handles authentication/authorization
c. Controllers
- controllers/*Controller.js – parse requests, enforce business rules, call services or models
d. Services & Business Logic
- services/recommender.service.js – loads Python artifacts (JSON, NPY, CSV, PKL) to compute recommendations
e. Data Layer
- models/*.js – Mongoose schemas (User, Product, Order, Cart, RequestLog)
- MongoDB – stores persistent application data
f. Python Recommender Artifacts & Scripts
- python_recommender_artifacts/ – precomputed matrices, maps, stopwords used by recommender.service
- scripts/ – Jupyter notebook and Python/JS scripts to train, normalize, enrich, export, and test the recommender

##### Relationships & data flows
1. Client (web/mobile) sends HTTP request →
2. Express (app.js) receives request →
3. Route handler (routes/*.js) →
4. Auth middleware (optional) →
5. Controller (*.js) →
- For CRUD: calls Mongoose Model → MongoDB → returns data → controller → response
- For recommendations: calls recommender.service → loads precomputed artifacts from disk → computes recommendations → returns to controller → response
6. Response sent back to client

##### Key architectural patterns & design principles
- MVC-style separation: routes → controllers → services/models
- Service layer for isolating business logic (recommender.service)
- Externalized configuration (config/db.js)
- Precomputation & caching: Python artifacts stored on disk to speed up recommendation queries
- Modularization: each resource has its own route, controller, and model

##### Detail without overthinking
- Every controller and its route grouping to highlight resource boundaries
- Distinguish the recommender path from standard CRUD paths
- Essential components so that an engineer can understand request flow, fault boundaries, and deployment scope at a glance

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% API Layer
    subgraph "API Layer"
        direction TB
        API_APP["app.js"]:::nodejs
        API_DBCFG["config/db.js"]:::nodejs
        subgraph "Routing & Middleware"
            direction TB
            ROUTE_USER["userRoutes.js"]:::nodejs
            ROUTE_PRODUCT["productRoutes.js"]:::nodejs
            ROUTE_ORDER["orderRoutes.js"]:::nodejs
            ROUTE_CART["cartRoutes.js"]:::nodejs
            ROUTE_DISTRIBUTOR["distributorRoutes.js"]:::nodejs
            ROUTE_ADMIN["adminRoutes.js"]:::nodejs
            ROUTE_RECOMMEND["recommendationRoutes.js"]:::nodejs
            AUTH_MW["authMiddleware.js"]:::nodejs
        end
    end

    %% Business Layer
    subgraph "Business Layer"
        direction TB
        subgraph "Controllers"
            direction TB
            CTRL_USER["userController.js"]:::nodejs
            CTRL_PRODUCT["productController.js"]:::nodejs
            CTRL_ORDER["orderController.js"]:::nodejs
            CTRL_CART["cartController.js"]:::nodejs
            CTRL_DISTRIBUTOR["distributorController.js"]:::nodejs
            CTRL_ADMIN["adminController.js"]:::nodejs
            CTRL_RECOMMEND["recommendationController.js"]:::nodejs
        end
        SERVICE_RECOMMENDER["recommender.service.js"]:::nodejs
    end

    %% Data Layer
    subgraph "Data Layer"
        direction TB
        subgraph "Models"
            direction TB
            MODEL_USER["User.js"]:::nodejs
            MODEL_PRODUCT["Product.js"]:::nodejs
            MODEL_ORDER["Order.js"]:::nodejs
            MODEL_CART["Cart.js"]:::nodejs
            MODEL_REQUESTLOG["RequestLog.js"]:::nodejs
        end
        DB["MongoDB"]:::mongodb
    end

    %% Artifact Layer
    subgraph "Artifact Layer"
        direction TB
        ARTIFACT_STORE["python_recommender_artifacts"]:::artifact
        subgraph "Training & Utility Scripts"
            direction TB
            SCRIPT_NB["Train_AI_Recommend.ipynb"]:::script
            SCRIPT_CREATE["scripts/create.js"]:::script
            SCRIPT_EXPORT["scripts/exportProductNames.js"]:::script
            SCRIPT_NORMALIZE["scripts/normalize_csv.py"]:::script
            SCRIPT_ENRICH["scripts/enrich_product_map_by_name_matching.py"]:::script
            SCRIPT_CLI["scripts/recommender_cli.py"]:::script
            SCRIPT_TEST["scripts/test_recommender.py"]:::script
        end
    end

    %% Client
    Client["Client (Web/Mobile)"]:::external

    %% Connections
    Client -->|HTTP| API_APP
    API_APP --> API_DBCFG
    API_APP --> ROUTE_USER
    API_APP --> ROUTE_PRODUCT
    API_APP --> ROUTE_ORDER
    API_APP --> ROUTE_CART
    API_APP --> ROUTE_DISTRIBUTOR
    API_APP --> ROUTE_ADMIN
    API_APP --> ROUTE_RECOMMEND
    ROUTE_* --> AUTH_MW
    ROUTE_USER --> CTRL_USER
    ROUTE_PRODUCT --> CTRL_PRODUCT
    ROUTE_ORDER --> CTRL_ORDER
    ROUTE_CART --> CTRL_CART
    ROUTE_DISTRIBUTOR --> CTRL_DISTRIBUTOR
    ROUTE_ADMIN --> CTRL_ADMIN
    ROUTE_RECOMMEND --> CTRL_RECOMMEND
    CTRL_USER --> MODEL_USER
    CTRL_PRODUCT --> MODEL_PRODUCT
    CTRL_ORDER --> MODEL_ORDER
    CTRL_CART --> MODEL_CART
    CTRL_RECOMMEND --> SERVICE_RECOMMENDER
    MODEL_USER -->|DB Query| DB
    MODEL_PRODUCT -->|DB Query| DB
    MODEL_ORDER -->|DB Query| DB
    MODEL_CART -->|DB Query| DB
    MODEL_REQUESTLOG -->|DB Query| DB
    SERVICE_RECOMMENDER -->|loads artifacts| ARTIFACT_STORE
    SERVICE_RECOMMENDER --> CTRL_RECOMMEND
    SCRIPT_* --> ARTIFACT_STORE
    SCRIPT_NB --> ARTIFACT_STORE

    %% Click Events
    click API_APP "https://github.com/meruemvn/ocop_be/blob/main/app.js"
    click API_DBCFG "https://github.com/meruemvn/ocop_be/blob/main/config/db.js"
    click ROUTE_USER "https://github.com/meruemvn/ocop_be/blob/main/routes/userRoutes.js"
    click ROUTE_PRODUCT "https://github.com/meruemvn/ocop_be/blob/main/routes/productRoutes.js"
    click ROUTE_ORDER "https://github.com/meruemvn/ocop_be/blob/main/routes/orderRoutes.js"
    click ROUTE_CART "https://github.com/meruemvn/ocop_be/blob/main/routes/cartRoutes.js"
    click ROUTE_DISTRIBUTOR "https://github.com/meruemvn/ocop_be/blob/main/routes/distributorRoutes.js"
    click ROUTE_ADMIN "https://github.com/meruemvn/ocop_be/blob/main/routes/adminRoutes.js"
    click ROUTE_RECOMMEND "https://github.com/meruemvn/ocop_be/blob/main/routes/recommendationRoutes.js"
    click AUTH_MW "https://github.com/meruemvn/ocop_be/blob/main/middlewares/authMiddleware.js"
    click CTRL_USER "https://github.com/meruemvn/ocop_be/blob/main/controllers/userController.js"
    click CTRL_PRODUCT "https://github.com/meruemvn/ocop_be/blob/main/controllers/productController.js"
    click CTRL_ORDER "https://github.com/meruemvn/ocop_be/blob/main/controllers/orderController.js"
    click CTRL_CART "https://github.com/meruemvn/ocop_be/blob/main/controllers/cartController.js"
    click CTRL_DISTRIBUTOR "https://github.com/meruemvn/ocop_be/blob/main/controllers/distributorController.js"
    click CTRL_ADMIN "https://github.com/meruemvn/ocop_be/blob/main/controllers/adminController.js"
    click CTRL_RECOMMEND "https://github.com/meruemvn/ocop_be/blob/main/controllers/recommendationController.js"
    click SERVICE_RECOMMENDER "https://github.com/meruemvn/ocop_be/blob/main/services/recommender.service.js"
    click MODEL_USER "https://github.com/meruemvn/ocop_be/blob/main/models/User.js"
    click MODEL_PRODUCT "https://github.com/meruemvn/ocop_be/blob/main/models/Product.js"
    click MODEL_ORDER "https://github.com/meruemvn/ocop_be/blob/main/models/Order.js"
    click MODEL_CART "https://github.com/meruemvn/ocop_be/blob/main/models/Cart.js"
    click MODEL_REQUESTLOG "https://github.com/meruemvn/ocop_be/blob/main/models/RequestLog.js"
    click ARTIFACT_STORE "https://github.com/meruemvn/ocop_be/tree/main/python_recommender_artifacts/"
    click SCRIPT_NB "https://github.com/meruemvn/ocop_be/blob/main/Train_AI_Recommend.ipynb"
    click SCRIPT_CREATE "https://github.com/meruemvn/ocop_be/blob/main/scripts/create.js"
    click SCRIPT_EXPORT "https://github.com/meruemvn/ocop_be/blob/main/scripts/exportProductNames.js"
    click SCRIPT_NORMALIZE "https://github.com/meruemvn/ocop_be/blob/main/scripts/normalize_csv.py"
    click SCRIPT_ENRICH "https://github.com/meruemvn/ocop_be/blob/main/scripts/enrich_product_map_by_name_matching.py"
    click SCRIPT_CLI "https://github.com/meruemvn/ocop_be/blob/main/scripts/recommender_cli.py"
    click SCRIPT_TEST "https://github.com/meruemvn/ocop_be/blob/main/scripts/test_recommender.py"

    %% Styles
    classDef nodejs fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef mongodb fill:#90EE90,stroke:#000,stroke-width:1px
    classDef artifact fill:#FFFF99,stroke:#000,stroke-width:1px
    classDef script fill:#FFD700,stroke:#000,stroke-width:1px,stroke-dasharray: 5 5
    classDef external fill:#D3D3D3,stroke:#000,stroke-width:1px
```
