# mpc-ou/mpc-extension architecture

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

- Interactive diagram: https://gitdiagram.com/mpc-ou/mpc-extension
- Repository: https://github.com/mpc-ou/mpc-extension

## Overview

##### Project Type and Purpose
- This is a browser extension (Chrome/Chromium-based) built with TypeScript and Vite.

##### File Structure Analysis
- Top-level: configuration files (.gitignore, tsconfig.json, vite.config.ts), build scripts (scripts/updateManifest.ts), and entry HTML (index.html).
- public/: static assets—extension manifest (manifest.json), Chart.js library, xlsx library, images.
- src/: main TypeScript code.
- app.ts: orchestrator for initialization.
- index.ts: content script entry.
- info.ts & statistics.ts: feature modules for info panel and statistics view.
- constants/: default values, app-wide constants.
- data/: domain data (IT, major curricula).
- utils/: DOM helpers, query utilities, global type declarations.
- css/: styling for base, app, info, statistics views.
- scripts/: utility to update manifest before build.
- package.json & pnpm-lock.yaml: dependencies and scripts.

##### README Insights
- Uses pnpm for build.
- After build, dist/ contains the extension bundle.
- Loaded as an unpacked extension, injects into https://tienichsv.ou.edu.vn, on the “điểm” tab.

##### Main Components
a. Content Script (src/index.ts)
b. Core Application Module (src/app.ts)
c. Feature Modules
- Info Panel (src/info.ts + CSS)
- Statistics Dashboard (src/statistics.ts + CSS + Chart.js)
d. Data Layer (src/data/*, src/constants/*)
e. Utility Layer (src/utils/*)
f. Static Asset Providers (Chart.js, xlsx, images in public/)
g. Extension Host (Chrome extension runtime)
h. External Host Page (OU student portal)

##### Relationships & Interactions
- On page load at target URL, Chrome runtime injects content script.
- Content script → invokes app.ts → initializes data modules & utils.
- app.ts orchestrates rendering:
- Loads data from data layer → passes to feature modules.
- Info module reads DOM via utils → overlays student info panel.
- Statistics module computes GPA, draws charts via Chart.js.
- Feature modules may export to Excel via xlsx library.
- All DOM manipulations use globalDOM utilities.
- Assets (CSS, chart.js, xlsx) served from extension’s public folder as defined in manifest.

##### Architectural Patterns & Tech Stack
- Modular single-page script (no backend).
- Separation of concerns:
- Content script vs. feature modules vs. data vs. utils.
- Build tool: Vite + pnpm.
- Libraries: Chart.js for charting, SheetJS (xlsx) for export.
- Styling: plain CSS per feature.

##### Essential Elements
- Clear component names matching file names.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Build and Packaging
    Build["Build: Vite + pnpm"]:::build
    ViteBundle["Bundle: dist/"]:::build
    Build -->|"bundles"| ViteBundle

    %% Chrome Extension Boundary
    subgraph "Chrome Extension"
        direction TB
        Manifest["Manifest (public/manifest.json)"]:::config
        ContentScript["Content Script\n(src/index.ts)"]:::feature
        AppModule["Core App Module\n(src/app.ts)"]:::feature
        subgraph "Feature Modules"
            direction TB
            InfoModule["Info Panel Module\n(src/info.ts)"]:::feature
            StatsModule["Statistics Dashboard Module\n(src/statistics.ts)"]:::feature
        end
        subgraph "Data Layer"
            direction TB
            DataIT["IT Curriculum\n(src/data/it.ts)"]:::data
            DataMajor["Major Curriculum\n(src/data/major.ts)"]:::data
            ConstantsDefault["Constants Default\n(src/constants/default.ts)"]:::data
            ConstantsIndex["Constants Index\n(src/constants/index.ts)"]:::data
        end
        subgraph "Utility Layer"
            direction TB
            UtilGlobalDOM["Global DOM Helpers\n(src/utils/globalDOM.ts)"]:::util
            UtilQuery["Query Utilities\n(src/utils/query.ts)"]:::util
            UtilIndex["Aggregator Index\n(src/utils/index.ts)"]:::util
        end
        subgraph "Styles & Static Assets"
            direction TB
            BaseCSS["Base & App Styles\n(src/css/base.css,\nsrc/css/app.css)"]:::config
            InfoCSS["Info Styles\n(src/css/info.css)"]:::config
            StatsCSS["Stats Styles\n(src/css/statistics.css)"]:::config
            ChartJS["Chart.js Library\n(public/chartjs/chart.js)"]:::third
            XLSX["XLSX Library\n(public/xlsx)"]:::third
            Images["Static Images\n(public/img)"]:::config
        end
        UpdateScript["Manifest Update Script\n(scripts/updateManifest.ts)"]:::build
    end

    %% External Entities
    ChromeRuntime["Chrome Extension Runtime"]:::config
    ExternalPage["OU Student Portal\n(https://tienichsv.ou.edu.vn)"]:::config

    %% Build to Extension
    ViteBundle -->|"output to"| Manifest
    ViteBundle -->|"output to"| ContentScript
    ViteBundle -->|"output to"| AppModule
    ViteBundle -->|"output to"| InfoModule
    ViteBundle -->|"output to"| StatsModule

    %% Runtime Injection
    ChromeRuntime -->|"injects"| ContentScript

    %% Initialization Flow
    ContentScript -->|"initialize"| AppModule
    AppModule -->|"load data"| DataIT
    AppModule -->|"load data"| DataMajor
    AppModule -->|"load constants"| ConstantsDefault
    AppModule -->|"load constants"| ConstantsIndex
    AppModule -->|"init utils"| UtilGlobalDOM
    AppModule -->|"init utils"| UtilQuery
    AppModule -->|"init utils"| UtilIndex
    AppModule -->|"render"| InfoModule
    AppModule -->|"render"| StatsModule

    %% Feature Interactions
    InfoModule -->|"DOM inject/read"| ExternalPage
    StatsModule -->|"chart draw"| ChartJS
    StatsModule -->|"export XLSX"| XLSX
    StatsModule -->|"DOM inject/read"| ExternalPage

    %% Styling Links
    InfoModule --> InfoCSS
    StatsModule --> StatsCSS
    AppModule --> BaseCSS

    %% Assets Access
    InfoModule --> Images
    StatsModule --> Images

    %% Legend
    subgraph "Legend"
        direction TB
        F["Feature Module"]:::feature
        D["Data/Constants"]:::data
        U["Utility"]:::util
        T["Third-Party"]:::third
        C["Configuration/Styles"]:::config
        B["Build"]:::build
    end

    %% Click Events
    click ContentScript "https://github.com/mpc-ou/mpc-extension/blob/main/src/index.ts"
    click AppModule "https://github.com/mpc-ou/mpc-extension/blob/main/src/app.ts"
    click InfoModule "https://github.com/mpc-ou/mpc-extension/blob/main/src/info.ts"
    click InfoCSS "https://github.com/mpc-ou/mpc-extension/blob/main/src/css/info.css"
    click StatsModule "https://github.com/mpc-ou/mpc-extension/blob/main/src/statistics.ts"
    click StatsCSS "https://github.com/mpc-ou/mpc-extension/blob/main/src/css/statistics.css"
    click DataIT "https://github.com/mpc-ou/mpc-extension/blob/main/src/data/it.ts"
    click DataMajor "https://github.com/mpc-ou/mpc-extension/blob/main/src/data/major.ts"
    click ConstantsDefault "https://github.com/mpc-ou/mpc-extension/blob/main/src/constants/default.ts"
    click ConstantsIndex "https://github.com/mpc-ou/mpc-extension/blob/main/src/constants/index.ts"
    click UtilGlobalDOM "https://github.com/mpc-ou/mpc-extension/blob/main/src/utils/globalDOM.ts"
    click UtilQuery "https://github.com/mpc-ou/mpc-extension/blob/main/src/utils/query.ts"
    click UtilIndex "https://github.com/mpc-ou/mpc-extension/blob/main/src/utils/index.ts"
    click BaseCSS "https://github.com/mpc-ou/mpc-extension/blob/main/src/css/base.css"
    click BaseCSS "https://github.com/mpc-ou/mpc-extension/blob/main/src/css/app.css"
    click Manifest "https://github.com/mpc-ou/mpc-extension/blob/main/public/manifest.json"
    click ChartJS "https://github.com/mpc-ou/mpc-extension/blob/main/public/chartjs/chart.js"
    click XLSX "https://github.com/mpc-ou/mpc-extension/tree/main/public/xlsx"
    click Images "https://github.com/mpc-ou/mpc-extension/tree/main/public/img"
    click UpdateScript "https://github.com/mpc-ou/mpc-extension/blob/main/scripts/updateManifest.ts"
    click Build "https://github.com/mpc-ou/mpc-extension/blob/main/vite.config.ts"
    click ViteBundle "https://github.com/mpc-ou/mpc-extension/blob/main/index.html"

    %% Styles
    classDef util fill:#D3D3D3,stroke:#333
    classDef data fill:#D3D3D3,stroke:#333
    classDef feature fill:#ADD8E6,stroke:#036,stroke-width:2px
    classDef third fill:#FFA500,stroke:#333
    classDef config fill:#FFE4B5,stroke:#333
    classDef build fill:#E0FFFF,stroke:#333,stroke-dasharray: 5 5
```
