# TOPEDU SEO OS — Phase 1

Internal SEO operating system for **topeduprep.uk**. Phase 1 delivers the
production architecture, layout shell, theming, storage, routing and the
Dashboard + Settings modules. The remaining 18 modules are scaffolded in the
navigation and command palette with a clear "not built yet" state, ready to
be implemented module-by-module in Phases 2–4 as specified in the build order.

## Run it

No build step is required to run the app — it's plain ES modules over
static files. You only need to (re)build CSS when you change classes.

```bash
npm install          # installs the Tailwind CLI (dev-only dependency)
npm run build:css    # compiles css/output.css from css/input.css
npm run serve        # serves the project at http://localhost:8080 (any static server works)
```

Open `http://localhost:8080/index.html`. While actively editing styles, run
`npm run watch:css` in a second terminal.

Because this is a static PWA, you can also just open `index.html` through
any static file server (Vite's `preview`, `npx serve`, VS Code Live Server,
Cloudflare Pages, GitHub Pages, etc.) — nothing here depends on Node at
runtime, only at CSS build time.

## What's live in Phase 1

- **Dashboard** (`#/dashboard`) — stat cards, visibility trend chart
  (Chart.js), priority keyword list, quick-launch grid for all 20 modules,
  and a locally-persisted recent-activity feed.
- **Settings** (`#/settings`) — theme control, local data export/clear
  (IndexedDB), and placeholders for the Phase 4 API connections.
- **App shell** — collapsible sidebar nav (grouped by workflow stage),
  topbar with global search, dark/light theme with system-preference
  detection and no flash-of-wrong-theme, and the **Mission Strip**: a
  terminal-style ticker that always surfaces today's single highest-ROI
  action (this app's signature UI element).
- **Command palette** (`⌘K` / `Ctrl+K`) — fuzzy search across all 20
  modules via Fuse.js (lazy-loaded from esm.sh, with an offline-safe plain-
  filter fallback).
- **PWA** — installable, offline-capable app shell via `manifest.json` +
  `sw.js` (cache-first for the shell, network-first-with-fallback for CDN
  assets like fonts and Chart.js/Fuse.js).
- **Storage** — `src/services/storage.js` wraps both `localStorage`
  (settings, UI state) and `IndexedDB` (history, favorites, cache) behind a
  small promise-based API every future module will reuse.

Every other module (Site Audit, Keyword Explorer, Keyword Gap, Topic
Cluster, Competitor Analysis, Content Planner, Blog/FAQ/Schema Generators,
Internal Link Builder, SEO/EEAT/Helpful Content Score, Google/Naver Score,
Daily Mission, AI Assistant, Prompt Library) is registered in
`src/services/moduleRegistry.js` with its route, icon, group and target
build phase, and renders a clean "not built yet" state until implemented.

## Project structure

```
/index.html            App shell entry point
/manifest.json          PWA manifest
/sw.js                   Service worker (offline app-shell cache)
/css
  input.css              Tailwind source + design tokens (components/base layers)
  output.css              Compiled, minified CSS (generated — do not edit by hand)
/js
  app.js                  Boot sequence: theme → storage → layout → router → shortcuts
/src
  /components             Sidebar, Topbar, MissionStrip, CommandPalette, StatCard, EmptyState
  /pages                   Dashboard, Settings (one module = one page file)
  /services                storage.js, moduleRegistry.js
  /utils                   router.js, theme.js, shortcuts.js, icons.js
  /data                    mockDashboardData.js — clearly labeled Phase 1 mock data only
/assets/icons             SVG app icons (favicon + PWA, incl. maskable variant)
/tailwind.config.js       Design tokens: ink/ivory/brass/steel palette, Playfair/Inter/JetBrains Mono
```

## Design system

- **Palette**: `ink` (near-black navy, dark-mode base), `ivory` (warm paper,
  light-mode base), `brass` (primary accent — links, focus states, the
  Mission Strip pulse), `steel` (secondary/data-viz), `moss`/`amber`/`clay`
  (positive/warning/negative signal colors used in scoring badges later).
- **Type**: Playfair Display for page titles and the wordmark only; Inter
  for all UI text; JetBrains Mono for anything numeric, tabular, or
  terminal-flavored (badges, the Mission Strip, keyboard-shortcut chips).
- **Signature element**: the Mission Strip — a constant-position, terminal-
  style ticker under the topbar that always shows today's single
  highest-ROI action. It's the thesis of an "operating system" made
  visible: one clear next action, never buried in a dashboard of widgets.

## Adding a new module (Phase 2+)

1. Add the module's entry to `src/services/moduleRegistry.js` (route, icon,
   group, `phase`).
2. Build `src/pages/<Module>.js` exporting a `render(container)` function,
   following the pattern in `Dashboard.js` / `Settings.js`.
3. In `js/app.js`, replace its registration with the real page:
   `registerRoute(mod.route, YourModule)` before the "not built yet" loop.
4. Add any new files it needs to `APP_SHELL` in `sw.js` so it works offline.

No other file needs to change — Sidebar, Topbar and the Command Palette all
read from `moduleRegistry.js` automatically.