# vtex-apps/minimum-boilerplate-theme architecture

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

- Interactive diagram: https://gitdiagram.com/vtex-apps/minimum-boilerplate-theme
- Repository: https://github.com/vtex-apps/minimum-boilerplate-theme

## Overview

##### Project type and purpose
- This is a front-end “theme” VTEX IO app built on the VTEX Store Framework.
- It provides a minimal starting point for building a custom storefront by defining page “blocks” and styles, then wiring them into VTEX’s runtime.

##### File structure
- Top-level manifest.json: declares the app’s vendor/name, and its runtime dependencies on VTEX apps.
- store/blocks/*.jsonc: each JSONC file configures one page or layout block (home, product, search, header, footer, default).
- styles/configs/style.json: theme-wide style tokens and variables.
- styles/css/vtex.store-components.css: global CSS override for Store Framework components.
- docs/README.md: documentation stub.

##### Key architectural insights from README
- The theme is installed/uninstalled via the VTEX CLI (vtex link, vtex install/uninstall).
- Depends on two VTEX apps: vtex.store and vtex.store-sitemap.
- Render pipeline: the Store Framework loads blocks & CSS, composes pages, and serves them via the VTEX IO CDN.

##### Main components
a. Developer environment
- VTEX CLI (Toolbelt)
- Local workspace & Git repo (the boilerplate code)
b. Theme App (your code)
- manifest.json (app metadata & dependencies)
- store/blocks (page composition)
- styles/configs & styles/css (visual theming)
c. VTEX IO Platform
- Store Framework (runtime that reads blocks + CSS)
- vtex.store-sitemap (auto-generates sitemap, page routing)
- vtex.store (storefront services like search, catalog, cart)
d. End user (browser)
- Fetches JS/CSS from VTEX CDN, sends events & queries to storefront services.

##### Relationships and data flows
- Developer → (vtex link) → Theme App registers on VTEX IO workspace
- Theme App’s manifest.json → Platform loads dependencies (vtex.store, vtex.store-sitemap)
- Store Framework → reads store/blocks/*.jsonc to assemble UI components into routes
- Store Framework → injects styles/css and style tokens from styles/configs
- End user browser → HTTP GET → VTEX CDN → serves assembled HTML/CSS/JS
- Browser interactions (search, add to cart) → VTEX storefront APIs under vtex.store

##### Architectural patterns & design principles
- Component-based composition via JSONC “blocks”
- Configuration-driven layouts (blocks declare child components)
- Clearly separated layers: code vs. style vs. platform services
- Extensible plugin/app model (theme is just another VTEX IO app)

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Developer Environment"
        CLI["VTEX CLI (Toolbelt)"]:::developer
        WS["Local Workspace & Git Repo"]:::developer
    end

    CLI -->|"vtex link"| manifest
    WS -->|"edit code & configs"| manifest

    subgraph "Theme App" 
        manifest["manifest.json"]:::theme
        subgraph "store/blocks" 
            blockHome["home.jsonc"]:::theme
            blockProduct["product.jsonc"]:::theme
            blockSearch["search.jsonc"]:::theme
            blockHeader["header.jsonc"]:::theme
            blockFooter["footer.jsonc"]:::theme
            blockDefault["default.jsonc"]:::theme
        end
        subgraph "styles"
            styleConfig["style.json"]:::theme
            cssOverride["vtex.store-components.css"]:::theme
        end
        docs["README.md"]:::theme
    end

    manifest -->|"declare deps"| vtexStore
    manifest -->|"declare deps"| sitemapService
    blockHome -->|"assemble blocks"| storeFramework
    blockProduct -->|"assemble blocks"| storeFramework
    blockSearch -->|"assemble blocks"| storeFramework
    blockHeader -->|"assemble blocks"| storeFramework
    blockFooter -->|"assemble blocks"| storeFramework
    blockDefault -->|"assemble blocks"| storeFramework
    styleConfig -->|"inject style tokens"| storeFramework
    cssOverride -->|"inject CSS overrides"| storeFramework

    subgraph "VTEX IO Platform"
        storeFramework["Store Framework"]:::platform
        vtexStore["vtex.store"]:::platform
        sitemapService["vtex.store-sitemap"]:::platform
        CDN[(VTEX CDN)]:::cdn
    end

    storeFramework -->|"deploy UI assets"| CDN

    subgraph "End User"
        Browser["Browser"]:::enduser
    end

    Browser -->|"HTTP GET"| CDN
    CDN -->|"serve assets"| Browser
    Browser -->|"search/add cart"| vtexStore
    Browser -->|"route lookup"| sitemapService

    click manifest "https://github.com/vtex-apps/minimum-boilerplate-theme/blob/master/manifest.json"
    click blockHome "https://github.com/vtex-apps/minimum-boilerplate-theme/blob/master/store/blocks/home.jsonc"
    click blockProduct "https://github.com/vtex-apps/minimum-boilerplate-theme/blob/master/store/blocks/product.jsonc"
    click blockSearch "https://github.com/vtex-apps/minimum-boilerplate-theme/blob/master/store/blocks/search.jsonc"
    click blockHeader "https://github.com/vtex-apps/minimum-boilerplate-theme/blob/master/store/blocks/header.jsonc"
    click blockFooter "https://github.com/vtex-apps/minimum-boilerplate-theme/blob/master/store/blocks/footer.jsonc"
    click blockDefault "https://github.com/vtex-apps/minimum-boilerplate-theme/blob/master/store/blocks/default.jsonc"
    click styleConfig "https://github.com/vtex-apps/minimum-boilerplate-theme/blob/master/styles/configs/style.json"
    click cssOverride "https://github.com/vtex-apps/minimum-boilerplate-theme/blob/master/styles/css/vtex.store-components.css"
    click docs "https://github.com/vtex-apps/minimum-boilerplate-theme/blob/master/docs/README.md"

    classDef theme fill:#cfe2f3,stroke:#0b5394
    classDef platform fill:#d9ead3,stroke:#38761d
    classDef developer fill:#fce5cd,stroke:#e69138
    classDef enduser fill:#ead1dc,stroke:#c27ba0
    classDef cdn fill:#d9ead3,stroke:#38761d
```
