Hellion-NewTab/docs/architecture.md

Hellion Dashboard — Architecture

This document is intentionally written in English. Full German/English i18n support is planned for v2.0 — until then, English keeps the docs accessible to anyone who wants to contribute or fork the project.

---

Overview

Hellion Dashboard is a browser extension (NewTab replacement) built with Vanilla JavaScript ES2020, CSS Custom Properties, and zero dependencies. No build step, no framework, no bundler — files are loaded directly via <script> tags.

Storage: chrome.storage.local with localStorage fallback. Manifest: V3 across all supported browsers (separate files for Firefox and Opera GX).

---

File Structure

HOM_NewTab_Project/
├── newtab.html              # Single HTML entry point
├── manifest.json            # Chrome, Edge, Brave, Vivaldi (MV3)
├── manifest.firefox.json    # Firefox (MV3)
├── manifest.opera.json      # Opera, Opera GX (MV3 + workarounds)
├── src/
│   ├── css/
│   │   └── main.css         # All styles, 11 themes, responsive breakpoints
│   └── js/
│       ├── storage.js        # Storage abstraction layer
│       ├── state.js          # Global state, defaults, helpers
│       ├── i18n.js           # Internationalization (DE/EN, t() helper)
│       ├── dialog.js         # Custom dialog system (alert, confirm)
│       ├── themes.js         # Theme definitions & application (11 themes)
│       ├── drag.js           # Drag & drop (Pointer Events API)
│       ├── boards.js         # Board/bookmark rendering & events
│       ├── settings.js       # Settings panel, toggles, theme picker
│       ├── search.js         # Search bar (Google, DuckDuckGo, Bing)
│       ├── widgets.js        # Widget manager (registry, drag, resize)
│       ├── notes.js          # Notes/checklists (multi-instance widgets)
│       ├── calculator.js     # Calculator widget (single-instance)
│       ├── timer.js          # Timer/countdown widget (single-instance)
│       ├── image-ref.js      # Image reference widget (multi-instance)
│       ├── bookmark-import.js # Browser bookmark import (chrome.bookmarks API)
│       ├── data.js           # JSON export/import (backup & restore)
│       ├── onboarding.js     # First-run onboarding flow
│       └── app.js            # Init, clock, global events (entry point)
├── assets/
│   ├── fonts/                # Local fonts (Rajdhani, Inter, Cinzel)
│   ├── icons/                # Extension icons (16-512px)
│   └── themes/               # 11 theme background images
└── docs/                     # You are here

---

Module Responsibilities

Each module has exactly one responsibility. Communication happens through global references — no import/export, because this is a browser extension without a bundler.

Module	Responsibility
storage.js	The only place that touches chrome.storage / localStorage. Everything else goes through Store.get() / Store.set().
state.js	Global boards and settings arrays, default values, uid(), escHtml(), getFaviconUrl().
i18n.js	Internationalization module. STRINGS object with ~220+ keys (DE/EN), t(key, vars?) helper, applyLanguage() DOM scanner, setLanguage(), I18n.init().
dialog.js	HellionDialog.alert() and HellionDialog.confirm() — custom styled dialogs that replace native browser popups.
themes.js	Applies theme CSS variables. 11 themes, each with its own [data-theme] block in main.css.
boards.js	Renders boards and bookmarks. Event delegation on board containers.
drag.js	Board and bookmark reordering via Pointer Events API.
settings.js	Settings panel UI, toggle handlers, appearance modal, background upload.
search.js	Search bar with engine switching (Google, DuckDuckGo, Bing).
widgets.js	Widget manager — creates DOM, handles drag/resize/z-index, provides registry. See widget-schema.md.
notes.js	Notes and checklists as widgets. Multi-instance (max 5). Notebook sidebar. Also handles widget toolbar events.
calculator.js	Calculator widget. Single-instance. Shunting-yard expression parser — no eval().
timer.js	Timer/countdown widget. Single-instance. Presets, Web Audio API alarm, tab-title blink on completion.
image-ref.js	Image reference widget. Multi-instance (max 3). Canvas API WebP conversion, sessionStorage for image data — cleared on browser close.
bookmark-import.js	Direct browser bookmark import via chrome.bookmarks.getTree(). Folder selection modal with duplicate detection.
data.js	JSON export/import with validation. Covers boards, notes, calculator history and timer presets.
onboarding.js	Multi-slide first-run flow including the gaming starter board opt-in.
app.js	Entry point. Calls init() on DOMContentLoaded. Clock, global event binding.

---

Init Sequence

DOMContentLoaded
  → init()
    → Store.get('boards')          # Load saved boards
    → Store.get('settings')        # Load saved settings
    → applySettings()              # Apply theme, toggles, etc.
    → renderBoards()               # Render all boards
    → startClock()                 # Start clock/date display
    → bindGlobalEvents()           # Header buttons, modals
    → bindSettingsEvents()         # Settings toggles, theme picker
    → initSearch()                 # Search bar
    → migrateSticky()              # Legacy sticky note migration (v1.5.x → v1.6+)
    → Notes.init()                 # Notes + widget toolbar
    → Calculator.init()            # Calculator widget
    → Timer.init()                 # Timer widget
    → ImageRef.init()              # Image reference widget
    → initDataButtons()            # Export/import buttons
    → Onboarding check             # First-run onboarding

---

Script Load Order

Scripts are loaded in newtab.html in dependency order. A module may only reference modules loaded before it — there is no bundler to handle this automatically.

<script src="src/js/storage.js"></script>
<script src="src/js/state.js"></script>
<script src="src/js/i18n.js"></script>
<script src="src/js/dialog.js"></script>
<script src="src/js/themes.js"></script>
<script src="src/js/drag.js"></script>
<script src="src/js/boards.js"></script>
<script src="src/js/settings.js"></script>
<script src="src/js/search.js"></script>
<script src="src/js/widgets.js"></script>
<script src="src/js/notes.js"></script>
<script src="src/js/calculator.js"></script>
<script src="src/js/timer.js"></script>
<script src="src/js/image-ref.js"></script>
<script src="src/js/bookmark-import.js"></script>
<script src="src/js/data.js"></script>
<script src="src/js/onboarding.js"></script>
<script src="src/js/app.js"></script>

---

Z-Index Hierarchy

Layer	z-index	Elements
Background	0-2	#bgLayer, boards
Search bar	90	.search-bar-wrapper
Widgets + Toolbar	100+	.widget, .widget-toolbar
Header	100	#header
Settings panel	200	#settingsPanel
Dialogs / Modals	300	.hellion-dialog-overlay, modals
Onboarding	400	#onboardingOverlay

Widgets use an incrementing z-index (WidgetManager._topZ++) so the last clicked widget always sits on top.

---

Storage Keys

Key	Type	Content
boards	Array	Board objects with bookmarks
settings	Object	User preferences (theme, toggles, etc.)
widgetStates	Object	All widget data — see widget-schema.md
onboardingDone	Boolean	Whether the first-run onboarding has been completed
lastBackupReminder	Number	Timestamp of the last backup reminder

---

Browser Compatibility

Browser	Engine	Manifest
Chrome	Chromium MV3	manifest.json
Edge	Chromium MV3	manifest.json
Brave	Chromium MV3	manifest.json
Vivaldi	Chromium MV3	manifest.json
Opera / GX	Chromium MV3	manifest.opera.json
Firefox	Gecko MV3	manifest.firefox.json

Any change that touches manifest fields — version numbers, permissions, content scripts — needs to be applied to all three files. The CI quality check will catch it if they drift out of sync.