# leomssilva/ultimatespeedwarehc3 architecture

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

- Interactive diagram: https://gitdiagram.com/leomssilva/ultimatespeedwarehc3
- Repository: https://github.com/leomssilva/ultimatespeedwarehc3

## Overview

##### Project type and purpose
- This is a full-stack, low-code VTEX IO e-commerce application with a custom “combos” admin panel and a separate Node.js backend integrating AWS services and VTEX APIs.
- The front-end lives entirely on the VTEX IO platform (storefront + admin UI), while the backend is a standalone Node service running on AWS (EC2 or Lambda), using DynamoDB for storage and calling VTEX catalog/order APIs.

##### File structure
Top-level directories:
- server/ – Node.js service (index.js, AWS/Dynamo helper, VTEX API wrappers).
- web/ – VTEX IO app:
– react/ – custom React components and API‐calling services.
– store/ – VTEX JSON blocks for pages and components.
– styles/, assets/, admin/ – static assets, admin panel config, internationalization.

##### README
- Confirms VTEX IO usage, AWS EC2, Lambda, DynamoDB, VTEX APIs, Node/JS/TS tech stack.
- Mentions a “combos” admin panel (product‐bundle management).

##### Main components
A. Client layer
- Shopper (Storefront UI)
- Admin user (Combos panel in VTEX IO)
B. VTEX IO platform
- Storefront blocks & React components
- Admin panel app
- VTEX CDN & routing
C. Backend service
- Node.js service on AWS (EC2 or Lambda)
- AWS DynamoDB table (“combos”)
- VTEX API clients (catalog.js, order.js)
D. External services
- VTEX Catalog & Order APIs (via Axios)
- AWS services (EC2/Lambda, DynamoDB)

##### Relationships and data flows
1. Shopper requests storefront → VTEX IO serves static blocks + JS.
2. Storefront JS calls backend endpoint (/combos) → Node service.
3. Node service retrieves combo data from DynamoDB.
4. Node service may call VTEX Catalog/Order APIs to enrich combos.
5. Response flows back to storefront UI for rendering bundle suggestions.
6. Admin user opens Combos panel → React admin component.
7. Admin UI calls backend (CRUD endpoints) → Node service → DynamoDB.

##### Architectural patterns and design principles
- Layered separation: Front-end (VTEX IO) vs. backend (Node/AWS).
- Microservice style: Single-purpose combos service.
- Externalized configuration: .env for AWS, dynamic Axios config for VTEX.
- Code organization: service modules (catalog, order, config), util for UUIDs.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Users Layer
    Shopper(["Shopper"]):::persona
    AdminUser(["Admin User"]):::persona

    %% VTEX IO Frontend Layer
    subgraph "VTEX IO Frontend" 
        direction TB
        StorefrontBlocks["VTEX Storefront Blocks\n(JSON/CSS/JS)"]:::frontend
        click StorefrontBlocks "https://github.com/leomssilva/ultimatespeedwarehc3/blob/main/web/store/blocks/home.jsonc"
        click StorefrontBlocks "https://github.com/leomssilva/ultimatespeedwarehc3/blob/main/web/store/blocks/product.jsonc"

        ReactComponents["Custom React Components\n(e.g., SliderComponent.jsx)"]:::frontend
        click ReactComponents "https://github.com/leomssilva/ultimatespeedwarehc3/blob/main/web/react/SliderComponent.jsx"

        AdminPanelConfig["Admin Panel Config\n(navigation/routes)"]:::frontend
        click AdminPanelConfig "https://github.com/leomssilva/ultimatespeedwarehc3/blob/main/web/admin/navigation.json"
        click AdminPanelConfig "https://github.com/leomssilva/ultimatespeedwarehc3/blob/main/web/admin/routes.json"

        Manifest["Manifest & I18n Messages"]:::frontend
        click Manifest "https://github.com/leomssilva/ultimatespeedwarehc3/blob/main/web/manifest.json"
        click Manifest "https://github.com/leomssilva/ultimatespeedwarehc3/blob/main/web/messages/en.json"
        click Manifest "https://github.com/leomssilva/ultimatespeedwarehc3/blob/main/web/messages/es.json"
        click Manifest "https://github.com/leomssilva/ultimatespeedwarehc3/blob/main/web/messages/pt.json"

        AssetsStyles["Assets & Styles\n(assets/, styles/)"]:::frontend
        click AssetsStyles "https://github.com/leomssilva/ultimatespeedwarehc3/tree/main/web/assets/"
        click AssetsStyles "https://github.com/leomssilva/ultimatespeedwarehc3/blob/main/web/styles/css/style.css"
        click AssetsStyles "https://github.com/leomssilva/ultimatespeedwarehc3/blob/main/web/styles/configs/style.json"
    end

    %% Backend Layer
    subgraph "Node.js Combos Service (AWS EC2/Lambda)" 
        direction TB
        EntryPoint["server/index.js"]:::backend
        click EntryPoint "https://github.com/leomssilva/ultimatespeedwarehc3/blob/main/server/index.js"

        EnvExample[".env.example"]:::backend
        click EnvExample "https://github.com/leomssilva/ultimatespeedwarehc3/blob/main/server/.env.example"

        DynamoHelper["AWS DynamoDB Helper\n(awsDynamo.js)"]:::backend
        click DynamoHelper "https://github.com/leomssilva/ultimatespeedwarehc3/blob/main/server/awsDynamo.js"

        subgraph "Services" 
            direction TB
            CatalogWrapper["VTEX Catalog API Wrapper\n(catalog.js)"]:::backend
            click CatalogWrapper "https://github.com/leomssilva/ultimatespeedwarehc3/blob/main/server/services/catalog.js"

            OrderWrapper["VTEX Order API Wrapper\n(order.js)"]:::backend
            click OrderWrapper "https://github.com/leomssilva/ultimatespeedwarehc3/blob/main/server/services/order.js"

            AxiosConfig["Axios Config\n(config/axios.js)"]:::backend
            click AxiosConfig "https://github.com/leomssilva/ultimatespeedwarehc3/blob/main/server/services/config/axios.js"

            ConfigModule["Service Config Module"]:::backend
            click ConfigModule "https://github.com/leomssilva/ultimatespeedwarehc3/tree/main/server/services/config/"

        end

        Utils["Utility Functions\n(uuid-generator.js)"]:::backend
        click Utils "https://github.com/leomssilva/ultimatespeedwarehc3/blob/main/server/util/uuid-generator.js"

        PackageBackend["server/package.json"]:::backend
        click PackageBackend "https://github.com/leomssilva/ultimatespeedwarehc3/blob/main/server/package.json"
    end

    %% Data Store
    DynamoDB["AWS DynamoDB\nCombos Table"]:::database

    %% External APIs
    VTEXCatalogAPI["VTEX Catalog API"]:::external
    VTEXOrderAPI["VTEX Order API"]:::external

    %% Flows
    Shopper -->|"requests storefront"| StorefrontBlocks
    StorefrontBlocks -->|"serves blocks + JS"| ReactComponents
    ReactComponents -->|"GET /combos"| EntryPoint
    AdminUser -->|"opens Combos panel"| AdminPanelConfig
    AdminPanelConfig -->|"CRUD /combos"| EntryPoint

    EntryPoint -->|"Query Table"| DynamoDB
    EntryPoint -->|"calls Catalog API"| VTEXCatalogAPI
    EntryPoint -->|"calls Order API"| VTEXOrderAPI
    VTEXCatalogAPI -->|"response"| EntryPoint
    VTEXOrderAPI -->|"response"| EntryPoint
    EntryPoint -->|"response data"| ReactComponents

    %% Styles
    classDef frontend fill:#cce5ff,stroke:#004085,color:#004085;
    classDef backend fill:#d4edda,stroke:#155724,color:#155724;
    classDef database fill:#fff3cd,stroke:#856404,color:#856404,stroke-dasharray: 5 5;
    classDef external fill:#e2e3e5,stroke:#6c757d,color:#6c757d,stroke-dasharray: 2 2;
    classDef persona fill:#f8d7da,stroke:#721c24,color:#721c24,stroke-width:2px;
```
