rfc-app/docs/design/multi-project.md

# Design sketch — multi-project deployments

> Status: **draft / sketch.** Not binding. This precedes the SPEC edits it
> describes. Decisions captured here were made interactively; open questions
> are flagged inline. When this stabilizes it folds into `SPEC.md` (§1, §2,
> §5, §6, §7, §8, §13, §14, §17, §20) and ships as a pre-1.0 minor with
> upgrade steps.

## The reframe

Today the framework hardcodes **deployment : corpus = 1 : 1**. One deployment
is one Gitea content repo (`META_REPO`), one global slug namespace, one
`VITE_APP_NAME` baked into the build, one flat catalog. SPEC §1 says it
plainly: "this single repository is its content repository."

This change makes it **deployment : project = 1 : N**, where *today's entire
deployment becomes the N=1 case*. A **project** is what a corpus is now: a
content repo, its own slug/`RFC-NNNN` namespace, its own catalog, philosophy,
branding, member roster, and enabled-models universe. The **deployment** (the
subdomain — e.g. Wiggleverse) becomes a thin shell hosting a directory of
projects plus a shared account/notification layer.

OHM becomes one project among several (specs, vision docs, …) under one
deployment.

The value of this framing: the migration stays mechanical. Everything
deployment-scoped today splits cleanly into:

- **stays deployment-scoped** — accounts, the beta/permission gate, the inbox,
  the bot service account, the Gitea org;
- **becomes project-scoped** — the corpus, branding, roles, catalog, philosophy,
  enabled models.

## Decisions (locked)

1. **Project registry lives in git.** A registry (a `projects.yaml` / registry
   repo) declares which projects exist and their config; adding a project is a
   PR. Mirrored into a `projects` cache table. Keeps the git-is-truth invariant.
2. **Projects are membership-gated by default** (private). A non-member does
   not see a private project exists. `visibility` is still a per-project field
   with `public` and `unlisted` escape hatches (see §3) — gated is the default,
   not the only mode.
3. **RFC numbering is per-project.** Each project has its own `RFC-0001`,
   `RFC-0002`… computed as `max(existing IDs in this project) + 1`.

## 1. Git topology — one content repo per project

One Gitea org for the deployment, **N content repos** (`ohm-content`,
`specs-content`, `vision-content`, …). The bot already operates org-wide; it
gains more repos and one registry repo. Slug uniqueness and `RFC-NNNN`
sequences become naturally per-repo = per-project.

Rejected alternatives: subdirectories in one repo (`projects/<id>/rfcs/…`)
churns every path / branch-name / graduation code path and can't carry
git-layer access control per project; prefixed slugs pollute the namespace.

### The registry repo

A small repo (or a top-level file in a deployment repo) the bot reads and
mirrors. Sketch shape:

```yaml
# projects.yaml
deployment:
  name: Wiggleverse
  tagline: ...
projects:
  - id: ohm                      # url slug, stable, unique in deployment
    name: Open Human Model
    content_repo: ohm-content    # repo under the deployment's Gitea org
    visibility: gated            # gated | public | unlisted
    philosophy_repo_path: PHILOSOPHY.md
    enabled_models: [claude, gemini]   # optional; falls back to deployment ENABLED_MODELS
    theme: { accent: "#5b5bd6" }       # optional per-project token overrides
```

Project **definition/config** is in git; project **membership** is in the DB
(it churns like `rfc_collaborators` and is app-state, not document state). The
registry gets the same webhook + reconciler treatment as content repos.

> Open: does the registry get its own repo, or is it a file in an existing
> deployment/meta repo? Ties into the `ohm-rfc-app-flotilla` operator tooling,
> which already owns deploy orchestration and could own registry edits.

## 2. Data model

Introduce a **`projects`** cache table (mirrored from the registry, like
`cached_rfcs` is mirrored from content). Then thread `project_id` through
every RFC-scoped table.

Hard constraint: once slugs are unique only *within* a project, any table
keyed on `rfc_slug` alone is ambiguous, so `project_id` must ride along on all
of them:

- `cached_rfcs` — PK becomes `(project_id, slug)`; `rfc_id` unique per project
- `cached_branches`, `cached_prs`, `pr_resolution_branches`, `proposed_use_cases`
- `threads`, `changes`, `branch_visibility`, `branch_contribute_grants`
- `stars`, `watches`, `pr_seen`, `branch_chat_seen`
- `rfc_invitations`, `rfc_collaborators`, `contribution_requests`, `funder_consents`
- `notifications`, `actions`

~15-table migration, all backfillable to a single default project (see §7).
`api_graduation.py`'s `RFC-NNNN` allocator scopes its `max()` query by
`project_id`.

New tables:

```
projects(
  id TEXT PRIMARY KEY,          -- 'ohm'
  name TEXT NOT NULL,
  content_repo TEXT NOT NULL,
  visibility TEXT CHECK (visibility IN ('gated','public','unlisted')),
  config_json TEXT,             -- theme, tagline, enabled_models, …
  registry_sha TEXT,            -- provenance of the mirrored row
  updated_at TEXT
)

project_members(
  project_id TEXT NOT NULL REFERENCES projects(id),
  user_id INTEGER NOT NULL REFERENCES users(id),
  role TEXT CHECK (role IN ('project_admin','project_contributor','project_viewer')),
  granted_by INTEGER REFERENCES users(id),
  granted_at TEXT,
  PRIMARY KEY (project_id, user_id)
)
```

## 3. Roles — three tiers

A **middle tier** slots between today's deployment roles and per-RFC authority.

| Tier | Who | Powers |
|---|---|---|
| **Deployment** (unchanged, narrowed) | `owner` / `admin` | Create/archive projects, manage all accounts, act in any project. The beta/`permission_state` gate stays here — it gates *having an account*, not project access. A plain authenticated user has an account but no implicit project powers. |
| **Project** (NEW — `project_members`) | `project_admin` / `project_contributor` / `project_viewer` | `project_admin` = today's app-admin, scoped to one project (manage its membership, settings, graduate, act on any RFC in it). `project_contributor` = propose/branch/PR/chat. `project_viewer` = read + discuss only. |
| **RFC** (unchanged) | frontmatter `owners`/`arbiters`; `rfc_collaborators` (`contributor`/`discussant`) | Same as today, now scoped within their project. |

This is the existing owner → admin → contributor delegation pattern with a
project axis added. `users.role` reverts to meaning *deployment*-level only.

**Visibility interaction:**

- **gated** (default) — invisible to non-members; must be a member to see it
  exists. Read and write both require membership.
- **public** — any authenticated user can read; contributing requires a
  `project_contributor` grant.
- **unlisted** — readable by direct link, not shown in the directory.

> Philosophy tension to resolve in SPEC: today the app is open-by-default
> (anonymous read, §11.1; admission gates only writing). Gated-by-default
> reverses that for the common case. The `public`/`unlisted` modes preserve the
> old behavior for projects that want it, and the deployment can choose its own
> default posture — but §11 and §14 need rewriting to make "gated" the baseline
> and anonymous read a per-project opt-in.

**Discovery for gated projects:** since a stranger sees an empty directory,
there must be a join path — invite-only (a `project_admin` adds you), or a
request-to-join surface analogous to the existing §28 contribution-request
flow. (Open — pick one.)

## 4. Branding & frontend (forced change)

The one *forced* change. `VITE_APP_NAME` is baked at build time; you cannot
bake N project names into one bundle. Branding moves to **runtime config
served by the backend**:

- `GET /api/deployment` → deployment name/tagline + the list of projects the
  caller can see (gated ones filtered by membership).
- `GET /api/projects/:id` → that project's name, tagline, philosophy, theme
  tokens.
- Frontend reads these instead of `import.meta.env.VITE_APP_NAME`
  (`App.jsx:208`, `Landing.jsx:16`, `BetaPending.jsx:17`).

`VITE_APP_NAME` is deprecated → deployment name comes from the registry. This
is a documented config change with upgrade steps per CLAUDE.md.

Two chrome layers result:

- **Deployment chrome** — the Wiggleverse header, the project directory /
  landing, a project switcher.
- **Project chrome** — the current header / catalog / philosophy, now per
  project; theme tokens (`tokens.css`) overridable per project at runtime.

## 5. Routing & UX

- RFC routes gain a project prefix: `/p/<project>/rfc/<slug>`,
  `/p/<project>/proposals/<n>`, `/p/<project>/philosophy`, etc.
- Root `/` becomes the **deployment landing = project directory** (the
  Wiggleverse home). For an anonymous or non-member visitor under gated
  default, that's only public/unlisted-by-link projects.
- Breadcrumb gains a segment: `Wiggleverse / OHM / RFC-0042 · Human › main`.
- The left-pane catalog (§7) becomes per-project; a project switcher lives in
  deployment chrome.

## 6. Cross-cutting — notifications, inbox, watches

Accounts are deployment-wide, so there is **one inbox spanning projects**
(§15). `notifications` and `watches` carry `project_id` so the inbox is
filterable and a user can mute an entire project. Quiet hours / digest prefs
stay per-account (deployment level).

## 7. Backward compatibility & migration

The N=1 path keeps existing single-project deployments working:

1. Migration creates one **default project** from current config (`META_REPO`
   → `content_repo`, `VITE_APP_NAME` → `name`, visibility seeded to match the
   deployment's current open posture, likely `public`).
2. Every existing row's `project_id` is stamped to that default project.
3. An optional default-project redirect keeps old `/rfc/<slug>` URLs alive
   (308 → `/p/<default>/rfc/<slug>`).

This is the SPEC §20 upgrade-steps block.

## 8. SPEC & versioning impact

Touches §1, §2, §5, §6, §7, §8, §13, §14, §17, §20. Pre-1.0 minor with
breaking changes spelled out (schema migration, `VITE_APP_NAME` deprecation,
URL change, gated-default philosophy shift). Single-process SQLite stays fine —
`project_id` is just a column; no DB-per-project, no Postgres forced.

## Operator-tooling integration (flotilla)

Checked against the `ohm-rfc-app-flotilla` spec (the OHM deployment's operator
control panel). It assembles a deployment from `{rfc-app@pin} + {non-secret
overlay} + {secret pulls} + {corpus}`, **does not host the corpus** ("the
corpus lives in a deployment-side repo"), and **depends on the framework only
through versioned contracts** (`/api/health`, `VERSION`, CHANGELOG
upgrade-steps, the `.rfc-app-version` pin). The framework knows nothing about
flotilla.

This confirms the registry decision and fixes how it integrates:

- The registry is **deployment-side git content the framework reads** — same
  category as the corpus — *not* a flotilla-owned config blob. Putting
  project definitions in operator tooling would re-bake deployment specifics
  into the assembly layer and add a new framework⇄tool contract.
- The framework reads the registry via a `REGISTRY_REPO` env var, the
  multi-project successor to `META_REPO`. Flotilla's overlay simply swaps one
  ref; its four versioned contracts are untouched.
- Multi-project therefore ships to OHM as an **ordinary pinned-version
  upgrade**: bump the pin, run the §22.13 default-project migration, change
  `META_REPO`→`REGISTRY_REPO` in the overlay, deploy, verify via
  `/api/health`. No flotilla architectural change.

## Open questions

- Gated discovery: invite-only vs. request-to-join surface? (drafted with
  both; M5 can ship invite-only first.)
- Does the deployment landing itself need branding config, or is it derived
  entirely from the registry `deployment:` block?
- Per-project `ENABLED_MODELS` resolution vs. deployment universe (§18, §6.6,
  §6.7 funder) — confirm fallback order.
- Slicing plan for the build (mirrors DEV.md's original slice approach).