124 lines
7.6 KiB
Markdown
124 lines
7.6 KiB
Markdown
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/."
|