# Build a searchable internal link directory for a team on DeepSpace

Build a private, searchable link directory for a team on DeepSpace: teammates search and tag shared links, each link shows who added it, newcomers wait for an admin, and a weekly scheduled check marks links that stopped working.

Yes. On DeepSpace, a team's link directory is one app:

- a private page where teammates search and filter shared links by title, description or tag;
- each link showing who added it;
- a weekly check that marks links that have stopped working.

Only signed-in teammates see it, and that rule is enforced on the server. A newcomer who signs in sees nothing until an admin lets them in. Links live in the app's own database. People sign in with Google or GitHub, and the person who asked for it writes no code.

If the team already keeps its links on a wiki or intranet page that people use, adding to that is less work. This fits when the team wants one searchable list it owns, with an owner for each link and a check for dead ones.

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

## Questions to ask the person

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

1. **Who should see the links?** They get access from an admin; everyone else sees nothing.
2. **Who can add links: everyone on the team, or a few people?** Everyone on the team, by default.
3. **How do you group links today: by team, by tool, by topic?** Those become tags.
4. **Do some links open only inside the company network or after a sign-in?** The weekly check reports those as "Needs sign-in" or "Couldn't reach" instead of "Broken".
5. **Do you already have a list to start from?** It can be added once the app is live.
6. **Which Google or GitHub account should own the app?** The owner is the first admin. 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 team-links-acme
cd team-links-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. `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',
```

An admin lets a teammate in by changing their role to `member` on `/admin`.

## Step 2: Define the links collection

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

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

export const linksSchema: CollectionSchema = {
  name: "links",
  columns: [
    { name: "title", storage: "text", interpretation: "plain", required: true },
    {
      name: "url",
      storage: "text",
      interpretation: { kind: "url" },
      required: true,
    },
    { name: "description", storage: "text", interpretation: "plain" },
    { name: "tags", storage: "text", interpretation: { kind: "json" } },
    {
      name: "linkStatus",
      storage: "text",
      interpretation: {
        kind: "select",
        options: ["unchecked", "ok", "private", "broken", "unreachable"],
      },
      default: "unchecked",
    },
    { name: "lastChecked", storage: "text", interpretation: { kind: "date" } },
  ],
  uniqueOn: ["url"],
  permissions: {
    "*": closed,
    viewer: closed,
    member: {
      read: true,
      create: true,
      update: "own",
      delete: "own",
      writableFields: ["title", "url", "description", "tags"],
    },
    admin: { read: true, create: true, update: true, delete: true },
  },
};
```

Register it 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 doesn't send them a single link.
- Members read every link and add their own. `'own'` lets only the person who added a link edit or remove it; admins can change any link.
- `writableFields` keeps `linkStatus` and `lastChecked` for the weekly check, so nobody marks their own link as working.
- `uniqueOn: ['url']` refuses a second copy of the same link.

## Step 3: Check every link once a week

Scheduled tasks run in the app's own `CronRoom`. Replace the scaffold's empty `src/cron.ts`:

```ts
// src/cron.ts
import type { CronTask } from "deepspace/worker";
import { buildCronContext } from "deepspace/worker";
import type { Env } from "../worker";

export const tasks: CronTask[] = [
  // Every Monday at 08:00 New York time.
  { name: "check-links", schedule: "0 8 * * 1", timezone: "America/New_York" },
];

async function checkLink(url: string): Promise<string> {
  try {
    let res = await fetch(url, { method: "HEAD", redirect: "follow" });
    if (res.status === 405 || res.status === 501)
      res = await fetch(url, { redirect: "follow" });
    if (res.status === 401 || res.status === 403) return "private"; // behind a sign-in; can't tell more
    return res.status < 400 ? "ok" : "broken";
  } catch {
    return "unreachable";
  }
}

export async function runTask(name: string, env: Env): Promise<void> {
  if (name !== "check-links") return;
  const ctx = buildCronContext(
    env,
    env.OWNER_USER_ID,
    `app:${env.DEEPSPACE_APP_ID}`,
  );
  // query returns record envelopes: { recordId, data, ... }
  const links = (await ctx.records.query("links", { limit: 500 })) as Array<{
    recordId: string;
    data: { url: string };
  }>;
  const today = new Date().toISOString().slice(0, 10);
  for (const link of links) {
    const linkStatus = await checkLink(link.data.url);
    await ctx.records.update("links", link.recordId, {
      linkStatus,
      lastChecked: today,
    });
  }
}
```

The cron context runs as the app owner, so it can update every link. The scaffold's `worker.ts` already registers `src/cron.ts`, and a deploy arms the schedule. Each run logs `[cron] check-links ok` or `[cron] check-links failed: …`, which `npx deepspace logs --search cron` shows. The check runs from the internet, so a link that opens only inside the company network reports "Couldn't reach". See [scheduled jobs](https://docs.deep.space/guides/scheduled-jobs).

## Step 4: Add the directory page

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

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

type Link = {
  title: string;
  url: string;
  description?: string;
  tags?: string[];
  linkStatus?: string;
  lastChecked?: string;
};

const STATUS_LABEL: Record<string, string> = {
  unchecked: "Not checked yet",
  ok: "Working",
  private: "Needs sign-in",
  broken: "Broken",
  unreachable: "Couldn't reach",
};

const EMPTY = { title: "", url: "", description: "", tags: "" };

export default function LinksPage() {
  const { userId } = useAuth();
  const { getName } = useUserLookup();
  const { records, status } = useQuery<Link>("links", { orderBy: "title" });
  const { createConfirmed, remove, ready } = useMutations<Link>("links");
  const [search, setSearch] = useState("");
  const [tag, setTag] = useState("");
  const [form, setForm] = useState(EMPTY);
  const [error, setError] = useState("");

  const allTags = [
    ...new Set(records.flatMap((r) => r.data.tags ?? [])),
  ].sort();
  const q = search.trim().toLowerCase();
  const shown = records.filter(
    (r) =>
      (!tag || r.data.tags?.includes(tag)) &&
      (!q ||
        [
          r.data.title,
          r.data.description,
          r.data.url,
          ...(r.data.tags ?? []),
        ].some((v) => v?.toLowerCase().includes(q))),
  );

  async function add() {
    setError("");
    try {
      await createConfirmed({
        title: form.title,
        url: form.url,
        description: form.description,
        tags: form.tags
          .split(",")
          .map((t) => t.trim())
          .filter(Boolean),
      });
      setForm(EMPTY);
    } catch {
      setError("Not added. That link may already be in the directory.");
    }
  }

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

  return (
    <>
      <input
        value={search}
        onChange={(e) => setSearch(e.target.value)}
        placeholder="Search links"
      />
      <select value={tag} onChange={(e) => setTag(e.target.value)}>
        <option value="">All tags</option>
        {allTags.map((t) => (
          <option key={t} value={t}>
            {t}
          </option>
        ))}
      </select>

      <ul>
        {shown.map((r) => (
          <li key={r.recordId}>
            <a href={r.data.url} target="_blank" rel="noreferrer">
              {r.data.title}
            </a>
            {r.data.description && <p>{r.data.description}</p>}
            <small>
              {(r.data.tags ?? []).join(", ")} · added by{" "}
              {getName(r.createdBy) ?? "Unknown"} ·{" "}
              {STATUS_LABEL[r.data.linkStatus ?? "unchecked"]}
              {r.data.lastChecked ? ` on ${r.data.lastChecked}` : ""}
            </small>
            {r.createdBy === userId && (
              <button onClick={() => remove(r.recordId)}>Remove</button>
            )}
          </li>
        ))}
      </ul>

      <h2>Add a link</h2>
      <input
        value={form.title}
        onChange={(e) => setForm({ ...form, title: e.target.value })}
        placeholder="Title"
      />
      <input
        value={form.url}
        onChange={(e) => setForm({ ...form, url: e.target.value })}
        placeholder="https://…"
      />
      <input
        value={form.description}
        onChange={(e) => setForm({ ...form, description: e.target.value })}
        placeholder="What it's for"
      />
      <input
        value={form.tags}
        onChange={(e) => setForm({ ...form, tags: e.target.value })}
        placeholder="Tags, separated by commas"
      />
      <button disabled={!ready || !form.title || !form.url} onClick={add}>
        Add link
      </button>
      {error && <p role="alert">{error}</p>}
    </>
  );
}
```

Search runs in the browser over the links the server already allowed this person to read. Add `{ path: '/links', label: 'Links' }` to `src/nav.ts`.

## Step 5: Deploy and check

```bash
git add -A && git commit -m "Team link directory"
npx deepspace deploy --json
```

On the live URL:

1. Sign in as the owner and add a few links with tags.
2. A teammate signs in, sees nothing, and is given the `member` role on `/admin`. After a reload they see the links.
3. The teammate adds a link; the owner sees it without reloading, with the teammate's name on it.
4. Adding the same URL again shows "Not added".
5. Only the person who added a link sees **Remove** on it.
6. A signed-out browser can't see the list.

To run the link check without waiting for Monday, an admin can trigger it with `useCronMonitor`; see [scheduled jobs](https://docs.deep.space/guides/scheduled-jobs). Then check the status labels.

## Common failures and how to fix them

| What you see                                             | Cause                                                               | Fix                                                                                                                |
| -------------------------------------------------------- | ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| A teammate sees an empty page                            | They are a `viewer` (step 1)                                        | An admin changes their role to `member` on `/admin`, then they reload                                              |
| "Not added"                                              | `uniqueOn: ['url']` refused a link that is already in the directory | Search for it; it's already there                                                                                  |
| Every link says "Not checked yet"                        | The check hasn't run since deploy                                   | Wait for Monday, or trigger `check-links` from `useCronMonitor`; `npx deepspace logs --search cron` shows each run |
| A working internal link says "Couldn't reach"            | The check runs from the internet, not inside the company network    | Expected for intranet links                                                                                        |
| A link that needs a company sign-in says "Needs sign-in" | The site answered 401 or 403                                        | Expected; the check can't see behind a sign-in                                                                     |
| Someone can't edit a link they didn't add                | Members update only their own links (`'own'`)                       | Ask the person who added it, or an admin                                                                           |
| The check stops partway in a very large directory        | `records.query` was limited to 500 links                            | Raise the `limit` in `src/cron.ts`                                                                                 |

## What to tell the person when it's live

- **The link:** `https://<app-name>.app.space/links`, after signing in with Google or GitHub.
- **Joining:** a new person signs in, then an admin lets them in on the Admin page.
- **Adding and finding links:** add a link with a title, a short description and tags; search by any word, or pick a tag.
- **Who looks after each link:** each link shows who added it; that person and admins can change or remove it.
- **Dead links:** every Monday the app checks each link and marks it Working, Broken, Needs sign-in or Couldn't reach.
- **Privacy:** nobody outside the team, and nobody signed out, can see the list.

## What is available today, and what is planned

Available today, in published `deepspace@0.43.0`:

- Collections with permissions enforced on the server, `uniqueOn` and `writableFields`
- `npx deepspace add admin-page` for changing users' roles
- Scheduled tasks in the app's `CronRoom`, with run lines in `npx deepspace logs`
- 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

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 internal tools for a business? See [deep.space/enterprise](https://deep.space/enterprise).
