Poposed top-level structure


  ────────────────────────────

  ┌────────────────┬───────────────────────────────────────────────────────────────────┐
  │ New Top-Level  │ Current Folders / Sub-categories that move inside                 │
  ├────────────────┼───────────────────────────────────────────────────────────────────┤
  │ foundation/    │ core, data, random, timing, bitpacker, barcode, flow              │
  │ persistence/   │ database, storage, cache                                          │
  │ network/       │ network, drive, events                                            │
  │ communication/ │ messaging, emails (+ webhook-client from the old platform bucket) │
  │ api/           │ api, gtap, vatdash                                                │
  │ auth/          │ auth                                                              │
  │ security/      │ security, crypto                                                  │
  │ monitor/       │ monitor                                                           │
  │ media/         │ audio, audio-fx, audio-ir, image, fonts, video                    │
  │ react/         │ react, forms                                                      │
  │ r3f/           │ r3f                                                               │
  │ i18n/          │ i18n                                                              │
  │ geo/           │ geo                                                               │
  │ finance/       │ finance, payment                                                  │
  │ commerce/      │ booking, store, contacts, logistics                               │
  │ testing/       │ testing                                                           │
  │ tooling/       │ tooling, docs, docker                                             │
  │ games/         │ games                                                             │
  └────────────────┴───────────────────────────────────────────────────────────────────┘

  ─────────────────────────────────────────────────────────────────────────────────────────────────────────

  Rationale for the groupings
  ───────────────────────────

  1. foundation/
  ──────────────
  Everything that is runtime-agnostic, zero-dependency (or near-zero), and imported by higher layers. flow
  fits here because cbor, crdt, retry, streams, rules, queue, etc. are infrastructure primitives, not busin
  ess logic.

  2. persistence/
  ───────────────
  All passive data retention: database adapters, migration tools, key-value storage, S3/OPFS/File backends,
  and cache implementations. These share the concern of "write bytes somewhere, read them back later."

  3. network/
  ───────────
  The distributed-systems stack. drive is kept here because its value proposition is P2P mesh transport (We
  bRTC, HTTPS, chunk gossip, signed envelopes); it is not just storage. events is the pub/sub bus that unde
  rpins both drive and network.

  4. communication/
  ─────────────────
  User-facing or outbound message delivery: email, SMS, Slack/Discord/Telegram, DMARC, suppression lists, w
  ebhooks. This is "talk to humans or external systems."

  5. api/
  ───────
  The Hono-centric server platform and all api-plugin-* packages. gtap and vatdash are just thin bridge plu
  gins — they belong here.

  6. auth/ & 7. security/
  ───────────────────────
  Split intentionally. auth is identity, sessions, OAuth, WebAuthn, permissions. security is cryptography,
  vaults, certificates (x509, JWS), password tools, SRP, TPM. They are related but auth is a consumer of se
  curity, not the same domain.

  8. monitor/
  ───────────
  Observability triple: logging, OpenTelemetry SDK wiring, audit-logging. Small but distinct enough to avoi
  d polluting api or security.

  9. media/
  ─────────
  The entire audio graph (core, fx plugins, IR engine), plus image processing, video, and font pipelines. T
  hese are all "create, transform, or render sensory content."

  10. react/ & 11. r3f/
  ─────────────────────
  Kept separate because react is already ~25 packages and growing; r3f will be ~40+ game/rendering packages
  . Combining them would recreate the bloat you're trying to solve. forms lives under react because every f
  orm package is a React surface.

  12. i18n/
  ─────────
  Large enough to deserve its own top-level: core ICU parser, 5+ backend adapters, 7+ formatters, locale da
  ta, and React bindings.

  13. geo/
  ────────
  Astronomy, tides, solar system, star catalogs, and geospatial geometry. Self-contained domain.

  14. finance/ & 15. commerce/
  ────────────────────────────
  Split by layer. finance is the money stack: money, currency, all currency-provider-*, payment, all paymen
  t-provider-*. commerce is the business domain on top: bookings, store, inventory, subscriptions, contacts
  , logistics.

  16. testing/
  ────────────
  Testcontainers, E2E fixtures, DOM helpers, A/B testing. Cross-cutting but cohesive.

  17. tooling/
  ────────────
  CLI toolkit, installer, readline, docs generators (sitemap, SVG compress), Docker assets. "Things develop
  ers run, not things apps import at runtime."

  18. games/
  ──────────
  The massive upcoming game-engine stack: ECS, physics, combat, progression, quests, NPCs, building, vehicl
  es, and all their React/R3F UI layers. It deserves its own silo.

  ─────────────────────────────────────────────────────────────────────────────────────────────────────────

  What this eliminates
  ────────────────────
  • The platform/ catch-all (its contents are split into foundation, api, communication, and monitor).
  • The unknown/ bucket in STATUS.md — every package now has a logical home.
  • The commerce/ mega-category from STATUS.md — split into finance (money/payments) and commerce (business
    perations).

  This gives you 18 folders at the packages/ root instead of 41, with each current category neatly nested a
  s a sub-folder. Scanning the repo becomes trivial: "Is it a base primitive? foundation/. Is it a UI compo
  nent? react/ or r3f/. Is it about money? finance/."