suaveplan/PROPOSED_STRUCTURE.md

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.

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

8. 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."

9. 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.

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

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

12. 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.

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

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

15. 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/."