# openedx/frontend-template-site architecture

> Architecture diagram of the GitHub repository openedx/frontend-template-site, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/openedx/frontend-template-site
- Repository: https://github.com/openedx/frontend-template-site

## Overview

##### Project type and purpose
- This is a frontend‐only “template site” for Open edX micro-frontends. It provides a static HTML/CSS/JS scaffold, build and dev configurations, and a sample SCSS entrypoint.
- Its primary use case is to be cloned as a starting point for new Open edX‐branded frontend sites, with minimal custom code.

##### File structure
- Top‐level config files:
- package.json / package-lock.json – npm dependencies and scripts
- tsconfig.json – TypeScript compiler settings
- eslint.config.js – lint rules
- .nvmrc – Node version (v20.x)
- catalog-info.yaml – Backstage metadata
- site.config.dev.tsx & site.config.build.tsx – development & build configuration (entrypoints for the Open edX micro-frontend build tooling)
- Public assets:
- public/index.html – static HTML template and root div for mounting JS
- Source assets:
- src/site.scss – global styles (compiled by the build tool)
- app.d.ts – TypeScript declarations
- No backend code: everything is bundled into static assets.

##### README for additional insights
- Emphasizes climate of use: clone, rename, update index.html title, set PORT in site.config.dev.tsx, npm run dev, npm run build.
- Mentions internationalization hook via frontend-base, but no direct i18n code here.
- CI badges indicate GitHub Actions are in place for build/checks (though workflow files aren’t in this template).

##### Main components & their relationships
a. Development environment
- Developer workstation with Node v20.x & nvm
- Local clone of GitHub repo
- npm scripts: “dev” → starts dev server; “build” → runs production build
- site.config.dev.tsx configures webpack‐dev‐server on port (default 8080)
- site.config.build.tsx configures production bundling (SCSS → CSS, TSX → JS)
b. Version control & CI
- GitHub repo (template) with catalog-info metadata
- GitHub Actions CI: lint, typecheck, build, test, codecov
c. Build system
- Underlying micro-frontend build tool (likely webpack under the hood)
- Input: src/site.scss, public/index.html, TypeScript config & declarations
- Output: static assets (JS bundles, CSS, assets)
d. Deployment & hosting
- Artifacts deployed to a static host/CDN (e.g., S3 + CloudFront or any static site host)
- Clients (browsers) request index.html, load JS bundles and CSS
- Optional integration with Open edX LMS via micro-frontend mounting

##### Architectural patterns & design principles
- Single‐Page Application (SPA) or micro-frontend shell – public/index.html provides one “shell” page
- Configuration‐driven build – site.config.{dev,build}.tsx allow per‐site customization without touching core toolchain
- Strict separation:
- config (site.config.*) vs
- source assets (SCSS, types) vs
- public assets (index.html)
- Type safety via TypeScript and declarations (app.d.ts)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Developer and Version Control
    Developer["Developer Local Environment"]:::user
    GitHub["GitHub Repo & CI"]:::external
    CI["GitHub Actions CI"]:::process

    %% Config Files Group
    subgraph "Config Files" 
        direction TB
        NVM[".nvmrc"]:::config
        Catalog["catalog-info.yaml"]:::config
        ESLint["eslint.config.js"]:::config
        TSConfig["tsconfig.json"]:::config
        PackageJSON["package.json"]:::config
        PackageLock["package-lock.json"]:::config
        AppDT["app.d.ts"]:::config
        DevConfig["site.config.dev.tsx"]:::config
        BuildConfig["site.config.build.tsx"]:::config
    end

    %% Source Assets Group
    subgraph "Source Assets"
        direction TB
        HTML["public/index.html"]:::config
        SCSS["src/site.scss"]:::config
    end

    %% Build Toolchain
    Build["Build Toolchain\n(npm run dev/build)"]:::process

    %% Hosting and Users
    Hosting["Static Host / CDN"]:::external
    Browser["End Users / Browsers"]:::user

    %% Flows
    Developer -->|push & PR| GitHub
    GitHub -->|triggers| CI
    CI -->|runs build & tests| Build

    %% Developer local build
    Developer -->|npm run dev/build| Build

    %% Inputs to build
    NVM --> Build
    Catalog --> Build
    ESLint --> Build
    TSConfig --> Build
    PackageJSON --> Build
    PackageLock --> Build
    AppDT --> Build
    DevConfig --> Build
    BuildConfig --> Build
    HTML --> Build
    SCSS --> Build

    %% Deployment and serving
    Build -->|artifacts| Hosting
    Hosting -->|serves index.html, JS, CSS| Browser

    %% Click Events
    click NVM "https://github.com/openedx/frontend-template-site/blob/main/.nvmrc"
    click Catalog "https://github.com/openedx/frontend-template-site/blob/main/catalog-info.yaml"
    click ESLint "https://github.com/openedx/frontend-template-site/blob/main/eslint.config.js"
    click TSConfig "https://github.com/openedx/frontend-template-site/blob/main/tsconfig.json"
    click PackageJSON "https://github.com/openedx/frontend-template-site/blob/main/package.json"
    click PackageLock "https://github.com/openedx/frontend-template-site/blob/main/package-lock.json"
    click AppDT "https://github.com/openedx/frontend-template-site/blob/main/app.d.ts"
    click DevConfig "https://github.com/openedx/frontend-template-site/blob/main/site.config.dev.tsx"
    click BuildConfig "https://github.com/openedx/frontend-template-site/blob/main/site.config.build.tsx"
    click HTML "https://github.com/openedx/frontend-template-site/blob/main/public/index.html"
    click SCSS "https://github.com/openedx/frontend-template-site/blob/main/src/site.scss"

    %% Styles
    classDef config fill:#cfe2f3,stroke:#036,stroke-width:1px;
    classDef process fill:#d9ead3,stroke:#38761d,stroke-width:1px;
    classDef external fill:#f9cb9c,stroke:#e69138,stroke-width:1px;
    classDef user fill:#e0e0e0,stroke:#888888,stroke-width:1px;
```
