# hieule-allcommerce/bc-cs-atlantisart1 architecture

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

- Interactive diagram: https://gitdiagram.com/hieule-allcommerce/bc-cs-atlantisart1
- Repository: https://github.com/hieule-allcommerce/bc-cs-atlantisart1

## Overview

##### Project type and purpose
- This repository is a BigCommerce “Stencil” theme—essentially a front-end, asset-driven storefront for an e-commerce site.
- It contains:
- A Node-based build system (Grunt + Webpack + npm scripts)
- SCSS/CSS assets
- JavaScript modules (ES6, page-scoped classes extending a PageManager)
- Handlebars templates (layout, components, pages)
- Config files (stencil.conf.js, webpack configs, package.json, schema.json)

##### File structure
- Top-level build dirs & files: Gruntfile.js, webpack.\*.js, package.json, stencil.conf.js
- lang/: translation files (en.json, fr.json, etc.)
- templates/: Handlebars templates organized by “components,” “layout,” “pages”
- config & schema: config.json, schema.json, schemaTranslations.json for BigCommerce theme settings

##### Extract architecture notes from README
- Themes are driven by BigCommerce’s Stencil engine; templates compile server‐side with Handlebars + injected context
- Client JS runs via PageManager subclasses: before(), loaded(), after() hooks
- Polyfills are feature‐detected; stencil-utils handles AJAX interactions with BigCommerce APIs
- Local dev uses “stencil” CLI to run a proxy server
- Assets are deployed as a zip to BigCommerce and served to browsers

##### Main components & interactions
a. Build System (Local Dev)
- Node.js + npm scripts
- Grunt task for SVG sprite generation
- Webpack: bundles assets (JS modules, SCSS → CSS, polyfills)
- ESLint for code quality
b. Theme Definition
- SCSS modules → compiled CSS
- JS modules (PageManager classes + utilities) → main bundle + route chunks
- Handlebars templates (layout, components, pages)
- Localization files
- Config & schema (theme settings)
c. Stencil CLI & BigCommerce Platform
- Stencil CLI: local preview, “stencil push” uploads theme package
- BigCommerce server: compiles templates with context, serves storefront endpoints (catalog, cart, checkout)
- stencil-utils: client AJAX calls to BigCommerce APIs (cart, products, customer data)
d. Browser (Client)
- Loads HTML (generated by Handlebars) + CSS + JS bundle
- Feature-detects and loads polyfills if needed
- PageManager modules run per page type (category, product, cart, etc.)
- Interacts with external services (payment gateways, Yotpo reviews, social widgets)

##### Relationships & data flows
- Developer edits SCSS/JS/templates → triggers Grunt/Webpack → outputs static assets
- stencil push → theme zip uploaded to BigCommerce
- Customer’s browser requests a page → BigCommerce renders Handlebars templates with context → HTML + CSS + JS delivered
- Browser runs polyfill loader → main bundle executes → PageManager picks correct module by route → AJAX via stencil-utils to platform APIs → UI updates

##### Architectural patterns & design principles
- Separation of concerns:
- Build tools vs. source code vs. runtime
- Templates (view) vs. JS modules (controller behavior) vs. SCSS (style)
- Module bundling & code-splitting: Webpack config for production/dev
- Hook pattern in PageManager: before() → loaded() → after()
- Feature-detection & progressive enhancement (polyfills only when needed)
- Theme settings schema drives dynamic template rendering

- Clear labels for each component (e.g., “Webpack Bundler,” “Handlebars Templates,” “Stencil CLI,” “Browser”)
- Related assets (assets/js, assets/scss, templates) under a “Theme Package” container
- Technologies: Node.js, Grunt, Webpack, Handlebars, stencil-utils, ES6 modules, polyfills
- Lifecycle in Browser: feature-detect → load polyfills → load main.js → PageManager.loaded()

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Developer Workstation
    subgraph "Developer Workstation"
        NpmScripts["Node.js + npm scripts"]:::build
        LockFile["package-lock.json"]:::build
        Grunt["Grunt Task Runner"]:::build
        subgraph "Webpack Configs"
            WebpackCommon["webpack.common.js"]:::build
            WebpackDev["webpack.dev.js"]:::build
            WebpackProd["webpack.prod.js"]:::build
        end
        StencilCLIconfig["Stencil CLI Configuration"]:::build
        TestRunner["Test Runner"]:::build
        NpmScripts --> LockFile
        NpmScripts --> Grunt
        NpmScripts --> WebpackCommon
        NpmScripts --> WebpackDev
        NpmScripts --> WebpackProd
        NpmScripts --> StencilCLIconfig
        NpmScripts --> TestRunner
    end

    %% Theme Package
    subgraph "Theme Package"
        subgraph "Styles"
            SCSS["SCSS Source Modules"]:::theme
            MaintSCSS["maintenance.scss"]:::theme
            OptCheckoutSCSS["optimized-checkout.scss"]:::theme
        end
        subgraph "Scripts"
            JSApp["assets/js/app.js"]:::theme
            Polyfills["assets/js/polyfills.js"]:::theme
            PageManagerCore["assets/js/page-manager.js"]:::theme
            ThemeScopedJS["assets/js/theme/"]:::theme
            PapaThemesJS["assets/js/papathemes/"]:::theme
        end
        subgraph "Templates"
            LayoutTemplates["templates/layout/"]:::theme
            ComponentTemplates["templates/components/"]:::theme
            PageTemplates["templates/pages/"]:::theme
        end
        subgraph "Localization"
            EN["lang/en.json"]:::theme
            FR["lang/fr.json"]:::theme
            ENCA["lang/en-CA.json"]:::theme
            FRCA["lang/fr-CA.json"]:::theme
        end
        subgraph "Config & Schema"
            ConfigJSON["config.json"]:::theme
            SchemaJSON["schema.json"]:::theme
            SchemaTrans["schemaTranslations.json"]:::theme
            ConfigStencil["config.stencil copy.json"]:::theme
            Secrets["secrets.stencil copy.json"]:::theme
        end
        subgraph "Static Assets"
            Fonts["assets/fonts/"]:::theme
            Icons["assets/icons/"]:::theme
            Images["assets/img/"]:::theme
        end
    end

    %% Platform
    subgraph "BigCommerce Stencil Engine"
        StencilCLI["Stencil CLI"]:::platform
        BCServer["BigCommerce Server"]:::platform
        APIs["BigCommerce APIs"]:::platform
    end

    %% Browser
    subgraph "Browser"
        HTML["HTML (Handlebars output)"]:::browser
        CSS["CSS"]:::browser
        JSBundle["JS Bundle"]:::browser
        PolyfillLoader["Polyfill Loader"]:::browser
        PageManagerRun["PageManager Modules"]:::browser
        ExternalServices["External Services"]:::external
    end

    %% Flows
    NpmScripts -->|"compile assets"| SCSS
    Grunt -->|"generate SVG sprite"| Icons
    WebpackCommon -->|"bundle JS/SCSS"| JSBundle
    WebpackDev -->|"bundle JS/SCSS"| JSBundle
    WebpackProd -->|"bundle JS/SCSS"| JSBundle
    SCSS -->|"to CSS"| CSS
    JSApp -->|"entry for bundle"| JSBundle
    Polyfills -->|"to bundle"| JSBundle
    PageManagerCore -->|"to bundle"| JSBundle
    ThemeScopedJS -->|"to bundle"| JSBundle
    PapaThemesJS -->|"to bundle"| JSBundle

    StencilCLIconfig -->|"push theme"| StencilCLI
    TestRunner -->|"run tests"| JSApp

    LayoutTemplates -->|"templates"| BCServer
    ComponentTemplates --> BCServer
    PageTemplates --> BCServer
    EN --> BCServer
    FR --> BCServer
    ENCA --> BCServer
    FRCA --> BCServer
    ConfigJSON --> BCServer
    SchemaJSON --> BCServer
    SchemaTrans --> BCServer
    ConfigStencil --> BCServer
    Secrets --> BCServer
    Fonts --> BCServer
    Icons --> BCServer
    Images --> BCServer

    StencilCLI -->|"compile templates"| BCServer
    BCServer -->|"render HTML"| HTML
    CSS -->|"served"| CSS
    JSBundle -->|"served"| JSBundle

    HTML --> PolyfillLoader
    PolyfillLoader --> JSBundle
    JSBundle --> PageManagerRun
    PageManagerRun -->|"AJAX via stencil-utils"| APIs
    APIs --> PageManagerRun
    PageManagerRun --> ExternalServices

    %% Click Events
    click NpmScripts "https://github.com/hieule-allcommerce/bc-cs-atlantisart1/blob/main/package.json"
    click LockFile "https://github.com/hieule-allcommerce/bc-cs-atlantisart1/blob/main/package-lock.json"
    click Grunt "https://github.com/hieule-allcommerce/bc-cs-atlantisart1/blob/main/Gruntfile.js"
    click WebpackCommon "https://github.com/hieule-allcommerce/bc-cs-atlantisart1/blob/main/webpack.common.js"
    click WebpackDev "https://github.com/hieule-allcommerce/bc-cs-atlantisart1/blob/main/webpack.dev.js"
    click WebpackProd "https://github.com/hieule-allcommerce/bc-cs-atlantisart1/blob/main/webpack.prod.js"
    click StencilCLIconfig "https://github.com/hieule-allcommerce/bc-cs-atlantisart1/blob/main/stencil.conf.js"
    click TestRunner "https://github.com/hieule-allcommerce/bc-cs-atlantisart1/blob/main/karma.conf.js"
    click SCSS "https://github.com/hieule-allcommerce/bc-cs-atlantisart1/tree/main/assets/scss/"
    click MaintSCSS "https://github.com/hieule-allcommerce/bc-cs-atlantisart1/blob/main/assets/scss/maintenance.scss"
    click OptCheckoutSCSS "https://github.com/hieule-allcommerce/bc-cs-atlantisart1/blob/main/assets/scss/optimized-checkout.scss"
    click JSApp "https://github.com/hieule-allcommerce/bc-cs-atlantisart1/blob/main/assets/js/app.js"
    click Polyfills "https://github.com/hieule-allcommerce/bc-cs-atlantisart1/blob/main/assets/js/polyfills.js"
    click PageManagerCore "https://github.com/hieule-allcommerce/bc-cs-atlantisart1/blob/main/assets/js/page-manager.js"
    click ThemeScopedJS "https://github.com/hieule-allcommerce/bc-cs-atlantisart1/tree/main/assets/js/theme/"
    click PapaThemesJS "https://github.com/hieule-allcommerce/bc-cs-atlantisart1/tree/main/assets/js/papathemes/"
    click LayoutTemplates "https://github.com/hieule-allcommerce/bc-cs-atlantisart1/tree/main/templates/layout/"
    click ComponentTemplates "https://github.com/hieule-allcommerce/bc-cs-atlantisart1/tree/main/templates/components/"
    click PageTemplates "https://github.com/hieule-allcommerce/bc-cs-atlantisart1/tree/main/templates/pages/"
    click EN "https://github.com/hieule-allcommerce/bc-cs-atlantisart1/blob/main/lang/en.json"
    click FR "https://github.com/hieule-allcommerce/bc-cs-atlantisart1/blob/main/lang/fr.json"
    click ENCA "https://github.com/hieule-allcommerce/bc-cs-atlantisart1/blob/main/lang/en-CA.json"
    click FRCA "https://github.com/hieule-allcommerce/bc-cs-atlantisart1/blob/main/lang/fr-CA.json"
    click ConfigJSON "https://github.com/hieule-allcommerce/bc-cs-atlantisart1/blob/main/config.json"
    click SchemaJSON "https://github.com/hieule-allcommerce/bc-cs-atlantisart1/blob/main/schema.json"
    click SchemaTrans "https://github.com/hieule-allcommerce/bc-cs-atlantisart1/blob/main/schemaTranslations.json"
    click ConfigStencil "https://github.com/hieule-allcommerce/bc-cs-atlantisart1/blob/main/config.stencil copy.json"
    click Secrets "https://github.com/hieule-allcommerce/bc-cs-atlantisart1/blob/main/secrets.stencil copy.json"
    click Fonts "https://github.com/hieule-allcommerce/bc-cs-atlantisart1/tree/main/assets/fonts/"
    click Icons "https://github.com/hieule-allcommerce/bc-cs-atlantisart1/tree/main/assets/icons/"
    click Images "https://github.com/hieule-allcommerce/bc-cs-atlantisart1/tree/main/assets/img/"

    %% Styles
    classDef build fill:#fdd835,stroke:#333,stroke-width:1px;
    classDef theme fill:#a5d6a7,stroke:#333,stroke-width:1px;
    classDef platform fill:#90caf9,stroke:#333,stroke-width:1px;
    classDef browser fill:#b3e5fc,stroke:#333,stroke-width:1px;
    classDef external fill:#ce93d8,stroke:#333,stroke-width:1px;
```
