Trackers — Context

What Are the Trackers?

A suite of internal operational tools built on Cloudflare Workers + D1. There are two systems that share a single D1 database:

1. Task Trackers — three separate task-management dashboards (Sonan Group HQ, Harper's Preserve, Woodridge), each showing tasks, priorities, assignments, progress charts, and a timeline. All three call the same backend Worker API.
2. Timesheet Tracker — employee clock-in/clock-out, pay period management, tax settings, pay stubs, and admin controls for the SONAN TECH repair shops.

Repo & Folder

Item	Value
Local root	E:\Claude_Projects\sonan-trackers\
GitHub	https://github.com/sonantechai/sonan-trackers
Cloudflare account	sonantechai (ID: a7bd7d4b54bb7cb5907f8ddd45c3e5d9)

Live URLs

System	URL	Cloudflare Pages Project
Sonan Group Tracker	sonan-tracker.sonandigital.com	sonan-tracker
Harper's Preserve Tracker	hp-tracker.sonandigital.com (approx)	harpers-preserve-tracker
Woodridge Tracker	wr-tracker.sonandigital.com (approx)	woodridge-tracker
Timesheet Tracker	sonantech-timesheet-tracker.sonandigital.com	sonantech-timesheet
Task Tracker API	sonan-tracker-api.sonantechai.workers.dev	Cloudflare Worker
Timesheet API	sonan-timesheet-api.sonantechai.workers.dev	Cloudflare Worker

Tech Stack

Layer	Technology
Frontend	Plain HTML / CSS / JavaScript — static files served by Cloudflare Pages
Backend	Cloudflare Workers (edge JS) — one worker per system
Database	Cloudflare D1 (SQLite at the edge) — both systems share one DB
Auth — task trackers	Two-layer: hardcoded HTML password gate → localStorage SHA-256 app password
Auth — timesheet	API key header (X-API-Key) + server-side admin password hash in D1
Encryption	AES-256-GCM for sensitive timesheet data (pay rates, SSN) via ENCRYPT_KEY Worker secret

File Structure

sonan-trackers/
  sonan-tracker/
    Sonan/index.html          ← Sonan Group task tracker frontend
    HP/index.html             ← Harper's Preserve task tracker frontend
    WR/index.html             ← Woodridge task tracker frontend
    worker.js                 ← Task tracker backend Worker API
    wrangler.toml             ← Worker config (sonan-tracker-api, sonan-tracker-db)
    sonan-timesheet/
      worker.js               ← Timesheet backend Worker API
      wrangler.toml           ← Worker config (sonan-timesheet-api, same D1 DB)
      html/
        index.html            ← Timesheet frontend
  Timesheet-Tracker/          ← Legacy/archived version (do not deploy)
  timesheet_migration.sql     ← DB migration file used July 2026
  DEPLOYMENT-GUIDE.md        ← How to deploy all components

Shared Database

Both workers bind to the same Cloudflare D1 database. They use separate table namespaces — task tables are used by the task worker, timesheet tables by the timesheet worker.

Property	Value
Database name	sonan-tracker-db
Database ID	d0e1e4d2-42be-4e0d-a521-534e7c4ebb99
Account	sonantechai

Key Tables

Table	Used by	Purpose
tasks	Task tracker	Sonan Group tasks
hp_tasks	Task tracker	Harper's Preserve tasks
wr_tasks	Task tracker	Woodridge tasks
employees	Timesheet	Employee records (AES-encrypted fields)
time_entries	Timesheet	Clock-in/out records, hours
pay_periods	Timesheet	Pay period summaries, deductions, advances
tax_settings	Timesheet	Key/value config including admin_pw_hash
stores	Timesheet	Store locations
holidays	Timesheet	Federal/custom holidays (id, holiday_date, name, type)
advances	Timesheet	Pay advances to employees
schedules	Timesheet	Employee shift schedules

How to Deploy

Frontend (Cloudflare Pages — auto-deploy on push)

Each tracker frontend is a Cloudflare Pages project connected to sonantechai/sonan-trackers on GitHub. Push to main and Pages rebuilds automatically. No build command — pure static HTML.

Pages Project	Root Directory in Repo
sonan-tracker	sonan-tracker/Sonan
harpers-preserve-tracker	sonan-tracker/HP
woodridge-tracker	sonan-tracker/WR
sonantech-timesheet	sonan-tracker/sonan-timesheet/html

Backend Workers (manual deploy)

Workers are deployed via wrangler deploy from Windows terminal. They do NOT auto-deploy from GitHub.

# Task tracker API
cd "E:\Claude_Projects\sonan-trackers\sonan-tracker"
npx wrangler deploy

# Timesheet API
cd "E:\Claude_Projects\sonan-trackers\sonan-tracker\sonan-timesheet"
npx wrangler deploy

Worker Secrets

Set once via Wrangler CLI, stored in Cloudflare (not in wrangler.toml):

# Task tracker
npx wrangler secret put API_KEY        # value: Sonan2026

# Timesheet
cd sonan-timesheet
npx wrangler secret put API_KEY        # value: SonanTS2026
npx wrangler secret put ENCRYPT_KEY    # value: 64-char hex AES-256 key

Authentication — How It Works

Task Trackers (Sonan, HP, WR)

Two-layer client-side protection:

1. Layer 1 — Hardcoded gate: An immediately-invoked function at page load checks a hardcoded password variable embedded in the HTML. This runs before anything else. Password: SONANGroup!. This gate persists across incognito/private browsing because it is in the HTML, not localStorage.
2. Layer 2 — Setup + app password: After passing layer 1, if localStorage.st_api_url is not set, the app shows a setup screen asking for API URL, API key, and a new app password. The app password is SHA-256 hashed and stored in localStorage.st_pw_hash. Subsequent loads show the lock screen requiring the app password.

Timesheet Tracker

Server-side auth via the Worker:

• All requests to the timesheet Worker require header X-API-Key: SonanTS2026. Requests without it return 401 immediately — the frontend will appear broken with no data if the API key is not configured.
• Admin login: username admin, password checked by the Worker against admin_pw_hash in the tax_settings D1 table. Hash format: SHA-256("SONAN_TS_SALT_2026_" + plaintext_password).
• If admin_pw_hash is not set or equals SETUP_REQUIRED, first login sets the password.

Common Mistakes to Avoid

Mistake	Prevention
Timesheet shows no employees / all API calls fail	Frontend must have API URL and API Key configured in Settings. X-API-Key header is required on every request.
Trying to reset task tracker password via localStorage in incognito	Layer 1 password (SONANGroup!) is hardcoded in HTML — localStorage is irrelevant for it. It works the same in incognito.
Deploying worker changes by pushing to GitHub	Workers are NOT connected to GitHub. Must run npx wrangler deploy manually from Windows terminal.
Running wrangler from Claude sandbox	Sandbox cannot authenticate to Cloudflare (403 proxy). All wrangler commands run from user's Windows terminal.
Assuming both workers use separate databases	Both the task worker and timesheet worker bind to the same D1 DB ID (d0e1e4d2). Schema changes affect both.
Using old malikadnanakram worker URLs	All workers are now in sonantechai account. Old malikadnanakram.workers.dev URLs no longer serve current data.