MCC Systems — Overview¶

This document explains what we've built, how the pieces fit together, and how development works. It's written for anyone who needs to understand the system at a high level — no code knowledge required.

What we have¶

We have two web applications, both built in the same codebase:

BMS (Business Management System) — our internal tool. Used by Tom, Jordan, Glenn, and other staff to manage the business: quoting, opportunities, services, contracts, sites, contacts, and organisations. It lives at bms.matthewscleaningco.com.au.

Client Portal — the external-facing app. Clients log in to see their quality reports, scope of work, costs, support tickets, and proposals/contracts. It lives at portal2.matthewscleaningco.com.au.

Both apps share the same database and the same backend functions.

How they're built¶

Both apps are built with React (a JavaScript framework for building user interfaces) and TypeScript (JavaScript with type safety). The user interface components, pages, and logic are all written in this stack.

The backend uses Supabase, which provides two things:

A PostgreSQL database where all our data lives (organisations, services, contracts, pricing, etc.)
Edge Functions — small server-side scripts that handle specific tasks like fetching data, sending emails, or talking to external services

The client portal also talks to Airtable (our older database, still used for quality reports, scope of work, support tickets, and org/site data) and Xero (for invoice and cost data). These connections go through Edge Functions — the apps never talk to Airtable or Xero directly.

How they fit together¶

┌──────────────────────────────────────────────────────────────┐
│                        The Internet                          │
│                                                              │
│   bms.matthewscleaningco.com.au    portal2.matthewscleaningco.com.au
│              │                                │              │
└──────────────┼────────────────────────────────┼──────────────┘
               │                                │
        ┌──────┴──────┐                  ┌──────┴──────┐
        │     BMS     │                  │   Client    │
        │  (React)    │                  │   Portal    │
        │             │                  │  (React)    │
        └──────┬──────┘                  └──────┴──────┘
               │                                │
               │     Both hosted on Vercel      │
               │                                │
               └───────────┬────────────────────┘
                           │
                           ▼
               ┌───────────────────────┐
               │   Supabase Edge       │
               │   Functions           │
               │   (backend logic)     │
               └───┬───────┬───────┬───┘
                   │       │       │
                   ▼       ▼       ▼
              Supabase  Airtable  Xero
              Database  (legacy)  (invoicing)

Supabase database is the primary data store. The BMS reads and writes everything here — organisations, sites, services, opportunities, contracts, pricing, shifts, areas, tasks.
Airtable is the older system. The client portal still reads quality reports, scope of work, support tickets, and org/site data from Airtable. Over time, we're migrating these to Supabase, but it's not urgent.
Xero provides invoice data. The client portal's cost pages pull service and consumable invoices from Xero via Edge Functions.
Edge Functions sit between the apps and the data. They handle all the logic: fetching from the right source, combining data, enforcing access control, and returning clean JSON to the frontend.

The codebase¶

Everything lives in a single monorepo (one Git repository containing both apps and all shared infrastructure): github.com/glenn-mcc/mcc-systems.

mcc-systems/
  apps/
    bms/                    ← BMS app (React + TypeScript)
    client-portal/          ← Client Portal app (React + TypeScript)
  supabase/
    migrations/             ← Database change scripts (version-controlled)
    functions/              ← Edge Functions (shared by both apps)
      _shared/              ← Common utilities used across functions
      portal-contract/      ← Example: handles contract data
      portal-reports/       ← Example: handles quality reports
      bms-pricing/          ← Example: handles BMS pricing logic
      ...
  docs/                     ← Documentation
  scripts/                  ← Deployment and maintenance scripts

The monorepo means both apps are always in sync — a single commit can update the BMS, the portal, an Edge Function, and the database schema together.

How development works¶

Development is done with Claude Code (CC) — an AI coding assistant that runs in VS Code. Glenn (and potentially Jordan for dashboards) writes instructions, CC executes them: creating files, writing code, modifying the database, and deploying to the dev environment.

There are two database environments:

Dev — a sandboxed copy for development and testing. CC works here. No real data, safe to break.
Production — the live database with real data. Users interact with this.

CC can freely make changes on dev. Nothing it does there affects the live system.

Database changes (new tables, columns, seed data) are captured in migration files — SQL scripts stored in the repo. This is critical: migration files are the single source of truth for the database schema. Direct changes via the Supabase dashboard are not allowed because they'd be lost on a branch reset and invisible to the rest of the system.

How deployment works¶

Frontend changes (anything in apps/bms/ or apps/client-portal/) deploy automatically. When code is pushed to GitHub, Vercel detects it and deploys both apps within a couple of minutes.

Database changes and Edge Functions require a manual step. After a CC session that includes these changes, Glenn tells CC to "make live" and CC runs the appropriate deploy scripts.

A nightly health check runs automatically to catch anything that was pushed to GitHub but not deployed to production. If it finds a mismatch, it creates a GitHub notification.

For full deployment details, see Deploying changes to production.

Key people and roles¶

Person	Role	System access
Jordan	Managing Director, business owner	BMS dashboards, portal oversight, business decisions. Starting to do some development via Claude Code.
Glenn	Director of Technology	Full technical access — builds and maintains everything via Claude Code
Gian	Junior dev / potential offsider	Learning Supabase+React, building warehouse tool, helps with Airtable
Tom	Sales / account manager	Primary BMS user — manages opportunities, quoting, proposals
Deb	Finance	Xero (invoicing). Accounting outsourced externally

Where to learn more¶

Topic	Where to look
How to deploy changes	Deploying changes to production
Why we use migration files	Development environment & database change management
Hosting and DNS setup	Hosting & production infrastructure
BMS dashboard development	Getting started — BMS dashboard development
Detailed technical docs	`docs/` folder in the mcc-systems repo