mirror of
https://github.com/BetterSEQTA/BetterSEQTA-Plus.git
synced 2026-06-05 19:24:39 +00:00
docs: more comprehensive documentation
This commit is contained in:
SethBurkart123
@@ -0,0 +1,235 @@
|
||||
# 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. 🚀
|
||||
Reference in New Issue
Block a user