1. Repo Structure & File Ownership
The monolith was split so parallel Claude sessions can build without overwriting each other. One feature, one file.
Golden rule: two sessions must never edit the same file at the same time. Shared files (
js/config.js, js/shared.js, index.html, css/styles.css) are edited by ONE session, in the same session as the feature needing the change. Always git pull before starting, push promptly after committing.
| Feature | Edit this file | Notes |
|---|---|---|
| Leadership Dashboard KPIs | js/dashboard.js | Loads the shared global data arrays for everyone |
| Cash flow / balance calculator | js/cashflow.js | Forecast, UC checks, what-if |
| Reconciliation engine | js/reconciliation.js | Matching, knowledge base, accuracy tracking; rate-limit pattern lives here |
| Invoices | js/invoices.js | Fetch, render, match, approve, pay |
| CFVs / rent statements | js/cfv.js | Overdue rent detection, chase actions |
| Costs / transactions / income / P&L | js/costs.js · js/transactions.js · js/income.js · js/pnl.js | Finance section tabs |
| Money Confidence / Wealth | js/money.js · js/wealth.js | Personal finance layer |
| Arrears | js/arrears.js · js/ar-variable.js | Rent balance per tenancy |
| Fintable monitor | js/fintable.js | Bank sync health |
| Site map & links | js/sitemap.js | Also SOP update requests |
| AI assistant panel | js/ai-assistant.js | Context blocks per tab live here |
| Skills / KPI sources / quick task | js/skills.js · js/skills-data.js · js/kpi-sources.js · js/quick-task.js | |
| Health bars | js/sync-bar.js | registerSyncBar engine — shared, treat like shared.js |
| Operating Systems pages | os/*/index.html | tasks, operations, strategy, systemisation, team, business-plan-builder — loaded via iframe |
| Standalone iframe pages | follow-up.html · compliance.html · ai-brain.html | Each self-contained |
| Styling | css/styles.css (consumes css/tokens.css) | Whole-app look changes: tokens.css ONLY |
| Sidebar / tab shell | index.html | Protected: OS sidebar items, OS iframe tab panels |
| Constants, table + field IDs | js/config.js | F, TABLES, INV, REC, PS, PAGE_REGISTRY, AI model IDs |
Root directory mapLayout
index.html— shell only: sidebar, tab containers, no logic*.htmliframe pages —follow-up,compliance,ai-brain,how-it-workssop*.html— SOP per page*-supabase.html+supabase-app.html— shadow-build twins (§5)*-shim.js— 5 fetch-override shims for the twins (§5)architecture.html/dev-blueprint.html— the two mapscss/js/os/docs/scripts/tests/supabase-migration/MASTER-PLAN.md— THE only plan ·STRUCTURE.md— file-location source of truth ·PRODUCTISATION.md— de-Kevining spec
Branch strategyRule
- Small fixes, single-file tweaks: push directly to
main - New features, multi-file, anything touching shared files: branch → PR (
feature/…orfix/…) - Parallel sessions can sweep uncommitted edits into other commits — commit before context-switching
- If a feature vanishes, check git history before reimplementing
Protected sections in index.htmlRule
Never remove when restructuring the shell:
- Sidebar OS menu items and their health dots
- OS iframe tab panels:
tab-tasks,tab-operations,tab-systemisation,tab-os-strategy,tab-os-team,tab-os-bplan - PAGE_REGISTRY OS entries in
js/config.js
2. JS Internals — Globals, Helpers, Conventions
All JS loads as plain <script> tags in one global scope. No bundler, no modules. Load order: config.js → shared.js → feature files.
Global variablesjs/config.js + dashboard.js
PAT— Airtable auth token, set by the auth flow. Never log it, never hardcode it.- Data arrays loaded by
dashboard.js:allTransactions,allTenancies,allTenants,allCosts,allCategories,allSubCategories,allBusinesses - Constants:
F(field IDs),TABLES,INV,REC,PS - AI models:
AI_MODEL_DEFAULT,AI_MODEL_LIGHT— feature files must use these, never a literal model ID
shared.js helper cataloguejs/shared.js
- Data:
airtableFetch(tableId, params)(handles pagination) ·getField·getNumVal·lookupValues·txDisplayAmount·getActiveBusinesses - Status logic:
isTenancyActive·isTenancyIncome·isTenantStatusActive/Former·isCostActive·getPaymentStatusName - Security:
escHtml(str)for ALL external text into HTML ·escJs(str) - UI:
expandableCard·toggleCard·switchTab(tabId)·showToast·showConfirm·openQuickTaskModal - Health:
updateSidebarHealth(tabId, status)· sync bars viaregisterSyncBarinjs/sync-bar.js - Robustness:
limitedApiFetch(rate limit) ·nextRenderGen/isCurrentRender(render race guard) ·smartRefresh+ idle auto-refresh
Known anti-patterns (real production bugs)Check every build
- Missing Number() on PATCH — Airtable number fields reject strings:
fields: { [F.amount]: Number(value) } - Partial re-render stale state — after inline edit/status/filter change call the full
renderAll(), not the single-item updater - returnFieldsByFieldId — this project uses field NAMES via
Fconstants; field-ID keys silently read undefined - CSS overflow truncation — long names need ellipsis or
word-break: break-word - localStorage quota — Safari caps at 5MB; large caches go to IndexedDB (dashboard.js pattern), localStorage is small UI state only, keys namespaced per feature (
cfv_,recon_…) - Linked-record filters — filter by record ID, never ARRAYJOIN display names
Forbidden patternsNever introduce
console.log/debuggerin production paths- Silent
catchblocks (must log or toast) - Secrets or PAT tokens hardcoded anywhere
- Hardcoded AI model IDs in feature files (a retired ID is an app-wide AI outage)
eval(),document.write(),Function()constructorinnerHTMLwith unescaped external data — useescHtml()- Hardcoded colours or fonts — design tokens only (§1 of CLAUDE.md design system)
3. Deploy Pipeline
The repo is the source of truth. Push to main → GitHub Pages auto-deploys in 2-3 minutes → confirm live before declaring done.
Deploy flowPipeline
- Live URL:
https://chaichoong.github.io/leadership-dashboard/ git push origin main→ Pages build → poll the deploy monitor script in the background until live- Never say "done" after pushing — the task completes when the deploy is confirmed live (watch stale browser cache; hard reload)
- Rollback = identify the revert commit BEFORE deploying anything risky
Version tracking (PAGE_REGISTRY)Automation
PAGE_REGISTRYinjs/config.jstrackspageVer/sopVerper page.github/workflows/auto-bump-pagever.ymlbumpspageVerautomatically when a page's source file hits main- File→page mapping lives in
scripts/pre-commit-action.py— update it when adding pages - Local hooks:
scripts/pre-commit(version bump) andscripts/pre-push(test gate) — symlink into.git/hooks/ sopVeris bumped manually when the SOP catches up with the page
Scheduled jobsGitHub Actions + local
monthly-valuations.yml— property valuations run, 1st of the month (needsPROXY_SERVICE_TOKENsecret)sync-ai-brain.yml— publishes the AI Brain feedsync-transactions.yml— transaction syncscripts/sync-master-plan.py— nightly plan↔Airtable sync: ticks MASTER-PLAN from Airtable completions, pushes approved plan tasks to Airtable
4. Testing & Quality Gates
Nothing ships unverified. Kevin never debugs — the session that builds it proves it works.
Sync-invariant suitePlaywright
tests/sync-invariants/— 11 spec files (33 tests): active-business filter, auth token handling, badge count sync, cascade sync, CFV detection, no-crash-on-load, and more- Run:
npm run test:sync - A local pre-push gate (not committed to the repo) blocks failing pushes to main
Unit testsVitest
tests/shared.test.js— shared helper coverage- The
/test-gapsskill generates Vitest tests for untested paths in changed files: data writes and business logic first, trivial getters skipped
Quality pipeline (every build/fix)Skills
Order, run by
/build-feature and /fix automatically:
- Self-audit →
/verify(browser proof) → simplify pass →/test-gaps→ independent review gate (blocking) → security review when auth/data/money →/pre-deploychecklist → deploy → confirm live →/testagainst production
5. Supabase Migration — the Shadow Build
Airtable stays the system of record until per-module cutover. A parallel Supabase/Vercel build runs alongside via twins and shims. Spec: docs/supabase-schema-spec.md.
Twin pages + fetch shimsPattern
supabase-app.html— the shell for the migrated app (deploys to Vercel)*-supabase.htmltwins mirror live pages: index, accounts, pnl, money, wealth, ai-brain, follow-up, skills*-shim.js(5:dashboard,wealth,ai-brain,comms,skills) overridewindow.fetchand translate Airtable REST calls into Supabase queries — so the original feature JS runs unmodified- Shims load NON-deferred, before feature code, and can chain (a page can load several)
- Shims await the Supabase session before the first query (fixes blank-data-on-load)
Migrations statesupabase-migration/
- In repo:
0015_systemisation·0016_app_settings·0017_objectives_strategy·0018_ai_brain·0019_wealth - 0001–0014 applied to the project but pending commit to the repo (MASTER-PLAN §4 task, Mica)
- Tenancy spine applied:
tenants,tenant_users,tenant_config,ai_usage_log - Open: RLS policy audit, tenant_id retrofit on every table, entities table (D1)
Cutover rulesRule
- Per-module cutover, not big-bang. A module cuts over when its twin loads real data on Vercel and passes the parity check
- Until then every write goes to Airtable; the shadow build is read-mirrored
- Replace any Airtable automation a migrating page depends on before its cutover
- Target: launch on Vercel + Supabase by early August 2026
6. Docs & Specs Registry
Which document governs what. If it is not listed here, check STRUCTURE.md before creating a new one.
| Document | Governs | Rule |
|---|---|---|
MASTER-PLAN.md | THE plan: every OD roadmap, launch task, priority | Never create another plan doc. Amendments via §13 holding pen, dated + sourced in the Changelog |
STRUCTURE.md | Where every file lives: repo, AI context layer, Drive | Read before creating any file; update in the same commit if you add a new location |
CLAUDE.md | Session rules: stack, workflow, quality gate, design system, concurrency | The contract every session works under |
PRODUCTISATION.md | De-Kevining: D1-D9 decisions, tenant model | §5 holds the decided outcomes |
docs/supabase-schema-spec.md | Target Postgres schema, RLS approach | Migration source of truth |
docs/agent-runtime-spec.md | How agents execute (engine live since 3 Jul 2026) | |
docs/agentic-extraction-spec.md | Loom → SOP → agent pipeline (the core product engine) | |
docs/business-blueprint-spec.md | Client-facing Blueprint tab ("% of work run by AI") | v1 = view over existing data |
docs/client-profile-questionnaire.md | Onboarding interview that writes tenant_config | |
docs/airtable-cleanse-2026-07-07.md | Record of the 7 Jul task cleanse | Historical |
7. AI Layer
Everything AI-facing: model routing, prompts, skills, memory. The north star: AI agents execute up to 90% of repeatable operational work.
Model routingjs/config.js
AI_MODEL_DEFAULT— main model for in-app AI featuresAI_MODEL_LIGHT— cheap model for light tasks- Feature files import these constants. A hardcoded model ID that later retires takes down every AI feature at once — this happened; do not repeat it
- Requests route through the claude-proxy worker; per-tenant AI keys (D9) are in build
Promptsjs/prompts/
js/prompts/boardroom-mentor.js— the single source of truth for every AI wizard's voice. All wizards import it; never fork the tone per featurejs/ai-assistant.js— the chat panel; per-tab context blocks (e.g.ctx.compliancePage) tell the AI what the user is looking at. New features that hold data Kevin might ask about add a context block here
Claude Code skills.claude/skills/
In-repo skills that drive the workflow:
build-feature— end-to-end build pipeline (BILD → plan → build → audit → review → deploy)fix— same pipeline for bugs and amendmentsaudit·verify·test·test-gaps·pre-deploy·health-bar
~/.claude/skills/.
Memory + AI BrainOutside the repo
- Claude Code project memory — persistent facts across sessions (MEMORY.md index + one file per fact)
- AI Brain vault — Google Drive
00 AI Context: founder profile, priorities, meetings, transcripts. Nightly compound engine links and reviews it - The AI Brain page (
ai-brain.html) reads a published Airtable feed — sensitive items are link-only pointers, never copied - Agent engine: live testing since 3 Jul 2026; agents come from the Systemisation pipeline (Loom → SOP → readiness → shadow → live)