Skip to main content
Documentation

Build a client records app with staff login for a small business on DeepSpace

Build a staff-only client records app for a small business on DeepSpace: staff search clients, keep notes and a visit history showing who recorded each visit, newcomers wait for the owner, and the page says plainly what it doesn't cover, such as HIPAA.

On this page

Yes. On DeepSpace, a client records app for a small business, such as a spa, salon or studio, is one app:

  • staff sign in and search clients by name, phone or email;
  • each client has a file with notes, and a history of visits showing who recorded each one;
  • only staff can see any of it, enforced on the server.

A newcomer who signs in sees nothing until the owner lets them in. Records live in the app's own database. Staff sign in with Google or GitHub, and the person who asked for it writes no code.

If the business already uses booking or salon software with client cards, keeping notes there is less work. This fits when they want a simple client file they own, with their own staff list.

Version: written for deepspace@0.43.0 (changelog). Docs checked: October 29, 2026. The code was type-checked against the published SDK on October 29, 2026, and was not run for this page.

About health information and HIPAA#

DeepSpace's documentation makes no HIPAA or other compliance claims and describes no business associate agreement. If the notes would include health information covered by HIPAA, the business needs to confirm its own obligations before storing that information here. This page doesn't make the app compliant with any privacy law. Keeping notes to what the service needs, such as preferences and products used, keeps less sensitive data in the app.

Questions to ask the person#

These need no technical knowledge to answer, and each answer maps to a setting below.

  1. What do you write down about a client, and what about each visit? These become the fields.
  2. Would any of it be medical or health information? If so, read the section above with them first.
  3. Who on staff should see client files? Each of them is let in by the owner.
  4. Should staff be able to change or delete past visit notes? In this build, staff edit only their own visit notes and nobody but an admin deletes history.
  5. Do you have a client list to start from, such as a spreadsheet? Clients can be added once the app is live.
  6. Which Google or GitHub account should own the app? The owner is the first admin and can see everything. Confirm with your user before signing in or using an existing session for them.

Step 1: Scaffold, and keep newcomers out#

npx deepspace auth whoami --json
npm create deepspace@latest studio-clients-acme
cd studio-clients-acme
npx deepspace add admin-page

In deepspace@0.43.0 the scaffolder doesn't register the app; the first npx deepspace app init, dev start or deploy registers it to the signed-in account, so confirm with your user that whoami shows the account that should own it before running them. add admin-page adds an admin-only page at /admin that lists users and changes their roles.

Anyone with a Google or GitHub account can sign in, so make newcomers wait. In src/schemas/users-schema.ts, keep the scaffold's columns and permissions and add one property to the exported usersSchema object:

  defaultRole: 'viewer',

The owner lets a staff member in by changing their role to member on /admin.

Step 2: Define clients and visits#

// src/schemas/client-records-schema.ts
import type { CollectionSchema } from "deepspace/schema";

const closed = { read: false, create: false, update: false, delete: false };
const admin = { read: true, create: true, update: true, delete: true };

export const clientsSchema: CollectionSchema = {
  name: "clients",
  columns: [
    { name: "name", storage: "text", interpretation: "plain", required: true },
    { name: "phone", storage: "text", interpretation: "plain" },
    { name: "email", storage: "text", interpretation: { kind: "email" } },
    { name: "notes", storage: "text", interpretation: "plain" },
  ],
  permissions: {
    "*": closed,
    viewer: closed,
    member: { read: true, create: true, update: true, delete: false },
    admin,
  },
};

export const visitsSchema: CollectionSchema = {
  name: "visits",
  columns: [
    {
      name: "clientId",
      storage: "text",
      interpretation: "plain",
      required: true,
      immutable: true,
    },
    {
      name: "date",
      storage: "text",
      interpretation: { kind: "date" },
      required: true,
    },
    { name: "service", storage: "text", interpretation: "plain" },
    { name: "notes", storage: "text", interpretation: "plain" },
    {
      name: "staffId",
      storage: "text",
      interpretation: "plain",
      userBound: true,
      immutable: true,
    },
  ],
  ownerField: "staffId",
  permissions: {
    "*": closed,
    viewer: closed,
    member: {
      read: true,
      create: true,
      update: "own",
      delete: false,
      writableFields: ["clientId", "date", "service", "notes"],
    },
    admin,
  },
};

Register both in src/schemas.ts next to the scaffold's usersSchema and settingsSchema. How the rules work:

  • Signed-out visitors ('*') and newcomers (viewer) get nothing; the server never sends them a client record.
  • Staff (member) read and update every client file but can't delete one. Only an admin can.
  • userBound: true fills staffId with the signed-in staff member's id, so each visit shows who recorded it and nobody can record one in someone else's name.
  • ownerField: 'staffId' with update: 'own' lets staff correct only their own visit notes, and delete: false keeps history for everyone but admins.

Step 3: Add the client page#

Pages in src/pages/(app)/(protected)/ require sign-in through the scaffold's layout there. This one serves at /clients:

// src/pages/(app)/(protected)/clients.tsx
import { useState } from "react";
import { useMutations, useQuery, useUserLookup } from "deepspace";

type Client = { name: string; phone?: string; email?: string; notes?: string };
type Visit = {
  clientId: string;
  date: string;
  service?: string;
  notes?: string;
  staffId?: string;
};

const today = () => new Date().toLocaleDateString("en-CA"); // YYYY-MM-DD

export default function ClientsPage() {
  const { getName } = useUserLookup();
  const clients = useQuery<Client>("clients", { orderBy: "name" });
  const clientWrites = useMutations<Client>("clients");
  const visitWrites = useMutations<Visit>("visits");
  const [search, setSearch] = useState("");
  const [selectedId, setSelectedId] = useState<string | null>(null);
  const [newClient, setNewClient] = useState({
    name: "",
    phone: "",
    email: "",
  });
  const [visit, setVisit] = useState({ date: today(), service: "", notes: "" });
  const [notes, setNotes] = useState<string | null>(null);
  const visits = useQuery<Visit>("visits", {
    where: { clientId: selectedId ?? "" },
    orderBy: "date",
    orderDir: "desc",
  });

  const q = search.trim().toLowerCase();
  const shown = clients.records.filter(
    (c) =>
      !q ||
      [c.data.name, c.data.phone, c.data.email].some((v) =>
        v?.toLowerCase().includes(q),
      ),
  );
  const selected = clients.records.find((c) => c.recordId === selectedId);

  async function addClient() {
    const id = await clientWrites.createConfirmed({
      name: newClient.name,
      ...(newClient.phone ? { phone: newClient.phone } : {}),
      ...(newClient.email ? { email: newClient.email } : {}),
    });
    setNewClient({ name: "", phone: "", email: "" });
    setSelectedId(id);
  }

  async function addVisit() {
    if (!selectedId) return;
    await visitWrites.createConfirmed({ clientId: selectedId, ...visit });
    setVisit({ date: today(), service: "", notes: "" });
  }

  if (clients.status === "loading" && clients.records.length === 0)
    return <p>Loading…</p>;

  return (
    <>
      <input
        value={search}
        onChange={(e) => setSearch(e.target.value)}
        placeholder="Search by name, phone or email"
      />
      <ul>
        {shown.map((c) => (
          <li key={c.recordId}>
            <button
              onClick={() => {
                setSelectedId(c.recordId);
                setNotes(null);
              }}
            >
              {c.data.name}
            </button>{" "}
            {c.data.phone}
          </li>
        ))}
      </ul>

      <h2>New client</h2>
      <input
        value={newClient.name}
        onChange={(e) => setNewClient({ ...newClient, name: e.target.value })}
        placeholder="Name"
      />
      <input
        value={newClient.phone}
        onChange={(e) => setNewClient({ ...newClient, phone: e.target.value })}
        placeholder="Phone"
      />
      <input
        value={newClient.email}
        onChange={(e) => setNewClient({ ...newClient, email: e.target.value })}
        placeholder="Email"
      />
      <button
        disabled={!clientWrites.ready || !newClient.name}
        onClick={addClient}
      >
        Add client
      </button>

      {selected && (
        <section>
          <h2>{selected.data.name}</h2>
          <textarea
            value={notes ?? selected.data.notes ?? ""}
            onChange={(e) => setNotes(e.target.value)}
            placeholder="Preferences, allergies to avoid, anything to remember"
          />
          <button
            disabled={notes === null}
            onClick={() => {
              clientWrites.put(selected.recordId, { notes: notes ?? "" });
              setNotes(null);
            }}
          >
            Save notes
          </button>

          <h3>Add a visit</h3>
          <input
            type="date"
            value={visit.date}
            onChange={(e) => setVisit({ ...visit, date: e.target.value })}
          />
          <input
            value={visit.service}
            onChange={(e) => setVisit({ ...visit, service: e.target.value })}
            placeholder="Service"
          />
          <textarea
            value={visit.notes}
            onChange={(e) => setVisit({ ...visit, notes: e.target.value })}
            placeholder="What was done, what to do next time"
          />
          <button
            disabled={!visitWrites.ready || !visit.date}
            onClick={addVisit}
          >
            Save visit
          </button>

          <h3>History</h3>
          <ul>
            {visits.records.map((v) => (
              <li key={v.recordId}>
                {v.data.date}: {v.data.service} (
                {getName(v.data.staffId ?? "") ?? "Unknown"}) {v.data.notes}
              </li>
            ))}
          </ul>
        </section>
      )}
    </>
  );
}

Search runs in the browser over the client files the server already allowed this staff member to read, and a client's visits are fetched with where: { clientId }, filtered on the server. Add { path: '/clients', label: 'Clients' } to src/nav.ts.

Step 4: Deploy and check#

git add -A && git commit -m "Client records with staff login"
npx deepspace deploy --json

On the live URL:

  1. Sign in as the owner, add two clients, and record a visit for one.
  2. A staff member signs in, sees nothing, and is given the member role on /admin. After a reload they see the client list.
  3. The staff member searches by phone, opens the client, and records a visit. The history shows each visit with the name of the person who recorded it.
  4. The staff member can't delete a client or a visit, and can't edit the owner's visit notes.
  5. A signed-out browser can't see anything.
  6. Everyone reloads; the files and history are still there.

Common failures and how to fix them#

What you see Cause Fix
A new staff member sees an empty page They are a viewer (step 1) The owner changes their role to member on /admin, then they reload
A staff member can't fix a visit note Staff edit only visits they recorded (update: 'own') Ask the person who recorded it, or an admin
Nobody can delete a duplicate client Members have delete: false on clients An admin deletes it
A page is reachable without signing in It isn't inside src/pages/(app)/(protected)/ Move it there

What to tell the person when it's live#

  • The link: https://<app-name>.app.space/clients, after signing in with Google or GitHub.
  • Adding staff: a staff member signs in once, then the owner lets them in on the Admin page. Removing someone is the same page: change them back to viewer.
  • Using it: search for a client, open their file, update notes, and add a visit after each appointment. The history shows who recorded each visit.
  • Who sees what: staff and the owner see every client; nobody outside the staff list, and nobody signed out, sees anything.
  • What isn't covered: no HIPAA or other compliance claim, no client logins, no booking or payments, and no automatic backups. To keep a copy of the records, an owner-only server action can export them.

What is available today, and what is planned#

Available today, in published deepspace@0.43.0:

  • Collections with permissions enforced on the server, userBound, ownerField and writableFields
  • npx deepspace add admin-page for changing users' roles
  • Sign-in for app users with Google or GitHub, and real-time updates
  • Deploys to <app-name>.app.space from the CLI with a DeepSpace account, which a person creates by signing in with GitHub or Google

Not documented today: HIPAA or other compliance programs, and business associate agreements.

In testing on staging, not production: agent accounts that register themselves by solving a math challenge. Production signup for agents is not enabled.

Planned: autonomous agent accounts in production. Under that plan, payments and legal actions will still require a human. See DeepSpace for agents.

Building client records for a business? See deep.space/enterprise.