Skip to content

Developing dashboards

This guide covers everything specific to dashboard development in the BMS. It assumes you've already completed the new developer setup.

What you're working with

You'll be building dashboards inside the BMS (Business Management System) — a React + TypeScript app backed by Supabase, deployed on Vercel. Your work is contained to a dedicated dashboards section of the codebase, isolated from the core BMS by rules that are enforced automatically at build time.

This is different from OpenClaw. OpenClaw is an autonomous agent you chat with from your phone. Claude Code is a developer tool — you open the project in VS Code, tell CC what to build, review the changes it proposes, and approve them. It's more hands-on, but that's by design: you're building software that real people use, so you stay in control of every change.

The upside: CC reads the entire codebase, understands the project structure, follows the dev guide rules automatically, runs the build to catch errors, and commits and pushes to GitHub — all from inside VS Code. Once you get into the flow, it's fast.

Before you build anything

Tell CC:

Please read docs/admin/dashboard-development-guide.md and give me a summary.

This is the most important document for your work. It defines what you can and can't do. The key points:

  • Your code lives in src/resources/dashboards/ — that's the only folder you work in (with three small exceptions for adding routes and nav items)
  • You can read any database table but only write to tables prefixed dashboard_
  • You can create Edge Functions prefixed dashboard- but can't modify existing ones
  • You can import shared components (@/components/*, @/hooks/*, @/types/*, @/lib/*) but NOT from other resource folders like opportunities/ or services/ — the build will fail if you try
  • Every new route needs a permission entry in route-permissions.ts or users get a silent "no access" error

CC reads this guide automatically before working in the dashboards folder, so it'll keep you on track. But reading it yourself means you'll understand why CC makes the decisions it does.

The development workflow

  1. Open VS Code with the mcc-systems project
  2. Open Claude Code (click the ✱ icon in the sidebar)
  3. Pull from GitHub — tell CC: "Please pull from GitHub". Always do this at the start of a session to make sure you're working from the latest code.
  4. Start the dev server — tell CC: "Start the dev server". This launches the BMS locally so you can test changes before pushing. It stays running in the background while you work.
  5. Tell CC what you want to build — describe the dashboard, the data it should show, the layout
  6. CC proposes changes — you see inline diffs showing exactly what it wants to add or modify
  7. Review and accept — you approve each change
  8. CC runs the build — catches any errors before you commit
  9. Test locally — go to http://localhost:5180/ and check your changes look and work as expected (bookmark this URL)
  10. When you're happy, tell CC: "commit and push" — CC commits your changes and pushes to GitHub
  11. Let Glenn know — your changes are now on GitHub but not yet live. Glenn runs the production deployment manually. Drop him a message and he'll make it live.
  12. Sanity check on prod — once Glenn confirms it's deployed, go to https://bms.matthewscleaningco.com.au/ and check your changes are live and working (bookmark this URL too)

Tips

  • Start small. Your first task should be something simple — maybe display a list of data from a table. Get the full cycle working before attempting anything complex.
  • If CC suggests modifying a file outside src/resources/dashboards/ (other than the three permitted exceptions for routing and nav), that's a red flag. Push back and ask it to find a way within the dashboards folder.
  • For anything non-trivial — new database tables, Edge Functions, multi-page features — write a quick spec first using Claude.ai. See docs/admin/spec-and-plan-guide.md. This saves time by forcing you to think through the design before CC starts coding.
  • CC reads CLAUDE.md automatically. This file contains all the project conventions. You don't need to memorise them.
  • If you get stuck, ask Glenn. But try CC first — it's surprisingly good at debugging its own mistakes.

Quick reference

What Where
Your code apps/bms/src/resources/dashboards/
Dashboard dev guide docs/admin/dashboard-development-guide.md
Project conventions CLAUDE.md (repo root)
Route permissions apps/bms/src/lib/route-permissions.ts
Router (add routes) apps/bms/src/components/AppRouter.tsx
Sidebar (add nav items) apps/bms/src/components/app-sidebar.tsx
Edge Functions supabase/functions/dashboard-*/
Migrations supabase/migrations/
Spec guide docs/admin/spec-and-plan-guide.md
BMS URL (local) http://localhost:5180/
BMS URL (prod) bms.matthewscleaningco.com.au