How sprksoft/smpp works
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: main.ts Main runtime · background-scripts/index.ts Bg entry · manifest.json Manifest · src/index.ts Source entry
Components 23
Extension runtime
Packaged Chrome extension entrypoints and assets
- Manifest · Browser extension wiring and permissions
extension/manifest.json - Background JS · Packaged background entrypoint
extension/background-scripts/index.js - Inject JS · Packaged page-injection entrypoint
extension/inject.js - Main JS · Packaged top-level extension entrypoint
extension/index.js
Source runtime
TypeScript sources for background and injected page logic
- Source entry · Source-level extension bootstrap
src/index.ts - Bg entry · Source-level background bootstrap
src/background-scripts/index.ts - Data sync · Shared runtime data hydration and delivery
src/background-scripts/data-background-script.ts - Settings store · Persistent settings and defaults
src/background-scripts/settings.ts - Theme store · Theme data and theme state management
src/background-scripts/themes.ts - API bridge · 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 · Coordinates page-injected Smartschool enhancements
src/main-features/main.ts - Appearance · Themes, backgrounds, weather effects, and visual styling
src/main-features/appearance - Quick menu · Colon-command style shortcut menu
src/main-features/quick-menu - Settings UI · In-app settings panels and quick settings
src/main-features/settings - Page modules · Reusable DOM modules for images and windows
src/main-features/modules - Widgets · Dashboard widget registry and rendering
src/widgets/widgets.ts - Games · Launcher and registry for embedded games
src/games/games.ts - Fixes layer · Page-specific Smartschool patches and normalization
src/fixes-utils - Fix styles · Page-specific CSS overrides
src/styles/fixes - SMPP styles · Component and widget styling
src/styles/smpp-styles - Widget pages · Calendar, assignments, planner, plant, weather, De Lijn, photo, clock, tutorial
src/widgets - Game modules · Snake, Tetris, Pong, Breakout, Flappy, Space Invaders
src/games
Shared data
Configuration, theme data, and build-related support
- JSON data · Default settings, themes, plant data, and line colors
extension/background-scripts/data
Connections 29
- 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