Encore OS — Documentation

Status: Active
Owner: Platform Architecture
Related: ADR-008 (Vite SPA), TURBOREPO_USAGE.md, MICROFRONTENDS_RUNBOOK.md This document operationalizes the Performance Architecture plan: measure before changing runtime topology (microfrontends count, framework migrations), and keep Vite/Rolldown + Turborepo as the primary levers.

1. What to baseline

Signal	Tool / artifact	When
Repo + pipeline timing	`npm run perf:baseline` or `perf:baseline:quick`	Monthly or before large refactors
JS chunk sizes (post-build)	`npm run perf:build-metrics` (also embedded in `perf:baseline` when `dist/` exists)	After dependency upgrades or vendor chunk changes
Bundle graph	`npm run build:analyze` → `dist/stats.html`	When investigating regressions
Runtime Web Vitals	Vercel Speed Insights (production); Lighthouse locally	Before/after microfrontend activation
PWA precache	DevTools → Application → Service Workers + cache storage; `vite.config.ts` Workbox `globPatterns`	After PWA or routing changes

2. Commands

npm run build
npm run perf:build-metrics          # human-readable table + reports/perf/build-chunks-YYYY-MM-DD.json
npm run perf:build-metrics:json     # stdout JSON only

npm run perf:baseline               # structural + timed dev metrics → reports/perf/baseline-*.md
npm run perf:baseline:structural    # fast structural only (includes dist chunk rows if dist/ exists)

npm run perf:budgets:check          # fail if precache-critical JS chunks exceed budget (needs dist/)
VITE_BUDGETS_WARN_ONLY=1 npm run perf:budgets:check   # log violations, exit 0 (CI informational)

Budget defaults match Workbox maximumFileSizeToCacheInBytes (2 MiB) for the four precache-critical entry patterns (index-*, vendor-react-*, vendor-radix-*, vendor-supabase-*). Override with VITE_BUDGET_CRITICAL_CHUNK_BYTES.

3. Route timing (manual)

There is no single automated “route timing” suite in-repo today. For critical flows (login, dashboard, heavy tables, PDF export):

Chrome DevTools → Performance → record navigation.
Or Playwright trace + performance marks where needed.

Record dates and rough LCP/TTI in PR descriptions when claiming perf wins.

4. Microfrontends

Path-based splits are deployment concerns; they do not replace bundle discipline. Before activating Phase 3:

Follow MICROFRONTENDS_ACTIVATION_CHECKLIST.md.
Re-baseline Web Vitals on preview (runbook soak).

5. Turborepo

Turborepo improves CI and local task latency, not browser JS size. See TURBOREPO_USAGE.md for remote cache setup and cache-hit diagnostics.

Start Here

Module Engineering Snapshots

Canonical AI Governance

Architecture

Integrations

Development

Decision Guides

Database

Module Reference

Testing

Migration

Operations

Governance & Security

Platform Internals

Performance baseline and budgets

1. What to baseline

2. Commands

3. Route timing (manual)

4. Microfrontends

5. Turborepo

See also

​1. What to baseline

​2. Commands

​3. Route timing (manual)

​4. Microfrontends

​5. Turborepo

​See also

1. What to baseline

2. Commands

3. Route timing (manual)

4. Microfrontends

5. Turborepo

See also