EEE Roadmap

An interactive roadmap for learning Electrical & Electronic Engineering.

Live Demo →

⚠️ Content Notice: Roadmap content (descriptions, concepts, resources) is AI-generated and has not been manually verified. Links may be outdated or broken. Use as a learning guide, not authoritative reference. Contributions and corrections welcome!

---

Table of Contents

• Current Features
  • For Learners
  • For Explorers
  • For Contributors
  • Technical Highlights
• Roadmap
• Tech Stack
• Project Structure
• Run Locally
• Contributing
• License

Current Features

Current version is v0.21.1

For Learners

• Interactive Roadmaps — Expand/collapse topic nodes with descriptions, prerequisites, and curated resources
• Progress Tracking — Mark concepts complete (✓) or important (★), persists across sessions
• Cross-Device Sync — Sign in with Google to sync progress across devices; works offline with automatic merge on reconnect
• Focus View — Quickly expand only incomplete or highlighted topics with visual glow feedback
• Expand/Collapse All — Manage topic visibility in one click
• Two Interaction Modes:
  • Simple — Click (notes), double-click (complete), shift+click (important)
  • Tools — Swipe gestures with pen/highlighter/eraser (optimized for tablet/stylus)
• Concept Windows — Draggable, resizable note windows with markdown, LaTeX equations, and embedded PDFs; open windows persist across page refreshes; taskbar for window management; built-in markdown editor for adding personal notes
• Custom Concept Notes — Add personal notes to any concept (official or custom tracks); notes appear above original content with visual distinction; supports full markdown with LaTeX
• Add Custom Concepts — Create your own concept pills on official track topics (signed-in users); concepts sync across devices
• Global Search — Fuzzy search across all tracks, topics, and concept notes (Ctrl+K)
• Deep Links — Share links directly to specific concepts
• State Persistence — Topic expand/collapse state saved per track, settings panel remembers preferences
• Glossary — 100+ EEE terms with definitions, LaTeX equations, and cross-references
• Auto-linked Terms — Glossary terms in roadmap content show tooltips on hover
• Profile Page — View your progress across all tracks; works offline for guests, syncs when signed in
• Import/Export — Back up your progress as JSON; import with merge or replace options
• Graph View — Interactive visualization of topic connections and prerequisites; fullscreen mode on all devices; dark mode support; progress status indicators; per-track focused view on roadmap pages

For Explorers

• Four Tracks — Fundamentals, Core, Advanced, Distributed Generation
• Browse All Tracks — /roadmaps/ page with category + progress filters and boxed/unboxed view
• Custom Tracks — Create your own learning roadmaps with the built-in editor (requires sign-in)
  • Full track editor: sections, topics, concepts, resources, prerequisites
  • Prerequisite picker with cascading dropdowns (official + custom tracks)
  • Drag-and-drop reordering for sections and topics
  • Collapsible sections/topics for easier organization
  • Live preview before saving
  • Export track as JSON for backup/sharing
  • Import track from JSON file
  • Stored in Supabase (syncs across devices)
• Custom Track Display — View custom tracks at /roadmaps/custom/?track=slug with full interactivity (progress tracking, tools mode, concept windows)
• Cross-track Navigation — Clickable prerequisites link between related topics
• Prerequisite Behavior — Smart defaults (same-track = same tab, cross-track = new tab)

For Contributors

• YAML Content Format — Human-readable with auto-defaults and schema validation
• Dynamic Track Discovery — Drop a YAML file in content/, track appears automatically
• Developer Tooling:
  • npm run validate — Schema validation
  • npm run version:bump — Interactive version updater
  • Pre-commit hooks for build/validate/test

Technical Highlights

• Stack: Astro, TypeScript, Tailwind CSS
• Search: Fuse.js fuzzy matching with highlighted snippets
• PDFs: PDF.js for cross-browser viewing, auto-downloaded at build time
• Math: KaTeX for LaTeX equation rendering
• Mobile: Touch + stylus support, responsive design
• Theming: Dark mode with system preference detection

---

Roadmap

See CHANGELOG.md for detailed version history.

Completed

v0.16 - ConceptWindows Persistence ✓

• Persist open windows to localStorage
• Restore windows on page load
• Per-track state storage
• Taskbar with "Minimize all" and "Close all" buttons

v0.17 - Cross-Device Sync ✓

• Supabase integration (auth + PostgreSQL)
• Google OAuth authentication
• Real-time sync on every progress change
• Union merge on login (local + cloud combined)
• Duplicate topic ID validation
• Auth UI with dropdown menu
• Graceful degradation when Supabase not configured

v0.18 - Profile & Data Export ✓

• GitHub Actions: add Supabase env vars for deployment
• Profile page with progress visualization
• Privacy policy page
• Import/export progress as JSON (merge or replace)
• Auth dropdown for guests with View Profile link

v0.19 - Roadmap Graph View ✓

• Node-based visualization showing prereq connections
• Interactive graph (click to navigate)
• Dynamic track colors (curated palette + HSL overflow)
• Fullscreen modal for mobile (tap to explore)
• Fullscreen button for desktop
• UI polish (node sizing, labels, dark mode)
• Progress status on nodes (complete/important)
• Legend for node states
• Per-track mini graph on roadmap pages (focused on current track with cross-track prereqs)
• Filter by track on homepage graph

v0.20 - Custom Tracks & Editor ✓

**Goal:** Let users create and manage their own learning tracks.

• Custom content storage in Supabase (per-user, private, 500KB limit)
• Custom concept notes on existing tracks (distinct styling)
• Display custom tracks on /roadmaps/ with "Custom" badge
• Custom track detail page
• Form-based web editor with validation
  • Editor shell with edit/preview toggle
  • Meta fields (title, description, icon, category, order)
  • Sections management (add/remove/edit title)
  • Topics management (title, description, add/remove)
  • Concepts list (names only - add/remove)
  • Resources within topics (label + url)
  • Prerequisites with cascading dropdown picker (track → section → topic)
  • Validation before save (required fields, duplicate detection)
  • Save to Supabase
  • "Create New Track" button on /roadmaps/ page
• Concept Notes Editor (separate from roadmap editor)
  • Markdown editor inside ConceptWindow (edit button)
  • Works for custom track concepts AND custom notes on official tracks
  • Keeps roadmap editor focused on structure (sections/topics/concept names)
  • Concept content editing is contextual (edit while viewing the concept)
• UI to add custom concept notes on existing tracks
  • "+" button on concept lists (signed-in users)
  • Modal for entering concept name
  • Custom concepts styled distinctly (dashed border)
• Live preview (edit/preview toggle in editor)
• Export as JSON (single track with conceptNotes)
• Import track from JSON file
• Drag-and-drop reordering for sections and topics

---

In Progress

v0.21 - Test Coverage & Code Quality (Refactor)

Goal: Improve existing test suite for better reliability and coverage, then improve code quality by linting checks and refactor.

• Add linting (ESLint with TypeScript + Astro)
• Add lint to pre-commit hook
• Fix/unskip flaky Playwright tests (Supabase timing issues)
• Add knip for unused code detection
• Add madge for dependency graph / circular import detection
• Add tests for new sync/auth functionality
• Visual regression tests (when UI stabilizes)
• Accessibility tests (a11y)
• Increase unit test coverage for utilities
• Add CSS duplicate checks
• Refactor as needed
• Lighthouse score and performance optimisation

---

Planned

v0.22 - Content Verification

Goal: Manually vet all AI-generated content before 1.0.

• Review all topic descriptions for accuracy
• Verify all external resource links
• Add "Verified by" badges with contributor attribution
• Verification status indicators (section/track level)

---

Known Issues & Polish

• iOS Safari: dark mode demo tools switch menu arrow visibility
• iOS Safari: trail persistence in two-finger swipe (tools mode)
• Mobile: fullscreen mode bottom bar overlap
• PDF.js: open-in-new-tab and fullscreen viewer icons
• Concept windows: translucent effect when unfocused
• Unboxed view: overlapping card layout for overflow
• Refactor: localStorage keys duplicated across files (should use shared constants)
• Custom track cards: display Lucide icon from meta (currently hardcoded)
• Custom tracks: integrate with category filters on /roadmaps/ page
• Replace browser alerts with custom toast notifications (editor validation)

---

v1.0.0 - Official Release

Goal: Production-ready, verified educational resource.

• All content manually verified
• Comprehensive test coverage
• Performance optimized
• Accessibility audit passed
• PWA support for offline access
• Filter by section on track page graph (post-v1.0)

---

Future Ideas

Post-launch features, no timeline commitment.

• Gamification (streaks, achievements, learning stats)
• Image/file attachments for notes (Supabase Storage)
• AI-generated roadmap remixing
• Notes parser (upload .md → convert to roadmap format)
• In-class note-taking mode
• WebAssembly circuit simulator
• Freemium tiers (if user growth warrants)
• Community contributions workflow
• User feedback system (comments per section)

---

Tech Stack

• Astro — Static site generator
• Tailwind CSS — Utility-first CSS
• TypeScript — Type safety
• Supabase — Auth & PostgreSQL database
• Cytoscape.js — Graph visualization

---

Project Structure

food-wars/
├── e2e/                        # Playwright E2E tests
│   └── home.spec.ts
├── public/                     # Static assets
├── scripts/
│   └── bump-version.mjs        # Version updater
├── src/
│   ├── app/
│   │   ├── api/
│   │   │   └── test-supabase/  # API test route
│   │   ├── auth/
│   │   │   ├── callback/       # OAuth callback handler
│   │   │   └── error/          # Auth error page
│   │   ├── test/               # Color palette test page
│   │   ├── globals.css
│   │   ├── layout.tsx
│   │   └── page.tsx            # Home (inventory)
│   ├── components/
│   │   ├── diner/              # Themed components
│   │   │   ├── Noren.tsx       # Curtain header
│   │   │   ├── UserMenu.tsx    # User dropdown
│   │   │   ├── WelcomeModal.tsx
│   │   │   └── WoodCard.tsx    # Legacy item card
│   │   ├── inventory/          # Inventory feature
│   │   │   ├── AddItemForm.tsx
│   │   │   ├── EditItemForm.tsx
│   │   │   ├── InventoryList.tsx  # Legacy list
│   │   │   ├── InventoryStats.tsx
│   │   │   ├── InventoryWarnings.tsx
│   │   │   ├── StockCard.tsx   # New v0.4 card
│   │   │   └── StockList.tsx   # New v0.4 list
│   │   └── ui/                 # shadcn components
│   ├── hooks/
│   │   └── useGuestStorage.ts
│   ├── lib/
│   │   ├── supabase/
│   │   │   ├── client.ts       # Browser client
│   │   │   ├── inventory.ts    # DB queries
│   │   │   ├── middleware.ts   # Auth middleware
│   │   │   └── server.ts       # Server client
│   │   ├── __tests__/          # Unit tests
│   │   ├── inventory.ts        # Legacy inventory helpers
│   │   ├── inventory-utils.ts  # Expiry/stats utilities
│   │   ├── storage.ts          # Guest localStorage
│   │   └── utils.ts            # General utilities
│   └── types/
│       └── database.ts         # TypeScript types
├── supabase/
│   └── migrations/
│       └── 001_schema.sql      # Database schema
├── BRANDING.md                 # Design system
├── CHANGELOG.md
├── CONTRIBUTING.md
└── README.md

Run Locally

Prerequisites

• Node.js v18 or higher
• npm (comes with Node.js)

Development Steps

# 1. Clone the repository
git clone https://github.com/Muhammad-Hazimi-Yusri/eee-roadmap.git
cd eee-roadmap

### Setup
npm install        # Installs dependencies + downloads PDF.js viewer
npm run dev        # Downloads PDFs + starts dev server

Environment Variables (for sync features)

Copy .env.example to .env and fill in your Supabase credentials:

cp .env.example .env

PUBLIC_SUPABASE_URL=https://your-project.supabase.co
PUBLIC_SUPABASE_ANON_KEY=your_anon_key_here

Get these from Supabase Dashboard → Project Settings → API.

Note: Sync features require a Supabase project with Google OAuth configured. See Supabase Auth Docs for setup.

Scripts

Command	Description
npm run dev	Download PDFs and start dev server
npm run build	Build for production (auto-downloads PDFs)
npm run build:data	Convert YAML to JSON + glossary + search index
npm run build:glossary	Build glossary JSON with reverse index
npm run validate	Validate YAML against schema
npm run test	Run unit tests (Vitest) in watch mode
npm run test:run	Run unit tests once
npm run test:e2e	Run Playwright integration/E2E tests
npm run test:all	Run all tests (Vitest + Playwright)
npm run download:pdfs	Manually download external PDFs
npm run knip	Find unused files, exports, and dependencies
npm run madge:circular	Check for circular dependencies
npm run madge:graph	Generate dependency graph image (WSL/Linux only)

Adding PDFs

External PDF URLs in data files are automatically downloaded at build time:

1. Add pdf: "https://example.com/document.pdf" to a concept in src/data/
2. Run npm run download:pdfs (or it runs automatically on build/dev)
3. PDFs are saved to public/pdfs/ and a manifest maps URLs to local paths

Adding/Editing Roadmap Content

Roadmap data lives in content/*.yaml files. These are human-readable and auto-convert to JSON on build.

1. Edit or create a YAML file in content/ (see content/sample.yaml for template)
2. Run npm run dev — conversion happens automatically
3. Changes appear immediately in the browser

See CONTRIBUTING.md for the full YAML format reference.

Contributing

Contributions welcome! Make sure to read CONTIRBUTING.MD. Please:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

---

License

MIT License — see LICENSE for details.

---

Acknowledgments

Built by Muhammad-Hazimi-Yusri with assistance from Claude.