@zigrivers/scaffold 3.6.0 → 3.8.0

package/content/knowledge/web-app/web-app-dev-environment.md

@@ -0,0 +1,173 @@
+---
+name: web-app-dev-environment
+description: Dev server configuration, HMR setup, API proxy, environment variables, Docker for local services, and browser devtools for web app development
+topics: [web-app, dev-environment, vite, webpack, hmr, docker, debugging]
+---
+
+A fast, reliable local development environment is a force multiplier for the entire team. The goal is sub-second feedback loops for code changes and zero friction getting from a fresh checkout to a running app. Every minute spent fighting the dev environment is a minute not spent building the product.
+
+## Summary
+
+A fast web app dev environment targets sub-second feedback loops with HMR and zero-friction onboarding. Use Vite for new projects (or the framework's built-in server for Next.js). Configure an API proxy to avoid CORS issues. Validate environment variables at startup with a schema. Run local dependencies in Docker Compose.
+
+## Deep Guidance
+
+### Dev Server Choice: Vite vs webpack
+
+For new projects in 2024 and beyond, use **Vite** unless you have a specific reason not to:
+
+- **Vite**: Native ESM dev server, near-instant startup regardless of project size, esbuild-powered transforms (10–100x faster than Babel), first-class support for React, Vue, Svelte, and TypeScript out of the box.
+- **webpack (via Create React App, Next.js with webpack, or custom)**: Slower cold starts and HMR, but battle-tested and required by some frameworks. Next.js 13+ defaults to Turbopack (Rust-based, approaching Vite speed).
+
+If you are on Next.js, you get the dev server bundled with the framework. Do not fight the framework's built-in tooling — configure it via `next.config.ts`, not by ejecting or customizing webpack directly unless absolutely necessary.
+
+### HMR Configuration
+
+Hot Module Replacement keeps the page live-updating without full reloads. Ensure it is working correctly:
+
+- With Vite: HMR works out of the box. If it stops working after upgrading, check `server.hmr` in `vite.config.ts`. Common issue: HMR fails silently when a module has a circular dependency.
+- With React: Install `@vitejs/plugin-react` (uses Babel with Fast Refresh) or `@vitejs/plugin-react-swc` (uses SWC, 3–5x faster). Fast Refresh preserves component state on save — test that it works for your components.
+- Watch for HMR performance degradation in large projects: if HMR is slow, profile with `vite --debug hmr`. The usual cause is a large shared module being invalidated on every change.
+
+### API Proxy Configuration
+
+During development, your app's origin is `localhost:3000` but your API backend is `localhost:8000`. Avoid CORS issues and hardcoded localhost URLs by configuring a dev proxy:
+
+```typescript
+// vite.config.ts
+export default defineConfig({
+  server: {
+    proxy: {
+      "/api": {
+        target: "http://localhost:8000",
+        changeOrigin: true,
+        rewrite: (path) => path.replace(/^\/api/, ""),
+      },
+    },
+  },
+});
+```
+
+This means your frontend code always calls `/api/users` and the proxy handles routing to the backend. The same relative URL works in production when the API is behind the same domain. Never hardcode `http://localhost:8000` in application code.
+
+### Environment Variables
+
+Use `.env` files for environment-specific configuration. Establish clear conventions:
+
+- `.env.example` — committed, documents all variables with dummy values
+- `.env.local` — gitignored, developer-specific overrides (actual API keys, local service URLs)
+- `.env.development` — gitignored, shared dev defaults (can be committed if values are non-sensitive)
+- `.env.production` — injected by CI/CD, never committed
+
+Validate all required variables at startup. An app that silently uses `undefined` for a missing API URL is worse than one that crashes immediately with a clear error:
+
+```typescript
+// lib/env.ts — validate at module load time
+import { z } from "zod";
+
+const envSchema = z.object({
+  VITE_API_URL: z.string().url(),
+  VITE_FEATURE_FLAGS: z.string().default(""),
+});
+
+export const env = envSchema.parse(import.meta.env);
+```
+
+### Docker for Local Services
+
+Run local dependencies (databases, caches, queues, email servers) in Docker to keep developer machines clean and ensure consistency:
+
+```yaml
+# docker-compose.yml
+services:
+  postgres:
+    image: postgres:16-alpine
+    ports: ["5432:5432"]
+    environment:
+      POSTGRES_DB: myapp_dev
+      POSTGRES_USER: dev
+      POSTGRES_PASSWORD: dev
+    volumes:
+      - postgres_data:/var/lib/postgresql/data
+
+  redis:
+    image: redis:7-alpine
+    ports: ["6379:6379"]
+
+  mailpit:
+    image: axllent/mailpit
+    ports:
+      - "1025:1025"   # SMTP
+      - "8025:8025"   # Web UI
+
+volumes:
+  postgres_data:
+```
+
+Document the setup in the README: `docker compose up -d` starts all services. Never require developers to install PostgreSQL, Redis, or other services directly on their machines.
+
+### Getting to Zero-Friction Setup
+
+Document the new developer setup flow and time it. Target under 10 minutes from fresh checkout to running app. Anything over 15 minutes will be skipped and developers will use workarounds.
+
+Minimum `package.json` scripts:
+
+```json
+{
+  "scripts": {
+    "dev": "vite",
+    "dev:full": "docker compose up -d && vite",
+    "build": "tsc && vite build",
+    "preview": "vite preview",
+    "test": "vitest",
+    "test:ui": "vitest --ui",
+    "lint": "eslint src --ext .ts,.tsx",
+    "typecheck": "tsc --noEmit"
+  }
+}
+```
+
+Include a `Makefile` or `justfile` for multi-step setup commands that developers run once (`make setup` installs deps, configures git hooks, copies `.env.example`).
+
+### Browser Devtools Configuration
+
+Install and configure browser extensions that accelerate debugging:
+
+- **React Developer Tools**: Component tree inspection, props/state browser, profiler for render performance.
+- **Redux DevTools** (if using Redux): Action/state history, time-travel debugging.
+- **Vite plugin for browser devtools**: Install `vite-plugin-inspect` to visualize the Vite plugin pipeline and module graph.
+
+Configure source maps in development (`devtool: "eval-source-map"` in webpack or `sourcemap: true` in Vite) so stack traces point to TypeScript source, not compiled JavaScript. Without this, debugging is nearly impossible.
+
+### TypeScript Strict Mode
+
+Enable strict mode from day one in `tsconfig.json`:
+
+```json
+{
+  "compilerOptions": {
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "exactOptionalPropertyTypes": true
+  }
+}
+```
+
+Disabling strict mode to make TypeScript "less annoying" creates a false sense of safety. The errors strict mode surfaces are real bugs. Fix them instead of disabling the check.
+
+### VS Code Workspace Settings
+
+Commit a `.vscode/settings.json` with recommended settings so all developers use consistent formatting:
+
+```json
+{
+  "editor.formatOnSave": true,
+  "editor.defaultFormatter": "esbenp.prettier-vscode",
+  "editor.codeActionsOnSave": {
+    "source.fixAll.eslint": true
+  },
+  "typescript.preferences.importModuleSpecifier": "non-relative"
+}
+```
+
+Commit `.vscode/extensions.json` with recommended extensions. Developers are prompted to install them on workspace open.

package/content/knowledge/web-app/web-app-observability.md

@@ -0,0 +1,221 @@
+---
+name: web-app-observability
+description: Real User Monitoring, Core Web Vitals tracking, error tracking with Sentry, CDN analytics, custom performance marks, and performance regression alerting
+topics: [web-app, observability, rum, core-web-vitals, sentry, performance, monitoring]
+---
+
+You cannot improve what you cannot measure. Frontend observability is often treated as an afterthought — added after users start complaining — but by then you have no baseline to regress against and no historical data to understand when performance degraded or errors started. Real User Monitoring (RUM) captures the experience of your actual users on their actual devices and networks, which lab-based tests like Lighthouse cannot replicate. Core Web Vitals are Google's standardized metrics for page experience and directly influence search ranking.
+
+## Summary
+
+### Real User Monitoring (RUM)
+
+RUM collects performance and behavioral data from real user sessions in production. Unlike synthetic monitoring (scheduled tests from a data center), RUM reflects the diversity of real-world conditions: slow Android devices, congested mobile networks, aggressive ad blockers, and geographically distant users.
+
+**Key RUM metrics:**
+
+- **Core Web Vitals** — Google's page experience signals (see below)
+- **Time to First Byte (TTFB)** — server response latency
+- **First Contentful Paint (FCP)** — when the first content is painted
+- **Time to Interactive (TTI)** — when the page is reliably interactive
+- **Custom marks** — application-specific milestones (e.g., "dashboard data loaded")
+- **Error rate** — JavaScript exceptions per session
+- **Rage clicks** — repeated clicks on non-interactive elements (UX frustration signal)
+- **Dead clicks** — clicks on elements that produce no response
+
+**RUM tools:** Vercel Analytics, Datadog RUM, New Relic Browser, Sentry Performance, web-vitals library (self-hosted reporting).
+
+### Core Web Vitals
+
+Google's three Core Web Vitals measure loading, interactivity, and visual stability:
+
+| Metric | Measures | Good | Needs Improvement | Poor |
+|---|---|---|---|---|
+| **LCP** (Largest Contentful Paint) | Load performance | ≤ 2.5s | 2.5–4s | > 4s |
+| **INP** (Interaction to Next Paint) | Responsiveness | ≤ 200ms | 200–500ms | > 500ms |
+| **CLS** (Cumulative Layout Shift) | Visual stability | ≤ 0.1 | 0.1–0.25 | > 0.25 |
+
+**Common LCP causes and fixes:**
+- Unoptimized hero images → use `srcset`, WebP/AVIF, CDN, `loading="eager"`, `fetchpriority="high"`
+- Render-blocking CSS/fonts → inline critical CSS, use `font-display: swap`
+- Slow TTFB → edge caching, CDN, server-side optimization
+
+**Common CLS causes and fixes:**
+- Images without explicit `width`/`height` attributes → always set dimensions
+- Late-loading ads or embeds → reserve space with aspect-ratio boxes
+- Custom fonts causing text reflow → use `font-display: optional` or `size-adjust`
+- Dynamic content injected above viewport content → append below, not prepend above
+
+**INP (replaced FID in 2024):** Measures the responsiveness of all user interactions, not just the first. Long JavaScript tasks (>50ms) block the main thread and inflate INP. Use `scheduler.postTask()`, web workers, and code splitting to break up long tasks.
+
+### Error Tracking with Sentry
+
+Sentry captures JavaScript exceptions, stack traces, user context, and breadcrumbs (the sequence of events leading to the error). Configure it to filter noise and surface actionable errors.
+
+**Critical Sentry configuration:**
+- Source maps for readable stack traces (never ship source maps publicly — upload to Sentry only)
+- User context (attach user ID, plan tier — never PII like email without consent)
+- Release tracking to correlate error spikes with deployments
+- Sampling rate: 100% for errors, 10–20% for performance transactions in high-traffic apps
+
+### Performance Regression Alerting
+
+The goal is to catch regressions before they reach users or before they compound. Alert on:
+- LCP p75 (75th percentile) increases by more than 300ms from the rolling 7-day average
+- Error rate increases by more than 0.5% from the rolling 24-hour baseline
+- Any new error type appearing in production for the first time
+
+## Deep Guidance
+
+### Web Vitals Collection
+
+```typescript
+// web-vitals library — collect and report Core Web Vitals
+import { onLCP, onINP, onCLS, onFCP, onTTFB } from 'web-vitals';
+
+function sendToAnalytics(metric: any) {
+  // Batch metrics to avoid sending too many beacons
+  const body = JSON.stringify({
+    name: metric.name,
+    value: metric.value,
+    rating: metric.rating,    // 'good', 'needs-improvement', 'poor'
+    id: metric.id,
+    navigationType: metric.navigationType,
+    url: window.location.pathname,
+    // Attach context for segmentation
+    connectionType: (navigator as any).connection?.effectiveType,
+    deviceMemory: (navigator as any).deviceMemory,
+  });
+
+  // sendBeacon is non-blocking and survives page unload
+  if (navigator.sendBeacon) {
+    navigator.sendBeacon('/api/vitals', body);
+  } else {
+    fetch('/api/vitals', { method: 'POST', body, keepalive: true });
+  }
+}
+
+// Register all Core Web Vitals + FCP + TTFB
+onLCP(sendToAnalytics);
+onINP(sendToAnalytics);
+onCLS(sendToAnalytics);
+onFCP(sendToAnalytics);
+onTTFB(sendToAnalytics);
+```
+
+Always use `navigator.sendBeacon` for analytics reporting — it queues the request to be sent after the page unloads without blocking navigation.
+
+### Custom Performance Marks
+
+Use the User Timing API to measure application-specific milestones that browser APIs cannot capture:
+
+```typescript
+// Mark application-level performance milestones
+class PerformanceTracker {
+  private marks: Map<string, number> = new Map();
+
+  mark(name: string): void {
+    performance.mark(name);
+    this.marks.set(name, performance.now());
+  }
+
+  measure(name: string, startMark: string, endMark?: string): number {
+    const end = endMark || name + '-end';
+    if (!endMark) this.mark(end);
+
+    const measure = performance.measure(name, startMark, end);
+    const duration = measure.duration;
+
+    // Report to RUM
+    this.report({ name, duration });
+    return duration;
+  }
+
+  private report(metric: { name: string; duration: number }): void {
+    navigator.sendBeacon?.('/api/perf', JSON.stringify(metric));
+  }
+}
+
+const perf = new PerformanceTracker();
+
+// Usage in application code
+async function loadDashboard() {
+  perf.mark('dashboard-fetch-start');
+  const data = await fetchDashboardData();
+  perf.mark('dashboard-fetch-end');
+
+  perf.measure('dashboard-fetch', 'dashboard-fetch-start', 'dashboard-fetch-end');
+
+  perf.mark('dashboard-render-start');
+  renderDashboard(data);
+  perf.mark('dashboard-render-end');
+
+  perf.measure('dashboard-render', 'dashboard-render-start', 'dashboard-render-end');
+}
+```
+
+These custom marks appear in Chrome DevTools Performance panel and can be reported to your RUM backend for tracking.
+
+### Sentry Setup for Next.js
+
+```typescript
+// sentry.client.config.ts
+import * as Sentry from '@sentry/nextjs';
+
+Sentry.init({
+  dsn: process.env.NEXT_PUBLIC_SENTRY_DSN,
+  environment: process.env.NEXT_PUBLIC_ENV,
+
+  // Performance monitoring sample rate — adjust based on traffic volume
+  tracesSampleRate: process.env.NODE_ENV === 'production' ? 0.1 : 1.0,
+
+  // Replay for error sessions only (privacy-conscious default)
+  replaysOnErrorSampleRate: 1.0,
+  replaysSessionSampleRate: 0.0,
+
+  // Filter noise — don't track network errors from ad blockers
+  ignoreErrors: [
+    'ResizeObserver loop limit exceeded',
+    'Non-Error promise rejection captured',
+    /Loading chunk \d+ failed/,
+  ],
+
+  beforeSend(event, hint) {
+    // Strip PII from error context
+    if (event.user) {
+      delete event.user.email;
+      delete event.user.username;
+    }
+    return event;
+  },
+
+  integrations: [
+    Sentry.replayIntegration({
+      maskAllText: true,     // Privacy: mask all text in replays
+      blockAllMedia: true,   // Privacy: block media in replays
+    }),
+  ],
+});
+```
+
+### CDN Analytics and Cache Hit Rate
+
+Monitor CDN cache performance as a leading indicator for LCP and TTFB:
+
+- **Cache hit rate** — percentage of requests served from CDN cache vs origin. Target >90% for static assets, >70% for edge-cached HTML.
+- **Origin shield hit rate** — for CDN tiers that include an origin shield, a low rate indicates cold cache or poor cache-control headers.
+- **Edge latency by region** — identify geographic regions where users have poor performance; expand CDN PoP coverage or investigate origin latency.
+
+Key cache-control headers:
+```
+# Immutable static assets (hashed filenames)
+Cache-Control: public, max-age=31536000, immutable
+
+# HTML pages — revalidate frequently but serve stale while revalidating
+Cache-Control: public, max-age=0, s-maxage=86400, stale-while-revalidate=3600
+
+# API responses — no public cache, short browser cache
+Cache-Control: private, max-age=30
+```
+
+Set `Surrogate-Key` (Fastly) or `Cache-Tag` (Cloudflare) headers on HTML responses to enable targeted cache purging when content changes.

package/content/knowledge/web-app/web-app-project-structure.md

@@ -0,0 +1,160 @@
+---
+name: web-app-project-structure
+description: Directory layout conventions, route organization, shared vs feature modules, barrel exports, and config file placement for web apps
+topics: [web-app, project-structure, architecture, routing, modules]
+---
+
+A well-structured web app project is navigable by any developer without a tour. The directory layout should communicate the architecture at a glance: where pages live, where shared code lives, where API logic lives, and where configuration lives. A poor structure forces every developer to ask "where does this go?" on every new file they create.
+
+## Summary
+
+Web app project structure separates `app/` (routes and layouts), `features/` (domain-owned modules), `components/` (shared UI), `hooks/` (shared hooks), and `lib/` (framework-agnostic utilities). Routes mirror URL structure with thin page files. Feature modules own their components, hooks, and types; shared modules have zero imports from feature modules.
+
+## Deep Guidance
+
+### Standard Directory Layout
+
+For a Next.js or similar SSR framework, the canonical structure is:
+
+```
+src/
+  app/              # App Router pages and layouts (Next.js 13+)
+  pages/            # Pages Router (Next.js legacy; or Remix/Vite routes)
+  components/       # Shared, reusable UI components
+  features/         # Feature modules (colocated components + hooks + logic)
+  hooks/            # Shared custom hooks used across features
+  lib/              # Framework-agnostic utilities and service clients
+  api/              # API route handlers (serverless functions)
+  types/            # Shared TypeScript types and interfaces
+  styles/           # Global CSS, design tokens, theme config
+public/             # Static assets served at root (images, fonts, robots.txt)
+```
+
+For a Vite/React SPA, drop `app/` and `api/` and substitute:
+
+```
+src/
+  routes/           # Route components and nested layouts
+  pages/            # Page-level components (one per route)
+```
+
+### Route Organization
+
+Routes should mirror the URL structure. Avoid flat route files that make the hierarchy ambiguous:
+
+- `/dashboard` → `app/dashboard/page.tsx`
+- `/dashboard/settings` → `app/dashboard/settings/page.tsx`
+- `/users/[id]` → `app/users/[id]/page.tsx`
+
+Keep route files thin — they orchestrate data loading and pass props to feature components. Business logic belongs in `features/`, not in the page file.
+
+**Layouts**: Use layout files (`layout.tsx`) to share navigation, auth checks, and providers across route groups. Do not repeat these in every page file.
+
+### Shared vs Feature Modules
+
+The critical distinction is "who owns this code":
+
+- **Feature module** (`features/checkout/`): Owned by one product domain. Contains everything the checkout feature needs — components, hooks, API calls, types. Other features do not import from it directly; they use shared interfaces.
+- **Shared module** (`components/`, `hooks/`, `lib/`): Owned by no single feature. Used by two or more features. Has no knowledge of any specific feature's business logic.
+
+The rule: shared modules must have zero imports from feature modules. Feature modules may import from shared modules. This prevents circular dependencies and keeps shared code reusable.
+
+### Barrel Exports
+
+Use `index.ts` barrel files at the feature and component directory level to create clean import paths:
+
+```typescript
+// features/user-profile/index.ts
+export { UserProfile } from "./UserProfile";
+export { useUserProfile } from "./useUserProfile";
+export type { UserProfileData } from "./user-profile.types";
+```
+
+Consumers import from `features/user-profile`, not from deep internal paths:
+```typescript
+// Good
+import { UserProfile } from "@/features/user-profile";
+
+// Bad — leaks internal structure
+import { UserProfile } from "@/features/user-profile/components/UserProfile";
+```
+
+Configure TypeScript path aliases (`@/`) to avoid relative path ladders (`../../../../../../`).
+
+### Config Files
+
+Config files belong at the repo root, not inside `src/`. Standard placement:
+
+- `next.config.ts` / `vite.config.ts` — build and bundler config
+- `tsconfig.json` — TypeScript compiler config
+- `eslint.config.js` — linting rules
+- `.env.example` — documented environment variables (committed); `.env.local` — actual values (gitignored)
+- `tailwind.config.ts` — if using Tailwind
+- `vitest.config.ts` / `jest.config.ts` — test runner config
+
+### Feature Module Template
+
+Every feature module follows the same internal structure. Establish this template in `CONTRIBUTING.md`:
+
+```
+features/
+  <feature-name>/
+    index.ts                  # Barrel export — public API of the feature
+    <FeatureName>.tsx          # Top-level feature component
+    <FeatureName>.test.tsx     # Component tests
+    <FeatureName>.stories.tsx  # Storybook stories (if applicable)
+    use<FeatureName>.ts        # Primary data hook
+    use<FeatureName>.test.ts   # Hook tests
+    <feature-name>.types.ts    # TypeScript types for this feature
+    <feature-name>.api.ts      # API calls made by this feature (if applicable)
+    components/                # Sub-components used only within this feature
+      <SubComponent>.tsx
+```
+
+Enforce "no cross-feature imports" with ESLint:
+
+```javascript
+// eslint-plugin-import rule to prevent cross-feature imports
+"import/no-restricted-paths": [
+  "error",
+  {
+    "zones": [{
+      "target": "./src/features",
+      "from": "./src/features",
+      "except": ["./src/features/index.ts"] // Only barrel is importable
+    }]
+  }
+]
+```
+
+### Environment Variable Management
+
+Never hardcode environment-specific values. Use `.env` files and document every variable:
+
+```bash
+# .env.example — committed to the repo
+# Never commit .env, .env.local, or .env.production
+
+# API base URL
+NEXT_PUBLIC_API_URL=https://api.example.com
+
+# Auth provider
+NEXT_PUBLIC_AUTH_DOMAIN=your-domain.auth0.com
+AUTH_SECRET=          # Server-only; never expose to client (no NEXT_PUBLIC_ prefix)
+
+# Feature flags
+NEXT_PUBLIC_FEATURE_NEW_CHECKOUT=false
+```
+
+Validate environment variables at startup using a schema (Zod is ideal). Fail fast with a clear error message if required variables are missing or malformed. Never let the app silently run with bad configuration.
+
+### Avoiding the "Utils Dumping Ground"
+
+A `utils/` directory with no sub-organization becomes a junk drawer within weeks. Apply the same discipline to utilities:
+
+- Group by domain: `lib/date.ts`, `lib/currency.ts`, `lib/validation.ts`
+- If a utility grows beyond ~100 lines, give it its own directory with an `index.ts`
+- Delete utilities that are no longer used — dead code in `lib/` is worse than no code
+- Never put business logic in `lib/`. Business logic belongs in features or hooks.
+
+The test for whether something belongs in `lib/`: "Could I copy this to a different web app project without modification?" If yes, it belongs in `lib/`. If it has knowledge of this app's domain, it belongs in `features/` or `hooks/`.