Getting started — BMS dashboard development¶

Welcome to the BMS codebase. This guide gets you from zero to making your first change. Follow it step by step — don't skip ahead.

Important: Throughout this guide, when you see terminal commands, enter them one at a time. Type (or paste) one command, press Enter, wait for it to finish, then move to the next. Don't paste multiple commands at once.

What you're working with¶

You'll be building dashboards inside our BMS (Business Management System). The BMS is a React + TypeScript app backed by Supabase, deployed on Vercel. You'll use VS Code as your editor and Claude Code (CC) as your AI coding assistant — it lives inside VS Code and can read, write, and run your code.

This is different from OpenClaw. OpenClaw is an autonomous agent you chat with from your phone. Claude Code is a developer tool — you open your 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 production 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 to GitHub — all from inside VS Code. Once you get into the flow, it's fast.

Step 1: Install VS Code¶

Download from https://code.visualstudio.com/ and install it. It's free.

Step 2: Install Claude Code¶

Open Terminal on your Mac (Cmd + Space, type "Terminal", hit Enter) and run:

curl -fsSL https://claude.ai/install.sh | bash

After it installs, run:

claude --version

You should see a version number. If you do, it's working.

Now run:

claude

It will open your browser and ask you to sign in. Sign in with the company Claude account (subscriptions@matthewscleaningco.com.au). This is the same account you already use for Claude and OpenClaw.

Step 3: Install the Claude Code VS Code extension¶

Open VS Code
Press Cmd+Shift+X to open Extensions
Search for "Claude Code"
Install the one published by Anthropic (it has millions of installs)

You'll see a spark icon (✱) in the sidebar — that's Claude Code.

The extension gives you a chat panel inside VS Code where you talk to CC, with inline diffs showing proposed changes, accept/reject buttons, and normal copy/paste shortcuts (Cmd+C / Cmd+V). This is the recommended way to work with CC day-to-day.

Step 4: Install Git (if not already installed)¶

Open Terminal and run:

git --version

If Git is already installed, you'll see a version number — move on to Step 5.

If it's not already installed, macOS will pop up a dialog offering to install Xcode Command Line Tools. Click Install and wait for it to finish (a few minutes). Then run git --version again to confirm.

Step 5: Authenticate with GitHub¶

The repo is private, so you need to authenticate with GitHub before you can clone it. First, check your email for Glenn's GitHub invitation and accept it.

Now install the GitHub CLI:

brew install gh

Then log in:

gh auth login

It will ask you a series of questions. Choose: - GitHub.com - HTTPS - Yes (authenticate Git with GitHub credentials) - Login with a web browser

It will give you a one-time code, open your browser, and ask you to paste the code. Do that, then authorise the app. Once Terminal says "Logged in", you're done.

Step 6: Clone the repo¶

cd ~

git clone https://github.com/glenn-mcc/mcc-systems.git

cd mcc-systems

Now open the project in VS Code:

code .

If the code command doesn't work, open VS Code manually, then press Cmd+Shift+P, type "Shell Command: Install 'code' command in PATH", and hit Enter. Then try code . again.

Step 7: Install Node.js and project dependencies¶

Claude Code's native installer doesn't need Node.js, but the BMS project does (it's a Node.js/React app). Open Terminal and run:

node --version

If you get a version number (18 or higher), skip to the npm ci step below. If not, install Node.js:

Go to https://nodejs.org/
Download the LTS version (the recommended one)
Run the installer
Close and reopen Terminal, then run node --version to confirm

Now install the project dependencies:

cd ~/mcc-systems/apps/bms

npm ci

This downloads all the libraries the BMS needs. It takes a minute or two the first time.

Step 8: Supabase MCP¶

The repo includes a .mcp.json file that connects Claude Code to our Supabase dev database. This lets CC query tables, create migrations, and manage the database — all from within VS Code.

You don't need to configure anything. The first time CC tries to use a Supabase tool, it will open your browser and ask you to log in to Supabase. Glenn needs to invite you to the Supabase organisation first — check with him before this step. Log in when prompted and grant access.

The MCP connection is locked to the dev database only. This is intentional — MCP should never talk to production.

Step 9: Configure Git identity¶

cd ~/mcc-systems

git config user.name "Jordan Matthews"

git config user.email "jordan@matthewscleaningco.com.au"

Step 10: Verify everything works¶

Open the Claude Code panel in VS Code (click the ✱ icon in the sidebar) and try:

What files are in src/resources/dashboards/?

CC should list DashboardsIndex.tsx. If it does, you're connected and ready.

Now try a build:

Please run npm run build from apps/bms and tell me the result.

If the build succeeds, you're fully set up.

Step 11: Read the dashboard development guide¶

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.

How the workflow works¶

Open VS Code with the mcc-systems project
Open Claude Code (click the ✱ icon in the sidebar)
Start the dev server — tell CC: "start the dev server". This launches the BMS locally so you can test your changes before pushing. The dev server stays running in the background while you work — you don't need to restart it.
Tell CC what you want to build — describe the dashboard, the data it should show, the layout
CC proposes changes — you see inline diffs showing exactly what it wants to add or modify
Review and accept — you approve each change
CC runs the build — catches any errors before you commit
Test on dev — go to http://localhost:5180/ and check your changes look and work as expected (bookmark this URL)
When you're happy, tell CC: "commit, push and make live" — CC handles everything: committing to GitHub, deploying any database changes or Edge Functions, and your code goes live on Vercel within 30–60 seconds
Sanity check on prod — go to https://bms.matthewscleaningco.com.au/ and do a quick check that your changes are live and working (bookmark this URL too)

When to use Claude.ai (Opus) instead of Claude Code¶

Claude Code is great at executing well-defined tasks: build this component, add this route, fix this error. But for bigger-picture thinking, use Claude.ai in the browser (select the Opus model). Specifically:

Planning a new feature — before telling CC to build something complex, talk it through with Opus first. Describe what you want the dashboard to do, what data it needs, how it should look. Opus will help you think through the design and write step-by-step instructions for CC.
Tricky problems CC is struggling with — if CC keeps going in circles on a bug or produces code that doesn't work, copy the error and relevant context into a new Claude.ai thread. Opus can analyse the problem with fresh eyes and give you instructions to relay back to CC.
Architecture decisions — if you're unsure whether to use an Edge Function vs a direct Supabase query, how to structure your data, or whether something is within your allowed boundaries, ask Opus.
Writing specs — for non-trivial features, Opus can help you write a spec (see docs/admin/spec-and-plan-guide.md) before you start building.

Think of it this way: Opus is the architect, CC is the builder. You can go straight to CC for simple tasks, but for anything that needs planning or problem-solving, start with Opus.

Tips¶

Start small. Your first task should be something simple — maybe display a list of data from a table. Get the full cycle working (code → build → push → live) before attempting anything complex.
CC reads CLAUDE.md automatically. This file contains all the project conventions. You don't need to memorise them — CC follows them.
If CC suggests modifying a file outside your area, that's a red flag. Push back and ask it to find a way within the dashboards folder.
If you want to build something non-trivial (new database tables, Edge Functions, multi-page features), write a quick spec first. See docs/admin/spec-and-plan-guide.md for the format. This saves time by forcing you to think through the design before CC starts coding.
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 (prod)	bms.matthewscleaningco.com.au