doxa-maps/documentation/HOWTO-join-the-table.md

# How to join the table

You want to build a map. Someone told you there is a repo, a dev server, and a thing called PocketBase, and
now you are staring at three of them wondering which one you are supposed to touch.

Short answer: **you work on your laptop, you land your work on main, and a shared server shows everyone what
landed.** That is the whole shape. The rest of this page is what each of those three is for, and the five
commands you actually type.

> **This page is about working alongside other people.** If you want to know how to build a plugin itself —
> the files, the build, getting it live — read
> [develop-a-plugin-and-see-it-live.md](./develop-a-plugin-and-see-it-live.md) first and come back here when
> you are ready to share your work.

---

## The three places

### 1. Your laptop — the workshop

This is where you build. Everything is local and fast, and nothing you do here can affect anyone else.

```bash
bun install
bun run dev
```

You get the Plugin Studio, hot reload on your own edits, and a local database with your own test data. Break
it, reset it, fill it with nonsense — it is yours.

### 2. `main` — the truth

When your work is ready, it goes to `main`. That is the one place everybody agrees on. Nothing is "real"
until it is there.

### 3. The shared dev server — the table

A server watches `main` and reloads about every 15 seconds. That is where the team sees each other's work without
anyone sending anyone a zip file. You do not edit here. You never need to log into it to do your job.

> **The rule that makes this work:** one plugin folder per person. You edit `plugin-designs/<your-plugin>/`
> and nobody else does. Everything below depends on that.

---

## Getting your work onto main

Three commands, in this order, every time:

```bash
git add -A && git commit -m "what you changed"
git pull --rebase origin main
git push origin HEAD:main
```

If the push is rejected, someone landed first. Run the middle command again and push again. That is not an
error — it is the normal case, and it is worth knowing how normal.

**We measured it.** In a ten-writer stress test at a far faster edit rate than a human works at:

| | |
|---|---|
| pushes rejected, then retried | **95%** |
| merge conflicts | **0** |
| retries needed per edit | 1.1 average, 3 at worst |

Nearly every push got rejected. **Not one caused a conflict.** That is the one-folder-each rule paying off:
you are all pushing to the same branch, so you collide on *who goes first* — but never on the same lines of
code, because you are never in the same file. A rejected push costs you one extra command. It does not cost
you an afternoon untangling someone else's work.

If you *do* hit a real conflict, it means two people edited one file. Stop and talk to the other person;
that is a coordination problem, not a git problem.

---

## Seeing your teammates' work on your laptop (optional)

By default your laptop only reloads on *your* edits. If you want teammates' landed work to arrive
automatically while `bun run dev` is running, copy `.env.example` to `.env.local` at the repo root and set:

```
DX_SYNC_REMOTE=origin
```

That is the only line you need. `.env.local` is never committed, so it stays yours.

> **Either a remote name or a full repo URL works.** `origin` is what almost everyone wants. A URL —
> `https://…/your-repo.git` — works too and saves you a `git remote add`; if the repo is private it uses
> the git credentials your laptop already has. Leave it unset and the whole feature is off.
>
> If you do put a token in the URL (`https://user:token@…`), it is never written to the log or shown at
> `/api/dev-sync`.

Two optional dials, if you want them:

| | what it does | default |
|---|---|---|
| `DX_SYNC_BRANCH` | which branch to follow | `main` |
| `DX_SYNC_INTERVAL` | seconds between checks | `5` (minimum 2) |

**It only pulls when it is completely safe to.** All three must be true: you are on that branch, you have no
unsaved edits, and you have no local commits. If any one of them is not, it does not touch your files —
it tells you instead, in the dev server log:

```
main is 3 commits ahead … pull when ready
```

So it cannot surprise you mid-thought. You can also check that any time at `/api/dev-sync`.

---

## The database, and the one thing that surprises people

There are three databases. You work against one of the first two — never the third.

| Where | What is in it | Who touches it |
|---|---|---|
| Your laptop | your own sandbox data | you, freely |
| The team's shared one | the team's shared test data | the team — this is usually the default |
| Production | what the public sees | nobody directly |

**You never publish a database.** Not yours, not anyone's. What travels is the *shape* — the tables and
fields — as migration files committed to the repo, in `backend/pocketbase/pb_migrations/`.

So adding a field is a normal change: you edit, you commit the migration, you push it like any other file,
and it goes through review with everything else. When the person who publishes runs the publish step, the
migrations apply.

This is deliberate. A database rule that opens something to the public arrives as **a commit someone can
read** rather than as a setting somebody clicked at midnight. If you have ever inherited a system where the
live config did not match the repo, you already know why.

### Which one your laptop talks to

Most teams point every laptop at the **shared** one, so you are all working against the same test data.
Put this in `.env.local`:

```
DX_PB_URL=https://<your team's dev server>/pb
```

You sign in with the same team account you use for everything else — there is no separate password. Ask
whoever set up your team for the address if you do not have it.

**Leave it unset and you get a private one instead.** The first time you run `bun run dev` it downloads and
starts a database on your laptop, with its data in `.pb/`, and you can open its admin screen at
`/api/pb/_/`. That is the fallback, and it is a fine way to work while you are finding your feet.

The only other thing here is `DX_PB_PORT`, which you set only if the log says port 8090 is already in use.

> **New collections start locked.** Your plugin's data is not readable until a migration opens it —
> deliberately, so nothing is public by accident. That migration is a commit like any other.

---

## One more thing to set

The maps need a Mapbox token. It is the one credential you have to ask the team for:

```
VITE_MAPBOX_TOKEN=<ask the team>
```

That, plus `DX_SYNC_REMOTE=origin` if you want it, is the whole of `.env.local`.

---

## The five things to remember

1. **Build on your laptop.** It is fast and it is yours.
2. **One plugin folder per person.** This is what keeps ten people out of each other's way.
3. **`pull --rebase`, then push.** A rejected push is normal — 95% of them were, and none became conflicts.
4. **The shared server is for looking, not editing.**
5. **Schema is a commit, never a click.** You never publish a database.

---

## When something is wrong

- **"Your push was rejected"** — normal. `git pull --rebase origin main`, push again.
- **A real merge conflict** — two people edited one file. Talk to them; the one-folder rule slipped.
- **Your change is not on the shared server** — it reloads about every 15 seconds, not instantly. Check your
  push actually landed: `git log origin/main -1`.
- **The shared server shows an old version of your plugin** — you are probably looking at what is on `main`,
  not what is on your laptop. Those are different on purpose.