A personal tracker: job applications, grad-school applications, study, plus anything else you build a tracker for — with tasks, a calendar, time-boxed challenges, subscribed calendar feeds and browser reminders.
React + Vite, served by a Cloudflare Worker on a path route (/private*, so
the portfolio keeps the rest of the domain), stored in Workers KV, and
protected by Cloudflare Access. It installs from the browser as a PWA.
Runs on Cloudflare's free tier. The only metered cost is job-posting extraction.
npm install
cp wrangler.example.toml wrangler.toml # fill in your account, KV namespace, Access team
npm run build # compile React into dist/
npx wrangler dev --port 8787 # http://localhost:8787/private/
npm test # 1,023 tests across 51 filesnpm run build is required before wrangler dev and after every change to
src/ — the Worker serves dist/, and it does not hot-reload.
| Document | Covers |
|---|---|
| docs/ARCHITECTURE.md | the data model, module map, invariants, the two UI traps, testing strategy |
| docs/OPERATIONS.md | local dev, phone testing, deploying, secrets, Access, KV limits, backups, recovery |
Read ARCHITECTURE.md before touching src/helpers.js.
src/
helpers.js the data model — the only module that knows the stored shape
model/ the parts of it that extract without circular imports
dates.js recurrence.js profile.js jobs.js
App.jsx layout, navigation, routing
ctx.js the React context every component reads through
shared.jsx shared components and style primitives
cards.jsx the card renderer every tracker uses, Study included
tabs/ one file per page
api.js where the API is — a relative fetch; Access carries identity
useTracker.js load, save, conflict detection and merge
useEvents.js memoised calendar events
useViewport.js breakpoints (inline styles have no media queries)
useTheme.js theme, in localStorage rather than the synced blob
webpush.js subscribing this browser to reminders
fonts/ self-hosted woff2 files, so no font CDN sees visitors
worker/
worker.js routes, static assets, the API, the reminder cron
identity.js Access JWT → an account
merge.js conflict detection and additive merge
ics.js iCalendar parsing for subscribed feeds
extract.js job posting → structured fields, via the Anthropic API
model.js which model does extraction, and the check that it did
quota.js the per-account and service-wide daily extraction limits
push.js web-push signing and delivery
account.js account deletion — every key that belongs to a person
users.js the account roster
public/ PWA manifest, service worker, icons — copied into dist/ as-is
scripts/ one-off generators: PWA icons, VAPID keys
test/ pure-Node Vitest suites; components render via react-dom/server
dist/ is build output and is gitignored. public/ is its source for the
static half; src/ is its source for the compiled half. wrangler.toml is
also gitignored — it is your Cloudflare account, not the code — and
wrangler.example.toml is the template for it.
All under /private/api/ and behind Cloudflare Access.
| Endpoint | Method | Purpose |
|---|---|---|
me |
GET | who you are; records you in the roster |
data |
GET / PUT | the account, withETag / If-Match conflict detection |
calendar |
POST | fetch and parse an iCalendar feed |
extract |
GET / POST | what is left today · job posting → structured fields |
account |
DELETE | delete the account and everything belonging to it |
users |
GET | the account roster — owner only |
push/key, push/subscribe, push/unsubscribe, push/due |
GET / POST | browser notifications |
Plus a scheduled handler (cron, every five minutes) that sends browser pushes when something has come due.
- Colours come from CSS custom properties. Never hard-code one; a test fails if a shared control does.
- Clickable
span/divmust spreadpressable()so it is keyboard reachable. Tick boxes useCheckBox. A test fails on a bareonClick. - Address records by id, never by array position. An index captured during render goes stale.
- Guard every access to an optional section (
D.jobs,D.gradApps) — they exist only when enabled. - Grids must adapt. A hardcoded multi-column
gridTemplateColumnsfails a test unless it is conditional, self-reflowing, or a fixed date grid. - Any new
tracker:*:KV prefix must be added todeleteAccount. A test scans the Worker and fails when one is missing.
Each of these has a guard test, and each was written after a real bug.