BetterSEQTA+ Architecture¶

Hey there! 👋 New to the codebase and feeling a bit lost? Don't worry - this guide will help you understand how everything fits together!

Table of Contents¶

Overview
High-Level Architecture
Core Components
Plugin System
File Structure Explained
Data Flow
Browser Extension Basics

Overview¶

BetterSEQTA+ is a browser extension that enhances SEQTA Learn by: - Adding new features through a plugin system - Providing customizable themes and UI improvements - Offering better navigation and user experience

Think of it like this: SEQTA Learn + BetterSEQTA+ = Enhanced SEQTA Experience

High-Level Architecture¶

┌─────────────────────────────────────────────────────────────┐
│                    BROWSER EXTENSION                        │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  ┌─────────────────┐    ┌──────────────────┐                │
│  │  Background     │    │  Content Script  │                │
│  │  Script         │    │  (SEQTA.ts)      │                │
│  │                 │    │                  │                │
│  │  - Settings     │◄───┤  - Page Detection│                │
│  │  - Storage      │    │  - Plugin Loading│                │
│  │  - Updates      │    │  - UI Injection  │                │
│  └─────────────────┘    └──────────────────┘                │
│                                   │                         │
│                         ┌─────────▼─────────┐               │
│                         │   Plugin System   │               │
│                         │                   │               │
│                         │  ┌─────────────┐  │               │
│                         │  │ Built-in    │  │               │
│                         │  │ Plugins     │  │               │
│                         │  │             │  │               │
│                         │  │ - Themes    │  │               │
│                         │  │ - Search    │  │               │
│                         │  │ - Timetable │  │               │
│                         │  │ - etc...    │  │               │
│                         │  └─────────────┘  │               │
│                         └───────────────────┘               │
│                                   │                         │
│                         ┌─────────▼─────────┐               │
│                         │   Settings UI     │               │
│                         │   (Svelte App)    │               │
│                         │                   │               │
│                         │  - Plugin Config  │               │
│                         │  - Theme Creator  │               │
│                         │  - General Settings│              │
│                         └───────────────────┘               │
└─────────────────────────────────────────────────────────────┘
                                   │
                         ┌─────────▼─────────┐
                         │   SEQTA Learn     │
                         │   Website         │
                         └───────────────────┘

Core Components¶

1. Entry Point (`src/SEQTA.ts`)¶

This is where it all begins! When you visit a SEQTA page: 1. Detects if you're on a SEQTA Learn page 2. Injects our CSS styles 3. Changes the favicon to BetterSEQTA+ icon 4. Loads settings from storage 5. Initializes the plugin system

2. Plugin System (`src/plugins/`)¶

The heart of BetterSEQTA+! This is what makes it extensible: - Plugin Manager: Registers and manages all plugins - Built-in Plugins: Pre-made plugins (themes, search, etc.) - Plugin API: Provides plugins with tools to interact with SEQTA

3. Settings UI (`src/interface/`)¶

A Svelte application that lets users: - Enable/disable plugins - Configure plugin settings - Create custom themes - Browse the theme store

4. Background Script (`src/background.ts`)¶

Runs in the background and handles: - Extension-wide settings storage - Communication between different parts - Update notifications

Plugin System¶

Our plugin system is what makes BetterSEQTA+ so powerful. Here's how it works:

Plugin Lifecycle¶

Plugin Registration → Settings Loading → Plugin Initialization → Running → Cleanup

Built-in Plugins Overview¶

Plugin	What it does	Files
Themes	Custom CSS themes and backgrounds	`src/plugins/built-in/themes/`
Global Search	Search across all SEQTA content	`src/plugins/built-in/globalSearch/`
Timetable	Enhanced timetable features	`src/plugins/built-in/timetable/`
Profile Picture	Custom profile pictures	`src/plugins/built-in/profilePicture/`
Animated Background	Moving background animations	`src/plugins/built-in/animatedBackground/`

Creating a Plugin¶

Every plugin follows this structure:

const myPlugin: Plugin = {
  id: "unique-plugin-id",
  name: "Human Readable Name",
  description: "What does this plugin do?",
  version: "1.0.0",
  settings: { /* user configurable options */ },
  run: async (api) => {
    // Your plugin code goes here!
  }
};

File Structure Explained¶

src/
├── SEQTA.ts              # 🚀 Main entry point - start reading here!
├── background.ts         # 🔧 Background script for extension
├── manifests/           # 📦 Browser extension manifests
├── plugins/             # 🧩 Plugin system (the magic happens here!)
│   ├── core/           # 🏗️  Plugin infrastructure 
│   ├── built-in/       # 🎁 Pre-made plugins
│   └── index.ts        # 📋 Plugin registration
├── interface/          # 🎨 Settings UI (Svelte app)
│   ├── pages/          # 📄 Settings pages
│   ├── components/     # 🧱 Reusable UI components
│   └── main.ts         # 🏠 Settings app entry point
├── seqta/              # 🔗 SEQTA-specific utilities
│   ├── main.ts         # 🎯 Core SEQTA modifications
│   ├── ui/             # 🎨 UI manipulation helpers
│   └── utils/          # 🛠️  Helper functions
└── css/                # 💄 Styles and themes

Where to Start Reading?¶

New to the project? Start with src/SEQTA.ts
Want to understand plugins? Look at src/plugins/core/types.ts
Want to see a simple plugin? Check out src/plugins/built-in/profilePicture/
Interested in the UI? Explore src/interface/main.ts

Data Flow¶

Here's how data flows through the system:

User visits SEQTA → SEQTA.ts detects page → Loads settings from storage
                                                        │
                                                        ▼
Plugin Manager initializes → Each plugin gets API access → Plugins modify SEQTA
                                                        │
                                                        ▼
User opens settings → Svelte UI loads → Settings changed → Storage updated
                                                        │
                                                        ▼
Storage change detected → Plugins notified → UI updates automatically

Browser Extension Basics¶

Never worked on a browser extension before? Here's what you need to know:

Content Scripts vs Background Scripts¶

Content Script (SEQTA.ts): Runs on SEQTA pages, can access and modify the page
Background Script (background.ts): Runs in the background, handles storage and messaging

Manifest Files¶

Each browser needs a slightly different manifest file: - manifests/chrome.ts - Chrome, Edge, Brave - manifests/firefox.ts - Firefox - manifests/safari.ts - Safari (experimental)

Communication¶

Different parts of the extension communicate using: - browser.runtime.sendMessage() - Send messages - browser.storage - Shared storage, but we have created a custom storage system that is easier to use:

settingsState.[the setting name] = [whatever you want to set it to]
console.log(settingsState.[the setting name])

- Custom events for plugin communication

Development Tips¶

Debugging¶

Chrome DevTools: Right-click → Inspect → Console tab
Extension Console: chrome://extensions → BetterSEQTA+ → "Inspect views: background page"
Look for logs: We log everything with [BetterSEQTA+] prefix

Making Changes¶

Edit code → Save → Browser auto-reloads extension → Refresh SEQTA page
For UI changes: The dev server hot-reloads automatically
For plugin changes: May need to disable/enable the plugin in settings

Common Gotchas¶

Settings take a moment to load (use api.settings.loaded promise)
Some SEQTA elements load dynamically (use api.seqta.onMount())
Plugin cleanup is important (always return a cleanup function)

Next Steps¶

Ready to contribute? Here's what to do next:

Read the code: Start with src/SEQTA.ts and follow the flow
Try creating a simple plugin: Follow our plugin guide
Look at existing issues: Check our GitHub issues for "good first issue" labels
Join our Discord: Get help from the community!

Questions?¶

Still confused about something? That's totally normal! Here are your options: - 💬 Ask in our Discord server - 🐛 Open an issue on GitHub - 📧 Email us at betterseqta.plus@gmail.com

Remember: Every expert was once a beginner! We're here to help you learn and contribute. 🚀