# sprksoft/smpp architecture

> Architecture diagram of the GitHub repository sprksoft/smpp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sprksoft/smpp
- Repository: https://github.com/sprksoft/smpp
- Video tour (about a minute): https://gitdiagram.com/sprksoft/smpp/video

## Overview

1. **Project shape**
   - This is a **Chrome extension** for Smartschool, not a standalone app.
   - The source of truth is under `src/` in TypeScript/CSS, and the packaged extension lives under `extension/`.
   - The README and file layout show a product focused on **page enhancement, customization, widgets, and small interactive features**.

2. **Extension entry points**
   - `extension/manifest.json` defines the browser extension wiring.
   - `extension/index.js`, `extension/inject.js`, and `extension/background-scripts/index.js` are the runtime entry points that run in different extension contexts.
   - `src/index.ts` and `src/background-scripts/index.ts` are the corresponding source-level entry points.

3. **Background vs. page-injected logic**
   - The architecture is split between:
     - **background scripts** for persistence, shared state, data loading, and any API-style interactions
     - **content/page scripts** for changing Smartschool’s UI directly
   - This boundary matters because many features need page DOM access, while settings/theme data are centralized elsewhere.

4. **Main Smartschool feature layer**
   - `src/main-features/` contains the core Smartschool enhancement logic.
   - Subsystems here map closely to user-visible feature groups from the README:
     - `appearance/` for themes, background images, weather effects, and UI styling
     - `quick-menu/` for the `:` command-style shortcut menu
     - `settings/` for in-app settings panels
     - `globalchat.ts`, `keybinds.ts`, `profile.ts` for cross-page behavior and user interaction
     - `modules/` for reusable page modules such as images and windows

5. **Widget system**
   - `src/widgets/` implements dashboard widgets such as:
     - calendar
     - assignments
     - planner
     - plant
     - weather
     - De Lijn
     - tutorial/widget helpers
     - photo widget
     - clock
   - `src/widgets/widgets.ts` looks like the coordinating layer for registering and rendering widgets.
   - These widgets likely consume data from background scripts or page context and render into the Smartschool dashboard.

6. **Games subsystem**
   - `src/games/` contains embedded mini-games:
     - snake
     - tetris
     - pong
     - breakout
     - flappy
     - space-invaders
   - `src/games/games.ts` likely acts as the launcher or registry.
   - This is a self-contained feature area, mostly UI/game logic rather than Smartschool integration logic.

7. **Fixes and compatibility layer**
   - `src/fixes-utils/` and `src/styles/fixes/` are the “Smartschool fixes” layer.
   - These files appear to patch or normalize different Smartschool pages such as login, results, messages, planner, navigation, and start page.
   - The repo is not just additive; it also **repairs or reshapes existing Smartschool screens** so the extension’s features fit consistently.

8. **Styling architecture**
   - Styles are split between:
     - `src/styles/fixes/` for page-specific overrides
     - `src/styles/smpp-styles/` for Smartschool++ UI components and widgets
   - The extension also contains media assets in `extension/media/`, including icons and theme backgrounds.
   - This suggests the UI is highly CSS-driven, with JavaScript coordinating behavior and state.

9. **Shared data and settings**
   - Background data files in `extension/background-scripts/data/` include:
     - default settings
     - theme definitions
     - theme categories
     - plant defaults
     - De Lijn color data
   - `src/background-scripts/settings.ts`, `themes.ts`, and `json-loader.ts` indicate a structured configuration layer that loads static JSON and persists user preferences.
   - User customization likely flows from settings UI → background persistence → feature modules/widgets consume the updated state.

10. **Background services and external integration**
   - `src/background-scripts/api-background-script.ts` and `theme_share_api.ts` suggest network-backed features, especially around theme sharing.
   - `data-background-script.ts` likely serves shared data to page scripts or manages runtime data hydration.
   - This is the main boundary for anything that must survive page reloads or does not belong in the Smartschool DOM.

11. **Build and packaging pipeline**
   - The repo uses TypeScript (`tsconfig.json`) plus build tooling under `build/`.
   - `build/build.py`, `build/ff_build.sh`, and release scripts indicate a packaging process that assembles the distributable extension from source.
   - The presence of a populated `extension/` directory suggests build output is checked in or generated for distribution.

12. **Overall runtime flow**
   - On browser startup, the extension loads background logic.
   - When Smartschool pages open, injected scripts and styles modify the page, mount widgets, add quick menu behavior, and apply themes/fixes.
   - User actions in settings or widgets feed back into background storage, which then influences future page loads and shared features like themes or plant state.

Main entry points: [`src/main-features/main.ts`](https://github.com/sprksoft/smpp/blob/main/src/main-features/main.ts) (Main runtime), [`src/background-scripts/index.ts`](https://github.com/sprksoft/smpp/blob/main/src/background-scripts/index.ts) (Bg entry), [`extension/manifest.json`](https://github.com/sprksoft/smpp/blob/main/extension/manifest.json) (Manifest), [`src/index.ts`](https://github.com/sprksoft/smpp/blob/main/src/index.ts) (Source entry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime_extension["Extension runtime"]
  node_extension_manifest["Manifest<br/>extension config<br/>[manifest.json]"]
  node_extension_background_js["Background JS<br/>extension runtime<br/>[index.js]"]
  node_extension_inject_js["Inject JS<br/>extension runtime<br/>[inject.js]"]
  node_extension_index_js["Main JS<br/>extension runtime<br/>[index.js]"]
end

subgraph group_runtime_source["Source runtime"]
  node_source_index_ts["Source entry<br/>app entrypoint<br/>[index.ts]"]
  node_source_background_index_ts["Bg entry<br/>background entrypoint<br/>[index.ts]"]
  node_background_data["Data sync<br/>background service"]
  node_background_settings["Settings store<br/>background service<br/>[settings.ts]"]
  node_background_themes["Theme store<br/>background service<br/>[themes.ts]"]
  node_background_api["API bridge<br/>network service"]
end

subgraph group_feature_ui["Feature surfaces"]
  node_main_shell["Main runtime<br/>page orchestrator<br/>[main.ts]"]
  node_appearance["Appearance<br/>ui subsystem"]
  node_quick_menu["Quick menu<br/>command palette"]
  node_settings_ui["Settings UI<br/>settings surface"]
  node_modules["Page modules<br/>ui helpers"]
  node_widgets_core["Widgets<br/>widget system<br/>[widgets.ts]"]
  node_games_core["Games<br/>mini-game suite<br/>[games.ts]"]
  node_fixes_layer["Fixes layer<br/>compatibility layer"]
  node_styles_fixes["Fix styles<br/>stylesheet set"]
  node_styles_smpp["SMPP styles<br/>stylesheet set"]
  node_widgets_data["Widget pages<br/>dashboard widgets"]
  node_games_data["Game modules<br/>game implementations"]
end

subgraph group_shared_data["Shared data"]
  node_shared_json[("JSON data<br/>static config")]
end

node_extension_manifest -->|"registers"| node_extension_background_js
node_extension_manifest -->|"injects"| node_extension_inject_js
node_extension_manifest -->|"boots"| node_extension_index_js
node_extension_index_js -.->|"mirrors"| node_source_index_ts
node_extension_background_js -.->|"mirrors"| node_source_background_index_ts
node_source_index_ts -->|"starts"| node_main_shell
node_source_index_ts -->|"applies"| node_fixes_layer
node_source_background_index_ts -->|"runs"| node_background_data
node_source_background_index_ts -->|"persists"| node_background_settings
node_source_background_index_ts -->|"serves"| node_background_themes
node_source_background_index_ts -->|"connects"| node_background_api
node_background_data -->|"loads"| node_shared_json
node_background_settings -->|"defaults"| node_shared_json
node_background_themes -->|"reads"| node_shared_json
node_main_shell -->|"orchestrates"| node_appearance
node_main_shell -->|"wires"| node_quick_menu
node_main_shell -->|"opens"| node_settings_ui
node_main_shell -->|"uses"| node_modules
node_main_shell -->|"mounts"| node_widgets_core
node_main_shell -->|"hosts"| node_games_core
node_main_shell -->|"patches"| node_fixes_layer
node_appearance -->|"styles"| node_styles_smpp
node_fixes_layer -->|"supports"| node_styles_fixes
node_widgets_core -->|"registers"| node_widgets_data
node_widgets_core -->|"styles"| node_styles_smpp
node_games_core -->|"launches"| node_games_data
node_games_core -->|"styles"| node_styles_smpp
node_settings_ui -->|"reads/writes"| node_background_settings
node_appearance -->|"consumes"| node_background_themes

click node_extension_manifest "https://github.com/sprksoft/smpp/blob/main/extension/manifest.json"
click node_extension_background_js "https://github.com/sprksoft/smpp/blob/main/extension/background-scripts/index.js"
click node_extension_inject_js "https://github.com/sprksoft/smpp/blob/main/extension/inject.js"
click node_extension_index_js "https://github.com/sprksoft/smpp/blob/main/extension/index.js"
click node_source_index_ts "https://github.com/sprksoft/smpp/blob/main/src/index.ts"
click node_source_background_index_ts "https://github.com/sprksoft/smpp/blob/main/src/background-scripts/index.ts"
click node_background_data "https://github.com/sprksoft/smpp/blob/main/src/background-scripts/data-background-script.ts"
click node_background_settings "https://github.com/sprksoft/smpp/blob/main/src/background-scripts/settings.ts"
click node_background_themes "https://github.com/sprksoft/smpp/blob/main/src/background-scripts/themes.ts"
click node_background_api "https://github.com/sprksoft/smpp/blob/main/src/background-scripts/api-background-script.ts"
click node_main_shell "https://github.com/sprksoft/smpp/blob/main/src/main-features/main.ts"
click node_appearance "https://github.com/sprksoft/smpp/tree/main/src/main-features/appearance"
click node_quick_menu "https://github.com/sprksoft/smpp/tree/main/src/main-features/quick-menu"
click node_settings_ui "https://github.com/sprksoft/smpp/tree/main/src/main-features/settings"
click node_modules "https://github.com/sprksoft/smpp/tree/main/src/main-features/modules"
click node_widgets_core "https://github.com/sprksoft/smpp/blob/main/src/widgets/widgets.ts"
click node_games_core "https://github.com/sprksoft/smpp/blob/main/src/games/games.ts"
click node_fixes_layer "https://github.com/sprksoft/smpp/tree/main/src/fixes-utils"
click node_styles_fixes "https://github.com/sprksoft/smpp/tree/main/src/styles/fixes"
click node_styles_smpp "https://github.com/sprksoft/smpp/tree/main/src/styles/smpp-styles"
click node_widgets_data "https://github.com/sprksoft/smpp/tree/main/src/widgets"
click node_games_data "https://github.com/sprksoft/smpp/tree/main/src/games"
click node_shared_json "https://github.com/sprksoft/smpp/tree/main/extension/background-scripts/data"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_extension_manifest,node_extension_background_js,node_extension_inject_js,node_extension_index_js toneBlue
class node_source_index_ts,node_source_background_index_ts,node_background_data,node_background_settings,node_background_themes,node_background_api toneAmber
class node_main_shell,node_appearance,node_quick_menu,node_settings_ui,node_modules,node_widgets_core,node_games_core,node_fixes_layer,node_styles_fixes,node_styles_smpp,node_widgets_data,node_games_data toneMint
class node_shared_json toneRose
```

## Components

### Extension runtime

Packaged Chrome extension entrypoints and assets

- [Manifest](https://github.com/sprksoft/smpp/blob/main/extension/manifest.json): extension config · Browser extension wiring and permissions · `extension/manifest.json`
- [Background JS](https://github.com/sprksoft/smpp/blob/main/extension/background-scripts/index.js): extension runtime · Packaged background entrypoint · `extension/background-scripts/index.js`
- [Inject JS](https://github.com/sprksoft/smpp/blob/main/extension/inject.js): extension runtime · Packaged page-injection entrypoint · `extension/inject.js`
- [Main JS](https://github.com/sprksoft/smpp/blob/main/extension/index.js): extension runtime · Packaged top-level extension entrypoint · `extension/index.js`

### Source runtime

TypeScript sources for background and injected page logic

- [Source entry](https://github.com/sprksoft/smpp/blob/main/src/index.ts): app entrypoint · Source-level extension bootstrap · `src/index.ts`
- [Bg entry](https://github.com/sprksoft/smpp/blob/main/src/background-scripts/index.ts): background entrypoint · Source-level background bootstrap · `src/background-scripts/index.ts`
- [Data sync](https://github.com/sprksoft/smpp/blob/main/src/background-scripts/data-background-script.ts): background service · Shared runtime data hydration and delivery · `src/background-scripts/data-background-script.ts`
- [Settings store](https://github.com/sprksoft/smpp/blob/main/src/background-scripts/settings.ts): background service · Persistent settings and defaults · `src/background-scripts/settings.ts`
- [Theme store](https://github.com/sprksoft/smpp/blob/main/src/background-scripts/themes.ts): background service · Theme data and theme state management · `src/background-scripts/themes.ts`
- [API bridge](https://github.com/sprksoft/smpp/blob/main/src/background-scripts/api-background-script.ts): network service · External API and theme-sharing interactions · `src/background-scripts/api-background-script.ts`

### Feature surfaces

User-facing Smartschool enhancements, widgets, games, and styles

- [Main runtime](https://github.com/sprksoft/smpp/blob/main/src/main-features/main.ts): page orchestrator · Coordinates page-injected Smartschool enhancements · `src/main-features/main.ts`
- [Appearance](https://github.com/sprksoft/smpp/tree/main/src/main-features/appearance): ui subsystem · Themes, backgrounds, weather effects, and visual styling · `src/main-features/appearance`
- [Quick menu](https://github.com/sprksoft/smpp/tree/main/src/main-features/quick-menu): command palette · Colon-command style shortcut menu · `src/main-features/quick-menu`
- [Settings UI](https://github.com/sprksoft/smpp/tree/main/src/main-features/settings): settings surface · In-app settings panels and quick settings · `src/main-features/settings`
- [Page modules](https://github.com/sprksoft/smpp/tree/main/src/main-features/modules): ui helpers · Reusable DOM modules for images and windows · `src/main-features/modules`
- [Widgets](https://github.com/sprksoft/smpp/blob/main/src/widgets/widgets.ts): widget system · Dashboard widget registry and rendering · `src/widgets/widgets.ts`
- [Games](https://github.com/sprksoft/smpp/blob/main/src/games/games.ts): mini-game suite · Launcher and registry for embedded games · `src/games/games.ts`
- [Fixes layer](https://github.com/sprksoft/smpp/tree/main/src/fixes-utils): compatibility layer · Page-specific Smartschool patches and normalization · `src/fixes-utils`
- [Fix styles](https://github.com/sprksoft/smpp/tree/main/src/styles/fixes): stylesheet set · Page-specific CSS overrides · `src/styles/fixes`
- [SMPP styles](https://github.com/sprksoft/smpp/tree/main/src/styles/smpp-styles): stylesheet set · Component and widget styling · `src/styles/smpp-styles`
- [Widget pages](https://github.com/sprksoft/smpp/tree/main/src/widgets): dashboard widgets · Calendar, assignments, planner, plant, weather, De Lijn, photo, clock, tutorial · `src/widgets`
- [Game modules](https://github.com/sprksoft/smpp/tree/main/src/games): game implementations · Snake, Tetris, Pong, Breakout, Flappy, Space Invaders · `src/games`

### Shared data

Configuration, theme data, and build-related support

- [JSON data](https://github.com/sprksoft/smpp/tree/main/extension/background-scripts/data): static config · Default settings, themes, plant data, and line colors · `extension/background-scripts/data`

## Connections

- Manifest → Background JS: registers · Declares background runtime
- Manifest → Inject JS: injects · Attaches page script to Smartschool pages
- Manifest → Main JS: boots · Loads top-level extension code
- Main JS → Source entry: mirrors · Packaged entry maps to source entry
- Background JS → Bg entry: mirrors · Packaged background maps to source background entry
- Source entry → Main runtime: starts · Initializes injected runtime
- Source entry → Fixes layer: applies · Loads compatibility patches for Smartschool pages
- Bg entry → Data sync: runs · Provides shared runtime data
- Bg entry → Settings store: persists · Stores and serves user preferences
- Bg entry → Theme store: serves · Exposes theme state and definitions
- Bg entry → API bridge: connects · Handles external/network-backed features
- Data sync → JSON data: loads · Hydrates runtime data from static JSON
- Settings store → JSON data: defaults · Uses default settings templates
- Theme store → JSON data: reads · Loads theme catalogs and categories
- Main runtime → Appearance: orchestrates · Coordinates theme and visual enhancements
- Main runtime → Quick menu: wires · Enables command-style menu interaction
- Main runtime → Settings UI: opens · Mounts settings panels
- Main runtime → Page modules: uses · Shares reusable page modules
- Main runtime → Widgets: mounts · Injects dashboard widgets into page UI
- Main runtime → Games: hosts · Launches embedded mini-games
- Main runtime → Fixes layer: patches · Applies page-specific fixes during runtime
- Appearance → SMPP styles: styles · Relies on shared component styling
- Fixes layer → Fix styles: supports · Pairs page fixes with CSS overrides
- Widgets → Widget pages: registers · Coordinates widget implementations
- Widgets → SMPP styles: styles · Uses widget and dashboard styles
- Games → Game modules: launches · Dispatches to individual game implementations
- Games → SMPP styles: styles · Uses game-specific presentation styles
- Settings UI → Settings store: reads/writes · Synchronizes user settings with background storage
- Appearance → Theme store: consumes · Applies shared theme definitions
