Ascent

Engineer your next move.

A personal roadmap tracker for anyone learning, revising, or working toward a goal — students, professionals, and career switchers alike. No account required to try it, no build step required to run it.

Demo video

demo-video.mp4

What it is · How it works · Features · Tech stack · Architecture · Data & privacy · Security · Getting started · Contributing · Project status · Deploying · License

---

What it is

New sign-ups pick a starter template and get an editable, syncable checklist — organized into phases and sections, each topic carrying its own resource links, priority, and notes — instead of a wiki page or a spreadsheet that goes stale.

Template	Focus
Java Backend Engineer	Java, Spring Boot, microservices, system design
GenAI / Agentic AI Engineer	LLMs, agent frameworks, RAG, prompt engineering
Frontend Developer	HTML/CSS/JS, frameworks, accessibility, performance
Data Scientist	Statistics, ML, Python tooling, model deployment
12th Grade Mathematics	Exam-focused syllabus tracker
Learning Piano	Structured practice roadmap
Marketing	Growth, content, analytics fundamentals

Not a fit? Create your own roadmap — answer a few questions, generate one with your AI assistant of choice, and paste the result back in; it's validated and imported automatically, phases/sections/priorities and all.

Any starter template can be hidden from your own picker without affecting anyone else's account, and you can run more than one roadmap at a time — switching between them never overwrites another's progress.

How it works

flowchart LR
    A["Sign in as guest,<br>or with email/password"] --> B["Pick a starter template,<br>build your own, or<br>import one with AI"]
    B --> C["Check off topics<br>by phase and priority"]
    C --> D["Progress syncs across<br>every device via Firebase"]
    D --> E["Review streaks, heatmap,<br>and velocity on /progress"]
    E -. "start another roadmap any time" .-> B

Loading

No tutorial required — the flow above is the entire learning curve. If you're not sure where to start, "Continue as guest" needs no signup and gets you to a real roadmap in one click.

Features

• Sign in with email/password, or start instantly as a guest — no signup wall between you and your first roadmap.
• Cross-device sync via Firebase, with a localStorage offline fallback so the app still works with no connection.
• Progress analytics — completion streaks, a GitHub-style activity heatmap, 7-day velocity, and a cumulative-progress projection chart.
• Daily Todos — pull specific topics into a lightweight daily list with optional reminders, linked back to their source roadmap topic.
• AI-assisted roadmap import — paste a generated roadmap from your assistant of choice and it's validated and imported automatically.
• Share a read-only snapshot of your roadmap or progress via a public link, or export a branded PDF/print view.
• First-time guided tour, a command palette (Cmd/Ctrl+K), and full light/dark theming that follows your system preference by default.
• Installable as a PWA with offline support.

Tech stack

Layer	Choice	Why
Frontend	Vanilla JavaScript, native ES modules	No build step, no framework, no bundler — npm run dev is a small Node-only static server (scripts/dev-server.mjs). Keeps the whole codebase readable without a compile step between editing and reloading.
Auth	Firebase Authentication	Email/password + anonymous "guest" sessions, so trying the product needs no signup.
Data	Firebase Realtime Database	Per-user roadmap sync across devices; security rules in firebase/database.rules.json enforce every read/write server-side, not just in client code.
Offline	localStorage + a Service Worker	The app keeps working with no connection — reads/writes fall back to localStorage, and a Service Worker (sw.js) precaches the app shell for installable/offline use.
Charts	Chart.js (lazy-loaded)	Only fetched the first time the Progress page's charts render — not part of the initial page load.
Testing	Vitest (unit/integration) + Playwright (E2E, incl. @axe-core/playwright accessibility scans)	Every PR runs the full suite in CI against a real Firebase emulator, not mocks.
Hosting/CI	Firebase Hosting + GitHub Actions	Every push to main auto-deploys, gated on CI passing first (see Deploying); every PR gets a temporary preview URL.

See docs/architecture.md for the full module-by-module breakdown and the reasoning behind each of these choices.

Architecture at a glance

No build step, no framework, no server you have to run — the browser talks directly to Firebase, with localStorage picking up the slack when there's no connection. See docs/architecture.md for the full breakdown; this is the 30-second version.

flowchart TB
    subgraph Browser["Your browser (no build step)"]
        UI["Vanilla JS · native ES modules"]
        LS["localStorage<br>(offline fallback)"]
    end
    subgraph Firebase["Firebase (backend)"]
        Auth["Authentication<br>email/password + guest"]
        RTDB["Realtime Database<br>per-user roadmap sync"]
        Rules["Security rules<br>firebase/database.rules.json"]
    end
    UI <--> LS
    UI <--> Auth
    UI <--> RTDB
    RTDB --> Rules

Loading

Vanilla JavaScript over native ES modules — no build step, no bundler, no framework. Vitest for unit/integration tests, Playwright for E2E. See docs/architecture.md for the full data model and file layout, and CLAUDE.md / AGENTS.md for the conventions this codebase follows. docs/README.md indexes every deeper reference doc and Architecture Decision Record (ADR) in this repo.

Data & privacy

• Your roadmap data belongs to you. It's stored under your own Firebase user ID, scoped by security rules so no other account can read or write it (see firebase/database.rules.json) — the one deliberate exception is a roadmap you explicitly publish via "Share this roadmap…", which creates a separate, unauthenticated-readable read-only snapshot at its own link (revocable any time from the same menu).
• Guest sessions are real accounts, not local-only demos — an anonymous Firebase Auth identity, so your progress syncs across a tab reload or a second device using the same browser profile. If you never link a guest session to a real email/password account and sign out, that anonymous account and its data are deleted, not left orphaned.
• No third-party analytics or tracking scripts. The only outbound network calls are to Firebase (auth/data) and, if you use it, a lazily-loaded Chart.js bundle from a pinned jsDelivr CDN URL — see index.html's Content Security Policy for the exact allowlisted origins.
• Exporting and deleting your data are both first-class, no-support-ticket-needed actions in Settings: download a full JSON backup, or permanently delete your account (which deletes your database data before the Auth record itself, so nothing is ever left orphaned).

Security

Found a security issue? Please report it privately rather than opening a public GitHub issue — see SECURITY.md for how. A few of the concrete measures already in place, for anyone evaluating this codebase:

• Content Security Policy + Subresource Integrity on every third-party script (index.html) — see docs/adr/ADR-002-csp-sri-security.md.
• Server-side validation, not just client-side — Realtime Database security rules enforce field-level shape/length caps and per-user scoping independently of what the JavaScript client does (firebase/database.rules.json).
• No innerHTML anywhere in the codebase — every render path goes through textContent, eliminating an entire class of XSS (enforced by npm run lint).
• Automated, encrypted daily database backups (.github/workflows/db-backup.yml) with a documented retention/restore procedure (docs/architecture.md §6a).
• CI-gated production deploys — a push to main only reaches production if that exact commit's CI run (lint, unit/integration tests, E2E, a secret scan) passed first (.github/workflows/deploy.yml).

Getting started

You don't need to be a developer to use Ascent — signing in as a guest on the deployed app is the fastest path, no install required. The steps below are only for running your own local copy (useful for development, or for self-hosting).

Prerequisites (click to expand/collapse)

You'll need three things installed, all free:

Tool	What it's for	Get it
Git	downloads ("clones") the code to your computer	git-scm.com/downloads
Node.js (v20 or later)	runs the dev server and test suite — this project has no build step, Node is only the runner	nodejs.org (installing Node also installs npm, used below)
A free Firebase project	the backend for sign-in and syncing roadmaps	console.firebase.google.com — walked through in step 2 below

New to the command line? "Clone" just means "download a copy of this repository to your computer," and every code block below is something you paste into a terminal (macOS: Terminal app; Windows: PowerShell; Linux: your shell of choice) and press Enter on.

1. Clone and install — there are no dependencies to install; this is a static site.

   git clone https://github.com/adv11/ascent.git
   cd ascent

2. Set up Firebase. Create a project at console.firebase.google.com, then copy the example config to a real one:
   • macOS/Linux:

     cp src/services/firebase.config.example.js src/services/firebase.config.js

   • Windows (PowerShell):

     Copy-Item src/services/firebase.config.example.js src/services/firebase.config.js

   Fill in firebase.config.js with your project's values (Project settings → General → Your apps). This file is gitignored — it's meant to hold your own credentials, never a committed value.
   • Enable Email/Password and Anonymous sign-in under Authentication.
   • Publish the Realtime Database rules from firebase/database.rules.json.
3. Run it.

   npm run dev

   Serves the app at http://localhost:4173 on macOS, Linux, and Windows alike — npm run dev shells out to a small Node-only static server (scripts/dev-server.mjs), so no separate Python install or OS-specific command is needed.

Something not working? Common first-run issues

• "command not found: git" or "npm" — the corresponding tool from the Prerequisites table above isn't installed yet, or your terminal needs restarting after installing it.
• Sign-in fails / spins forever — double-check Email/Password and Anonymous sign-in are both enabled in the Firebase console (step 2), and that firebase.config.js was filled in with your project's real values, not left as the example placeholders.
• Blank page / console errors about firebase.config.js — this file is gitignored on purpose; make sure you actually copied the example file (step 2) rather than assuming it exists.
• Still stuck? Open a GitHub issue — see "Contributing" below.

Contributing

You don't have to write code to contribute:

• Found a bug or have an idea? Open a GitHub issue — no local setup needed. If you're using the deployed app, the in-app feedback widget (floating button, bottom corner) captures a screenshot for you automatically.
• Spot unclear or outdated docs? Docs fixes are just as welcome as code — small wording/README PRs are a great first contribution.
• Want to write code? Follow Getting started above, then:
  1. Read CLAUDE.md — DOM construction, brand rules, store contracts, styling, and security conventions this codebase follows.
  2. Branch off main: feat/, fix/, refactor/, docs/, or chore/ followed by a short slug (e.g. fix/dropdown-select-overlay-scrim).
  3. Before opening a PR:

     npm run lint     # must exit 0
     npm test         # must exit 0

  4. Reference the issue you're addressing in your PR description — see .github/PULL_REQUEST_TEMPLATE.md.

Full details — code conventions, commit style, the Lighthouse perf check — live in CONTRIBUTING.md.

Project status

Feature-complete through Step 7 of the build-out; Step 8 (Launch) is in its final stretch. Issue #11 is the single source of truth for current status — see it for the full, up-to-date list of what's left. See CHANGELOG.md for the detailed change history and docs/roadmap.md for a pointer to the same tracker.

Tests run via npm test (Vitest unit + integration, 1484 tests) and npm run test:e2e (Playwright). Run npm run lint to check for security and quality issues. See the "Verifying changes" section of CLAUDE.md for the full checklist.

Deploying

firebase deploy            # deploys hosting + database rules
firebase deploy --only hosting

Every push to main auto-deploys to Firebase Hosting via GitHub Actions. Every PR gets a temporary preview URL posted as a comment. See docs/architecture.md for the required GitHub secrets (FIREBASE_SERVICE_ACCOUNT, FIREBASE_CONFIG, FIREBASE_PROJECT_ID).

Note on firebase.config.js: The values in this file (apiKey, authDomain, etc.) are public client identifiers — they are embedded in the page JavaScript and visible to any user who opens DevTools. Firebase's security model relies on Security Rules, not on keeping these values private. The file is gitignored to avoid committing production credentials during local development; CI injects it from a GitHub Secret.

License

All rights reserved — see LICENSE. This code is shared for viewing only; no license to use, copy, or modify is granted without permission.

---

_{Repository activity, for the curious:}