mirror of
https://github.com/BetterSEQTA/BetterSEQTA-Plus.git
synced 2026-06-06 03:34:40 +00:00
SethBurkart123
235 lines
11 KiB
Markdown
235 lines
11 KiB
Markdown
# 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](#overview)
|
|
- [High-Level Architecture](#high-level-architecture)
|
|
- [Core Components](#core-components)
|
|
- [Plugin System](#plugin-system)
|
|
- [File Structure Explained](#file-structure-explained)
|
|
- [Data Flow](#data-flow)
|
|
- [Browser Extension Basics](#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:
|
|
```typescript
|
|
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?
|
|
1. **New to the project?** Start with `src/SEQTA.ts`
|
|
2. **Want to understand plugins?** Look at `src/plugins/core/types.ts`
|
|
3. **Want to see a simple plugin?** Check out `src/plugins/built-in/profilePicture/`
|
|
4. **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:
|
|
```ts
|
|
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
|
|
1. **Chrome DevTools**: Right-click → Inspect → Console tab
|
|
2. **Extension Console**: `chrome://extensions` → BetterSEQTA+ → "Inspect views: background page"
|
|
3. **Look for logs**: We log everything with `[BetterSEQTA+]` prefix
|
|
|
|
### Making Changes
|
|
1. Edit code → Save → Browser auto-reloads extension → Refresh SEQTA page
|
|
2. For UI changes: The dev server hot-reloads automatically
|
|
3. 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:
|
|
|
|
1. **Read the code**: Start with `src/SEQTA.ts` and follow the flow
|
|
2. **Try creating a simple plugin**: Follow our [plugin guide](./plugins/README.md)
|
|
3. **Look at existing issues**: Check our [GitHub issues](https://github.com/BetterSEQTA/BetterSEQTA-plus/issues) for "good first issue" labels
|
|
4. **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](https://discord.gg/YzmbnCDkat)
|
|
- 🐛 Open an issue on GitHub
|
|
- 📧 Email us at betterseqta@betterseqta.com
|
|
|
|
Remember: **Every expert was once a beginner!** We're here to help you learn and contribute. 🚀 |