Architecture
These pages explain the durable, cross-cutting mechanisms that span multiple packages or feature areas — the repo-wide answer to "whenever we need X, we do it this way". Area-specific features live under their own sections (for example /docs/platform or /docs/esbabbler).
| Page | What it covers |
|---|---|
| Platform | The cross-product layer model — identity, resources, datasets, publishing, events |
| Resources | The standard for product persistence and surface — resource model, capabilities, factory |
| Datasets | The standard for serving tabular data — contract, DatasetProvider capability, row cap |
| Publishing | The Publishable capability — versioned publish copy + rate-limited public read |
| Auth | better-auth OAuth setup, session middleware, and the authed procedure chain |
| Azure services | Azure service ownership, the storage split, event flows, and the real-time layer model |
| Environment | Environment detection across the three Nuxt runtime contexts |
| File uploads | The two-step Azure Blob SAS upload pattern and upload procedure inventory |
| Serialization | How class instances survive the three transport paths (Azure Table, Nuxt payload, tRPC) |
| Client data access | The useQuery + useMutation primitives — non-blocking fetch, optimistic apply, staleness |
| Async operations | Concurrency by declaration — reads are latest-wins, writes queue, nothing drops silently |
| Persisted data — latest shape only | No legacy-shape schemas or migration code — parse the latest shape or reset |
| Content token rewriting | Finding tokens in authored content — self-delimiting matches, one pass, converge on read |
| Monorepo tooling | pnpm workspace orchestration, virrun routing, publishing, installs, and CI job shape |
| Server testing | tRPC router test wiring — in-memory DB, mocked Azure services, controlled auth session |
| Destructive confirmation | One shared delete dialog — StyledDeleteFormDialog + opt-in type-the-name guard |
| Singleton dialogs | Store-driven singleton dialogs — one mounted dialog per feature, never one per list item |
| Navigation | NuxtLink/navigateTo for every link — never a raw anchor — and instant docs routing |
| Persist then notify | Guard, persist, notify — then best-effort bookkeeping that can never fail the caller |
| Conditional writes | A write derived from a read is conditional on that version, and a lost race re-applies |
| Blob lifecycle ownership | Every blob prefix's naming discipline and single teardown owner per lifecycle event |
| No polling | Polling banned repo-wide — every wait is event-driven or awaits a completion handle |
| No manual recovery | Failed async work retries itself on an event, with an attempt cap and a quarantine |
| Null vs undefined | One absent-value sentinel in app-owned code — null survives only in boundary shapes |
| Search | One search stack — StyledSearchDialog palettes + useAutoSearch/useCursorSearcher |