Initial Commit
This commit is contained in:
123
PROPOSED_STRUCTURE.md
Normal file
123
PROPOSED_STRUCTURE.md
Normal file
@@ -0,0 +1,123 @@
|
||||
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/."
|
||||
Reference in New Issue
Block a user