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 platform or 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 |
| Caching | One cached-read primitive, invalidated by tag when a write says what it changed |
| Persisted data — latest shape only | No legacy-shape schemas or migration code — parse the latest shape or reset |
| No compatibility debt | A wrong name, shape or deployed identity is corrected in place — never aliased |
| 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 |
| Build pipeline | One bundler, shared build presets, and an external list derived from each manifest |
| Agent configuration | The vendor-neutral .agents tree, its .claude alias, and what stays out of the docs |
| Server testing | tRPC router test wiring — in-memory DB, mocked Azure services, controlled auth session |
| Dialog shell | One dialog shell — StyledDialog owns the card, the body slot and the actions row |
| 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 |
| Notifications | One typed event, one Function, fanned out to the surfaces its type declares |
| 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 |
| Module boundaries | The app's three import zones — shared/ may never reach into the client-only app tree |
| Browser execution | Where app/ runs — persisted state, a client-only phase, and the one use left for checkIsServer |
| Search | One search stack — StyledSearchDialog palettes + useAutoSearch/useCursorSearcher |
| Rate limiting | Postgres-backed budgets shared across instances, enforced in the authed middleware |
| Security posture | The app's nuxt-security configuration — CSP, permissions policy, and what is off and why |
| Responsive layout | One breakpoint scale feeding both Vuetify and UnoCSS |
| Date and time display | Every rendered date is a NuxtTime — the reader's locale and timezone, no mismatch |
| Section navigation | One scrollspy for every sidebar that tracks scrolled content, plus the rail that follows it |
Cross-cutting standards we decided against are recorded in rejected — check it before proposing a new one. Ones we chose not to build yet, each with a revisit trigger, are in deferred.