# loopbackio/loopback4-example-shopping architecture

> Architecture diagram of the GitHub repository loopbackio/loopback4-example-shopping, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/loopbackio/loopback4-example-shopping
- Repository: https://github.com/loopbackio/loopback4-example-shopping

## Overview

##### Main Components
- Frontend Client: Represented by the static assets in the “packages/shopping/public” directory (e.g., shoppy.html, index.html, and related JavaScript/CSS). This is the web page interface for the shopping experience.
- API Backend (Shopping App): The core LoopBack application found under “packages/shopping/src”. This includes controllers (e.g., user-management, shopping-cart, user-order, ping, product), models, datasources (for MongoDB and Redis), repositories, and services (e.g., recommender, user management, JWT, email, password hashing, and validator).
- Recommender Service: A separate packaged module under “packages/recommender” that exposes recommendation functionality via gRPC and REST endpoints. It acts as an external service that the shopping app calls to obtain product recommendations.
- Databases:
- MongoDB serves as the primary database for models like User, Product, Order, etc.
- Redis is used explicitly for maintaining shopping cart state.
- External Email Provider: Nodemailer is used for sending password reset emails.
- Infrastructure/Deployment: Dockerfiles (several variants for monorepo, recommender, and shopping), Kubernetes configuration files (in the “kubernetes” directory), and OpenShift files. This indicates that the system is containerized and intended to be deployed in cloud environments (Kubernetes cluster or OpenShift).

##### Relationships and Interactions
- The Web Browser (client) accesses the shopping website statically served by the “packages/shopping/public” assets.
- The client interacts with the backend API (LoopBack app) via REST endpoints exposed by controllers.
- Controllers in the backend layer invoke services for core business logic:
- Authentication and Authorization: Using JWT service, UserService (via @loopback/authentication), and voter functions for role-based access.
- Shopping Cart Management and Order placement: Controllers call the repositories and services to persist or retrieve data from MongoDB and Redis.
- Product Recommendation: The shopping service calls the recommender service (over gRPC or REST) to obtain personalized recommendations.
- Email and Password Reset: The email service integrating Nodemailer is invoked during password reset flows.
- Database Interactions:
- MongoDB is used as the main persistent store (accessed via LoopBack datasources).
- Redis is used for fast access to session or shopping cart data.
- Infrastructure:
- Docker is used for containerizing the apps.
- Kubernetes or OpenShift resources deploy the applications as separate microservices (shopping app container, recommendation container, databases, etc.).

##### Architectural Patterns and Design Principles
- The project adopts the separation of concerns where the frontend, backend API, and the recommendation service are clearly defined.
- Domain-driven design is visible through the distinct models (User, Product, Order, etc.) and their associated controllers, repositories, and services.
- The use of LoopBack 4 patterns (dependency injection, repositories & datasources, decorators for controllers and models) underpins the server structure.
- Containerized deployment and orchestration emphasize a cloud-native microservices architecture.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client Layer"
        A["Web Browser"]:::frontend
        B["Frontend (Shoppy Website)"]:::frontend
    end
    A -->|"Request"| B

    %% Backend Services
    subgraph "Backend Services"
        C["LoopBack API (Shopping App)"]:::backend
        D["JWT Auth Service"]:::service
        E["Password Hashing Service"]:::service
        F["Email Service (Nodemailer)"]:::service
        G["Recommender Service (gRPC/REST)"]:::service
    end
    B -->|"API_call"| C
    C -->|"Authenticate"| D
    C -->|"Hash_Password"| E
    C -->|"Send_ResetEmail"| F
    C -->|"Get_Recommendations"| G

    %% Datastores
    subgraph "Datastores"
        H["MongoDB (Primary Store)"]:::database
        I["Redis (Shopping Cart)"]:::database
    end
    C -->|"DB_Query"| H
    C -->|"Cart_Access"| I

    %% Deployment Infrastructure
    subgraph "Deployment Infrastructure"
        J1["Docker (Monorepo)"]:::deployment
        J2["Docker (Shopping)"]:::deployment
        J3["Docker (Recommender)"]:::deployment
        K["Kubernetes/Openshift"]:::deployment
    end
    J1 -->|"Deploys"| C
    J2 -->|"Deploys"| C
    J3 -->|"Deploys"| G
    K -->|"Orchestrates"| C
    K -->|"Orchestrates"| G

    %% Click Events
    click B "https://github.com/loopbackio/loopback4-example-shopping/tree/master/packages/shopping/public"
    click C "https://github.com/loopbackio/loopback4-example-shopping/tree/master/packages/shopping/src"
    click G "https://github.com/loopbackio/loopback4-example-shopping/tree/master/packages/recommender"
    click H "https://github.com/loopbackio/loopback4-example-shopping/blob/master/packages/shopping/src/datasources/mongo.datasource.ts"
    click I "https://github.com/loopbackio/loopback4-example-shopping/blob/master/packages/shopping/src/datasources/redis.datasource.ts"
    click F "https://github.com/loopbackio/loopback4-example-shopping/blob/master/packages/shopping/src/services/email.service.ts"
    click D "https://github.com/loopbackio/loopback4-example-shopping/blob/master/packages/shopping/src/services/jwt.service.ts"
    click E "https://github.com/loopbackio/loopback4-example-shopping/blob/master/packages/shopping/src/services/hash.password.bcryptjs.ts"
    click J1 "https://github.com/loopbackio/loopback4-example-shopping/blob/master/Dockerfile.monorepo"
    click J2 "https://github.com/loopbackio/loopback4-example-shopping/blob/master/Dockerfile.shopping"
    click J3 "https://github.com/loopbackio/loopback4-example-shopping/blob/master/Dockerfile.recommender"
    click K "https://github.com/loopbackio/loopback4-example-shopping/tree/master/kubernetes"

    %% Styles
    classDef frontend fill:#D1E8FF,stroke:#2E6DA4,stroke-width:2px;
    classDef backend fill:#D1FFD1,stroke:#2E7D32,stroke-width:2px;
    classDef service fill:#FFF2CC,stroke:#D4AC0D,stroke-width:2px;
    classDef database fill:#FFDAB9,stroke:#CD853F,stroke-width:2px;
    classDef deployment fill:#E6E6FA,stroke:#9370DB,stroke-width:2px;
```
