# 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.

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](https://deep.space/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

```bash
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:

```ts
  defaultRole: 'viewer',
```

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

## Step 2: Define clients and visits

```ts
// 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`:

```tsx
// 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

```bash
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](https://docs.deep.space/guides/server-actions) 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](https://docs.deep.space/agents).

Building client records for a business? See [deep.space/enterprise](https://deep.space/enterprise).
