# openedx/frontend-template-application architecture

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

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

## Overview

##### Project type and purpose
- This is a React-based micro-frontend template for the Open edX platform (“frontend-template-application”).
- Its goal is to provide a ready-to-use scaffold (including design tokens via Paragon, i18n support, feature-based organization) so teams can spin up new MFE components that plug into a devstack or Tutor-based LMS host.

##### File structure
- Top-level:
- Configuration & toolchain (.env*, .eslintrc.js, jest.config.js, webpack/module.config.js, Makefile)
- CI/CD pipelines under .github/workflows (lint, commit-lint, CI, version checks)
- docs/ (ADR decisions, how-tos, images)
- public/ (index.html shell)
- src/ (all application code)
- src organization:
- src/index.jsx + index.scss – application entrypoint
- feature folders under src/ following the Feature-Based Application Organization ADR (e.g., src/example)
- src/plugin-slots – extension point definitions (FooterSlot, etc.)
- src/i18n – internationalization initialization
- assets and styling under src/assets & src/*.scss
- Build & test: npm scripts (start, build, test), Webpack/Module Federation (via module.config.js), Jest for unit tests.

##### Key README insights
- It is a Template Repository (use “Use this template” to create your own MFE).
- Runs against Devstack or Tutor for backend LMS services.
- Relies on Node 18.x, Paragon design-token support, and the frontend-platform i18n module.
- Encourages feature-based directory structure and plugin-slot integration.

a. Main components
- Developer Workstation (git clone + npm start)
- Source Repository (GitHub)
- CI/CD (GitHub Actions workflows: lint, test, build, codecov)
- npm / Webpack build pipeline (npm run build → static asset artifacts)
- Development environment
– Devstack or Tutor (LMS backend containers)
– MFE Dev Server (Webpack Dev Server on localhost:8080)
- Production deployment
– Static asset host (e.g., CDN or LMS static files)
- Runtime in the Browser
– LMS Shell (host app)
– Micro-frontend container (Module Federation remoteEntry)
– Feature modules (e.g., ExamplePage)
– Plugin slots (FooterSlot extensions)
– i18n module + design tokens (Paragon)
b. Relationships & interactions
- Developer pushes to GitHub → triggers CI workflows → publishes build artifacts
- MFE Dev Server connects to Devstack/Tutor LMS (for API and shell)
- LMS Shell loads the MFE bundle via Module Federation at runtime
- Feature modules render into plugin-slots defined by the host
- i18n subsystem provides localized strings to UI components
c. Architectural patterns & principles
- Micro-frontends via Webpack Module Federation
- Feature-based folder organization (per ADR 0002)
- Plugin-slot extensibility
- Separation of concerns: config, build, src, docs, CI
d. Key technologies & frameworks
- React + ReactDOM
- Webpack (Module Federation)
- Paragon design tokens
- Jest + Testing Library
- GitHub Actions for CI
- Devstack / Tutor for backend host
- npm / Node 18.x

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Developer Tools & Workstation
    Developer["Developer Workstation"]:::dev
    GHRepo["Source Repository (GitHub)"]:::dev
    Developer -->|push code| GHRepo

    %% CI/CD Workflows
    subgraph "CI/CD Pipelines"
        CI["CI Workflow"]:::ci
        CL["Commit Linting"]:::ci
        Lock["Lockfile Version Check"]:::ci
        Browsers["Browserslist DB Update"]:::ci
    end
    GHRepo --> CI
    CI --> CL
    CI --> Lock
    CI --> Browsers

    Make["Makefile"]:::tool
    ESLint[".eslintrc.js"]:::tool
    JestCfg["jest.config.js"]:::tool
    CI --> Make
    CI --> ESLint
    CI --> JestCfg

    %% Source Code
    subgraph "Source Code (src)" 
        EP["Entry Point\nsrc/index.jsx"]:::code
        GS["Global Styles\nsrc/index.scss"]:::code
        i18n["i18n Initialization\nsrc/i18n/index.js"]:::code
        Assets["Static Assets\nsrc/assets/"]:::code
        SetupTest["Test Setup\nsrc/setupTest.js"]:::code
        subgraph "Feature Modules"
            ExPage["ExamplePage\nsrc/example/ExamplePage.jsx"]:::feature
            ExTest["ExamplePage Test\nsrc/example/ExamplePage.test.jsx"]:::feature
            ExStyle["Example Styles\nsrc/example/index.scss"]:::feature
        end
        subgraph "Plugin Slots"
            FSread["FooterSlot README\nsrc/plugin-slots/FooterSlot/README.md"]:::plugin
            FSimg["FooterSlot Images\nsrc/plugin-slots/FooterSlot/images"]:::plugin
        end
    end
    CI --> EP
    CI --> GS
    CI --> i18n
    CI --> Assets
    CI --> SetupTest

    %% Documentation
    subgraph "Documentation"
        ADR2["Feature-Based Org ADR\ndocs/decisions/0002-feature-based-application-organization.rst"]:::doc
        ADR1["ADR Records\ndocs/decisions/0001-record-architecture-decisions.rst"]:::doc
        README1["README.rst"]:::doc
        README2["README-template-frontend-app.rst"]:::doc
    end

    %% Build & Development Environment
    subgraph "Build & Dev Environment"
        webpack["Module Federation Config\nmodule.config.js.example"]:::tool
        DevServer["MFE Dev Server\nwebpack-dev-server"]:::runtime
    end
    CI --> webpack
    Developer -->|npm start| DevServer
    DevServer -->|connects to| Devstack

    %% Backend LMS Host
    subgraph "Backend LMS Host"
        Devstack["Devstack/Tutor LMS"]:::runtime
    end
    Devstack -->|provides APIs & shell| DevServer

    %% Production Deployment
    subgraph "Production"
        CDN["Static Asset Host (CDN/LMS)"]:::runtime
    end
    webpack -->|build artifacts| CDN
    Public["Public HTML Shell\npublic/index.html"]:::tool
    CDN --> Public

    %% Browser Runtime
    subgraph "Browser Runtime"
        LMSShell["LMS Shell (Host App)"]:::host
        MFECtn["MFE Container\nremoteEntry"]:::host
        FeatureRT["Feature Modules"]:::host
        SlotsRT["Plugin Slots"]:::host
        I18nRT["i18n & Paragon"]:::host
    end
    LMSShell -->|loads remoteEntry| MFECtn
    MFECtn -->|provides features| FeatureRT
    MFECtn -->|renders into| SlotsRT
    I18nRT -->|localization| FeatureRT

    %% Legend
    subgraph Legend
        direction LR
        A[Developer Tools & Workflows]:::dev --- B[CI/CD]:::ci --- C[Build/Dev]:::tool --- D[Runtime]:::runtime --- E[Browser]:::host
    end

    %% Click Events
    click EP "https://github.com/openedx/frontend-template-application/blob/master/src/index.jsx"
    click GS "https://github.com/openedx/frontend-template-application/blob/master/src/index.scss"
    click ExPage "https://github.com/openedx/frontend-template-application/blob/master/src/example/ExamplePage.jsx"
    click ExTest "https://github.com/openedx/frontend-template-application/blob/master/src/example/ExamplePage.test.jsx"
    click ExStyle "https://github.com/openedx/frontend-template-application/blob/master/src/example/index.scss"
    click ADR2 "https://github.com/openedx/frontend-template-application/blob/master/docs/decisions/0002-feature-based-application-organization.rst"
    click ADR1 "https://github.com/openedx/frontend-template-application/blob/master/docs/decisions/0001-record-architecture-decisions.rst"
    click README1 "https://github.com/openedx/frontend-template-application/blob/master/README.rst"
    click README2 "https://github.com/openedx/frontend-template-application/blob/master/README-template-frontend-app.rst"
    click FSread "https://github.com/openedx/frontend-template-application/blob/master/src/plugin-slots/FooterSlot/README.md"
    click FSimg "https://github.com/openedx/frontend-template-application/tree/master/src/plugin-slots/FooterSlot/images"
    click i18n "https://github.com/openedx/frontend-template-application/blob/master/src/i18n/index.js"
    click Assets "https://github.com/openedx/frontend-template-application/tree/master/src/assets/"
    click SetupTest "https://github.com/openedx/frontend-template-application/blob/master/src/setupTest.js"
    click JestCfg "https://github.com/openedx/frontend-template-application/blob/master/jest.config.js"
    click webpack "https://github.com/openedx/frontend-template-application/blob/master/module.config.js.example"
    click ESLint "https://github.com/openedx/frontend-template-application/blob/master/.eslintrc.js"
    click Makefile "https://github.com/openedx/frontend-template-application/tree/master/Makefile"
    click CI "https://github.com/openedx/frontend-template-application/blob/master/.github/workflows/ci.yml"
    click CL "https://github.com/openedx/frontend-template-application/blob/master/.github/workflows/commitlint.yml"
    click Lock "https://github.com/openedx/frontend-template-application/blob/master/.github/workflows/lockfileversion-check.yml"
    click Browsers "https://github.com/openedx/frontend-template-application/blob/master/.github/workflows/update-browserslist-db.yml"
    click Public "https://github.com/openedx/frontend-template-application/blob/master/public/index.html"

    %% Styles
    classDef dev fill:#D0E6FF,stroke:#0094FF
    classDef ci fill:#E2F8E9,stroke:#2D9C3A
    classDef tool fill:#FFF4E5,stroke:#F2C94C
    classDef code fill:#F0F5F9,stroke:#3892C1
    classDef feature fill:#F3E5F5,stroke:#9B51E0
    classDef plugin fill:#EDE7F6,stroke:#5F35B5
    classDef runtime fill:#FFEFEF,stroke:#EB5757
    classDef host fill:#F0FFF0,stroke:#27AE60
    classDef doc fill:#FDF6E3,stroke:#B58900
```
