suaveplan/openspec/archive/2026-04-25-folder-reorg-by-domain/proposal.md

OpenSpec Change: folder-reorg-by-domain

• Change ID: folder-reorg-by-domain
• Scope: Monorepo-wide structural change
• Status: PROPOSED
• Date: 2026-04-25

---

Summary

Replace the runtime-tier folder split (universal/, browser/, react/, api/, r3f/, server/, finance/, mcp/, python/, gaming/) with a domain-first layout where every folder corresponds 1:1 to a plugin in the upcoming suaveplan-skills marketplace. Tier becomes a per-package property (declared via package.json deps, exports, and the "browser" field) rather than a directory boundary.

Concurrently:

1. Retire @suaveplan/overview (manifest browser library) and replace with a generated MANIFEST.md at the repo root.
2. Retire FOLDERS.yml (replaced by the new layout itself + MANIFEST.md's tier-overlay view).
3. Update every CLAUDE.md and openspec/AGENTS.md path reference from universal/<domain>/<pkg> / packages/<tier>/<pkg> to packages/<plugin>/<pkg>.
4. Add a monorepo-structure capability spec codifying the rules.

Genesis currently has only ~21 packages on disk, so the migration cost is at its lowest. Every package shipped under the legacy layout is one more git mv later.

---

Motivation

The tier-first layout was a quick first cut that has not held up:

• Cross-tier domains are scattered. drive lives in universal/storage/, drive-webrtc in browser/network/, react-drive-sharing in react/platform/, and a future api-plugin-file-upload would land in api/data/ — four directories for one feature surface.
• The same redundancy exists for booking, dmx, audio, video, geo, and almost every gaming feature (universal core + r3f renderer + react UI + api plugin live in 3–4 folders).
• r3f/ is a deprecated category by FOLDERS.yml's own admission — gaming r3f packages were already relocated into gaming/. The remaining three (r3f-earth, r3f-booking, r3f-dmx) are stranded.
• Tier signal is redundant. Whether a package is browser-only is determined by package.json ("browser" field, browser-only deps); the directory adds nothing.
• Plugin marketplace coupling. The forthcoming suaveplan-skills marketplace ships ~50 plugins, each a vertical slice across tiers. If folders mirror plugins, generating the marketplace, scaffolding new packages, and onboarding contributors all collapse to one mental model.

---

Design

New folder layout

packages/
  <plugin-name>/
    <package-name>/
      package.json
      tsconfig.json
      vitest.config.ts
      src/
      tests/
      README.md

Plugin names match the suaveplan-<plugin> keys without the suaveplan- prefix. Inside a plugin folder, package directory names match the package's npm name without the @suaveplan/ prefix.

Plugin → package assignment (51 plugins, all 356 current + 22 future packages)

Foundation

Folder	Packages
packages/foundation/	error, types, typescript-config
packages/observability/	logger, opentelemetry, profiler, audit-logging, network-observability, analytics-browser
packages/primitives/	bytes, timing, datetime, mime, serialize, diff, templates, utils, json, bitpacker
packages/i18n/	i18n, locale-data, react-translate
packages/validation/	validation, schema-registry
packages/control-flow/	retry, idempotency, fsm, undo
packages/config/	env, config, feature-flags
packages/events/	events, events-metrics, events-otel, events-schema, events-transport, event-sourcing, broadcast-channel
packages/streams/	streams, streams-metadata, streams-chunk-queue, queue, queue-distribution
packages/random/	pseudo-random, random, noise

Crypto / Auth / Vault

Folder	Packages
packages/crypto/	crypto, crypto-utils, crypto-hash, crypto-curve, crypto-cipher, crypto-sodium, crypto-browser, crypto-keys, crypto-vault, react-crypto, security-codes
packages/auth/	auth, permissions, jwt-tenant, rate-limiter, oauth-client, slsa, password-formats, macos-keychain, react-auth, react-auth-whitelabel, react-permissions, react-consent-overlay, api-plugin-auth, api-plugin-user, api-plugin-tenant, api-plugin-admin, server-keys, sandbox
packages/vaulted/ (MIGRATION.md future)	keys, vault, vault-sync, srp, otp, cbor, webauthn, native-messaging, password-strength, form-detection, site-icons, hibp, biometrics, password-generator, api-plugin-vault

Data / Storage

Folder	Packages
packages/database/	db, db-sqlite, surrealdb, cache, cache-memory, cache-redis, cache-browser, migration, seed, api-plugin-database
packages/storage/	storage, storage-s3, storage-file, storage-browser, storage-browser-opfs
packages/drive/	drive, drive-sharing, drive-webrtc, react-drive-sharing, react-file-upload, api-plugin-file-upload, packer, packer-browser
packages/data/	etl, crdt, dedup, domain-normalizer, pagination, data-masking, ab-testing, api-plugin-import, api-plugin-export, api-plugin-graphql, api-plugin-analytics
packages/search/	search, api-plugin-search

Network

Folder	Packages
packages/network-core/	network, network-bootstrap, network-failover, network-governance, network-protocol, network-quality, network-registry, network-assignment, network-testing, network-websockets, network-standby-transport, service-discovery
packages/network-p2p/	network-webrtc, network-libp2p, network-libp2p-server, network-hyperswarm, network-trystero-server, network-gundb-server, network-discovery-crdt, network-discovery-gundb, network-discovery-hybrid, network-discovery-peerjs, network-discovery-trystero, network-discovery-webtorrent

API / Platform / UI / Workflow

Folder	Packages
packages/api/	api, api-shared, api-gateway, websocket-gateway, api-docs, api-schemas, docs, sitemap, react-docs, api-plugin-rate-limit, api-plugin-audit, api-plugin-sse, api-plugin-webhook, api-plugin-vatdash-bridge, webhook-client, api-plugin-cms, api-plugin-site, api-plugin-events
packages/platform/	cli, electrobun, readline, web-workers, pwa, clipboard, macos-contacts, react-iphone, linter, health-check, job-scheduler, caddy-imgproxy, iconz
packages/react-ui/	react-ui, react-modal, react-dnd, react-hotkeys, react-error-boundary, react-notifications, react-loading, react-store, react-charts, react-timeline, react-color-picker, react-calendar, react-rich-text, react-command-palette, react-kanban, react-tour, react-skeleton, react-infinite-scroll, react-tree-view, react-data-table, react-virtual
packages/workflow/	workflow, rules, form-builder, react-forms, react-admin-forms, react-rule-builder, react-wizard

Communications

Folder	Packages
packages/email/	email-processing, email-templates, campaigns, contacts, suppression, delivery-tracking, dmarc, audience-rules, emailer, react-campaigns, react-contacts, api-plugin-campaigns, api-plugin-contacts
packages/messaging/	sms, sms-providers, notification-channel, api-plugin-messaging, api-plugin-notifications
packages/social/	slack-client, discord-client, telegram-client, imessage-adapter, message-bridge, react-social, react-ui-social, api-plugin-social

Commerce / Logistics

Folder	Packages
packages/payment/	payment, payment-providers, license, api-plugin-payment, api-plugin-banking, api-plugin-subscription, api-plugin-store
packages/currency/	currency, currency-providers, money, cryptocurrency
packages/booking/	booking, r3f-booking
packages/logistics/	ports, react-port-tracking, api-plugin-logistics, api-plugin-customs, api-plugin-procurement, api-plugin-warehouse-ops, api-plugin-asset-register, api-plugin-inventory, api-plugin-gtap, api-plugin-port-tracking

Geo / Astronomy

Folder	Packages
packages/geo/	geo, geo-earth, geo-planet, heightmap-tiles, osm-buildings, r3f-earth, react-map
packages/astronomy/ (universe spec)	universe, solar-system, stars, tides

Media (per modality)

Folder	Packages
packages/media/	media, metadata, exif
packages/image/	image, image-quantisation, compress-image, react-image
packages/svg/	compress-svg, emblem-solver
packages/fonts/	font-compress, font-decompress, font-convert, font-subset, react-font-decompress
packages/video/	video, video-thumbnails, react-video
packages/audio/	audio-engine, audio-plugins-fx, audio-controllers, audio-sprite-packer, voice, voice-elevenlabs, react-audio, react-audio-player, react-audio-stream, react-audio-fingerprint, python-audio-fingerprint
packages/pdf/	pdf, react-pdf
packages/dmx/	dmx, r3f-dmx
packages/codes/	barcode, qrcode, qrcode-scan

Dev / MCP

Folder	Packages
packages/dev/	testing, testing-dom, testing-e2e, testing-integration, testing-integration-surrealdb, testing-integration-redis, testing-integration-postgres, testing-integration-mailpit, testing-integration-typesense, testing-integration-garage-s3, test-vite, storybook-test-utils, wip
packages/mcp/	mcp

Gaming (per gaming subdomain)

Folder	Packages
packages/gaming-engine/	ecs, game-loop, spatial-hash, game-persistence, game-server, game-state-schemas, controller, react-controller, api-plugin-game-server, api-plugin-game-persistence
packages/gaming-rigs/	character-physics, vehicle-physics, mixamo, bone-mapping, ik-solver, animation-events, character-vehicle-picker, r3f-character, r3f-character-vehicle, r3f-character-vehicle-picker, r3f-animation, r3f-vehicle, r3f-controller
packages/gaming-combat/	combat, weapons, hitbox, destructibles, r3f-combat
packages/gaming-ai/	behavior-tree, npc, fauna, r3f-npc, r3f-pathfinding
packages/gaming-narrative/	dialogue, quest, crafting, progression, economy, react-dialogue, react-crafting
packages/gaming-world/	building, day-night (deprecated), weather, fruit-machine, r3f-building, r3f-buildings, r3f-environment, r3f-vegetation, r3f-water, r3f-weather, r3f-terrain, r3f-world, gaming-universe, gaming-environment-lighting
packages/gaming-multiplayer/	lobby, party, chat, emotes, leaderboard, r3f-networking, api-plugin-matchmaking, api-plugin-anticheat, react-social-game, api-plugin-bank, api-plugin-virtual-currency, react-bank
packages/gaming-ui/	react-game-hud, react-game-map, react-game-settings, r3f-ui, r3f-minimap, r3f-inventory
packages/gaming-effects/	r3f-particles, r3f-shaders, r3f-parallax, r3f-audio, r3f-lod, r3f-performance, r3f-camera, r3f-number-plate, r3f-emulator, r3f-xr
packages/gaming-physics/	r3f-physics-core, r3f-physics-rapier, r3f-physics-cascade

---

MANIFEST.md (replaces @suaveplan/overview)

A repo-root MANIFEST.md is generated by scripts/generate-manifest.ts from on-disk truth (each package's package.json). It provides:

1. Plugin × package table — every plugin folder, every package within, dependency count, coverage status, npm version.
2. Tier-overlay view — packages grouped by inferred tier (universal / browser / react / r3f / server / python) for the rare case someone wants the old listing. Tier is inferred from engines, "browser" field, peer deps (react, @react-three/fiber), and bin entries.
3. Dependency graph — DOT-format adjacency list embedded in a fenced code block; can be piped to Graphviz.
4. Stale-manifest CI check — a CI job runs bun scripts/generate-manifest.ts --check and fails if the committed MANIFEST.md differs from the regenerated output.

@suaveplan/overview is deleted from packages/ (it is currently published at 0.1.0 to Verdaccio; per genesis convention pre-1.0.0 deletion is a bun scripts/unpublish.ts --package @suaveplan/overview operation).

---

Migration approach

Single bulk migration in one PR. A long-running rename branch is the worst of both worlds; everything in packages/ moves at once, in one mechanical commit, followed by a configuration-update commit.

1. scripts/migrate-folders.ts — reads the assignment table from this proposal (or a sibling assignment.yml), runs git mv packages/<old>/<pkg>/ packages/<plugin>/<pkg>/ for every package, and updates root package.json workspaces glob (packages/*/* covers every plugin/package pair).
2. Path updates in configs:
   • turbo.json — no changes needed (uses workspace globs).
   • Every vitest.config.ts referencing path.resolve(__dirname, '../../testing/...') — paths are auto-correct because they're relative to each package and the new layout still has packages/<plugin>/<pkg>/ as the same depth.
   • tsconfig.json paths mapping — regenerate.
   • Per-package package.json exports — unchanged (relative to package root).
3. Doc updates:
   • CLAUDE.md package list paths.
   • openspec/AGENTS.md — every universal/<domain>/<pkg> reference becomes packages/<plugin>/<pkg>.
   • Existing OpenSpec changes' proposals — leave historic; only update tasks.md for in-flight changes.
4. Delete FOLDERS.yml.
5. Generate MANIFEST.md for the first time, commit it.
6. Add CI check bun scripts/generate-manifest.ts --check.

---

Out of scope

• Renaming any package. Only directories move; npm names stay identical.
• Changing exports or APIs. Pure structural change.
• Migrating off Verdaccio for republish. Republishes happen as part of normal pre-publish gates after the move.

---

Impact

• Every package on genesis (~21 currently shipped + ~5 in flight) gets a git mv. No code change required inside packages.
• All in-flight OpenSpec changes that reference target paths (enterprise-booking, enterprise-testing-*, etc.) need their Target path: line updated. This is mechanical.
• Existing @suaveplan/overview consumers (none in genesis source — it was a leaf manifest reader) lose the package; the replacement is reading MANIFEST.md directly or running scripts/generate-manifest.ts.
• Future suaveplan-skills marketplace can be generated directly from the folder layout: each packages/<plugin>/ becomes one plugin manifest.

---

References

• FOLDERS.yml (current layout, to be deleted)
• MIGRATION.md (Vaulted future packages — assigned to packages/vaulted/)
• docs/superpowers/specs/2026-04-25-universe-family-design.md (universe family — assigned to packages/geo/ + packages/astronomy/ + packages/gaming-world/)
• ../suaveplan/README.md (full 356-package inventory, source for assignment table above)
• CLAUDE.md § "Packages" — every path reference will be updated.