coulomb-social/docs/migration/schema-mapping-sketch-2026-08-12.md

# Schema mapping sketch — Bubble → coulomb-social (provisional)

| Field | Value |
|-------|--------|
| Workplan | CSOC-WP-0001-T02 (partial — no dump yet) |
| Date | 2026-08-12 |
| Depends on | CSOC-WP-0004 content model (done), inventory T01 |

This is a **mapping sketch** so T02 has a target once Bubble export exists.
It is not an executed import.

## Layers

| Layer | System of record (rebuild) | Bubble source (hypothesized) |
|-------|----------------------------|------------------------------|
| Identity | NetKingdom OIDC → `Member(issuer, subject)` | Bubble User — **do not migrate passwords** |
| Space metadata | Postgres `spaces_space` | Space / project type |
| Membership | `spaces_spacemembership` | Collaborator / role |
| Page bodies | Forgejo `pages/*.md` | Page / chunk rich text |
| Assets | Forgejo `assets/` or later object store | Bubble CDN files |
| Social graph | later tables | favorites, follows |
| Marketplace | later or cut | challenges, methods, solutions |

## Identity mapping

| Bubble | Rebuild | Rule |
|--------|---------|------|
| User email | Member.email (profile) | Mutable; **not** account key |
| User _id | optional `bubble_user_id` on Member later | For reconciliation only |
| Password hash | **drop** | NetKingdom owns credentials |
| Login | OIDC | Case A proven; Case B residual |

Linking: prefer verified email **match as suggestion** only after NK registration;
never silent takeover (ADR-0001 / NK-WP-0025).

## Space metadata mapping

| Bubble field (TBD names) | `Space` column |
|--------------------------|----------------|
| name / title | `title` |
| slug or derived | `slug` |
| description | `description` |
| owner user | `created_by` → Member |
| (none) | `tenant_id` = `tenant:coulomb` |
| (none) | `forgejo_owner` / `forgejo_repo` set at import |
| (none) | `content_root` default `pages` |

## Content mapping (pages → markdown)

| Bubble | Forgejo path | App read |
|--------|--------------|----------|
| Home / index page of space | `pages/index.md` | default space detail |
| Named page / chunk | `pages/<slug>.md` | `?page=<slug>` |
| Embedded images | `assets/<file>` + relative links | rendered HTML |
| Bubble-only layout widgets | lose or rebuild as markdown structure | residual list at rehearsal |

Conversion notes:

- Prefer **markdown** export if Bubble plugin/API allows; else HTML → markdown
  with lossy table/embed handling.
- Preserve original Bubble page id in markdown frontmatter:
  `bubble_page_id: …` for re-import idempotency.
- Do not store full page HTML in Postgres.

## Export requirements (for real T02)

Operator needs (not in this repo):

1. Bubble editor access (or Data API with Privacy rules allowing export).  
2. Full type list with fields (Users, Spaces, Pages, …).  
3. CSV/JSON dumps or app connector export — **PII-minimized** copies for rehearsal.  
4. File inventory from CDN / Bubble file manager.

Store dumps outside git (operator disk / encrypted volume). Record **paths and
checksums only** here when available.

## Rehearsal plan (T04 — not started)

1. Pick **one** space with 2–5 pages.  
2. Convert to `pages/*.md` + assets.  
3. Create Forgejo repo under `coulomb-spaces` (or coulomb org).  
4. `Space` row bind + membership for tegwick.  
5. Open on `app.coulomb.social` — record lossiness.

## Stage-1 scope filter

Only map/migrate what **stage-1 capabilities** need first
(`docs/capability/stage-1-cutover.md`): members, spaces, pages (title/abstract/visual
+ body), not marketplace/social unless later promoted.

## Related

- Inventory: `docs/bubble-inventory/2026-08-12-surface-inventory.md`  
- Capability cut: `docs/decisions/2026-08-12-feature-cut-stage-1.md`  
- ADR-0002: `docs/adr/ADR-0002-space-content-forgejo-markdown.md`  
- Spaces models: `coulomb_social/apps/spaces/models.py`