@zigrivers/scaffold 3.6.0 → 3.8.0

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

@@ -0,0 +1,116 @@
+---
+name: web-app-architecture
+description: Rendering strategy tradeoffs, CDN edge patterns, hydration strategies, BFF pattern, and micro-frontend considerations for web apps
+topics: [web-app, architecture, ssr, ssg, spa, hydration, bff, micro-frontends, cdn]
+---
+
+Web application architecture is the set of decisions that are expensive to reverse: rendering strategy, client-server boundary, data fetching patterns, and infrastructure topology. These decisions must be made with explicit tradeoff acknowledgment and documented as Architecture Decision Records. The most common architectural mistake is choosing a sophisticated pattern because it is interesting, not because the problem demands it.
+
+## Summary
+
+Web app architecture decisions — rendering strategy (CSR, SSG, SSR, ISR, hybrid), CDN edge patterns, hydration strategy, and the BFF pattern — are expensive to reverse. Match each strategy to the use case rather than trends. Most real-world apps benefit from a hybrid approach mixing strategies per route. Document every significant architectural choice as an Architecture Decision Record.
+
+## Deep Guidance
+
+### Rendering Strategy Tradeoffs
+
+Every rendering strategy has a cost and a benefit profile. Match the strategy to the use case:
+
+**CSR (Client-Side Rendering)**
+- All rendering happens in the browser; server delivers a shell HTML + JS bundle
+- Benefits: Simplest server infrastructure (static file hosting), excellent for authenticated apps with no SEO requirement
+- Costs: Poor initial LCP (blank page until JS loads), crawlers may not index content, no server-side data access
+- Use when: Dashboard, admin panel, authenticated tools, single-page apps behind login
+
+**SSG (Static Site Generation)**
+- Pages built at deploy time; served as static files from CDN
+- Benefits: Near-zero TTFB, cheapest to serve, CDN-native, best Lighthouse scores
+- Costs: Data is stale until next deploy, build time grows with page count (thousands of pages = slow builds)
+- Use when: Marketing sites, documentation, blogs, any content that changes infrequently
+
+**SSR (Server-Side Rendering)**
+- Every request rendered on the server; fresh data every time
+- Benefits: SEO-friendly, always fresh data, works without JavaScript enabled, good LCP on slow connections
+- Costs: Server infrastructure required, cold start latency, harder caching, session management complexity
+- Use when: E-commerce product pages, news sites, any dynamic content that must be SEO-indexed
+
+**ISR (Incremental Static Regeneration)**
+- Static generation with time-based revalidation; stale-while-revalidate per route
+- Benefits: CDN-served like SSG, data freshness configurable per route (10 seconds to 24 hours)
+- Costs: Staleness window must be acceptable to the business, first-visitor after expiry pays SSR cost
+- Use when: Product listings, blog index pages, any content where "minutes stale" is acceptable
+
+**Hybrid**
+- Mix strategies per route: SSG for marketing pages, SSR for product pages, CSR for dashboard
+- Next.js and Remix enable hybrid out of the box — this is the recommended approach for most real-world apps
+
+### CDN Edge Patterns
+
+Deploy static assets and, when possible, entire page renders to CDN edge nodes geographically close to users:
+
+- **Edge caching**: Cache SSR responses at the CDN by setting appropriate `Cache-Control` headers. A page with `Cache-Control: s-maxage=60` is served from CDN for 60 seconds before revalidation.
+- **Edge middleware**: Run logic at the CDN edge (Cloudflare Workers, Vercel Edge Functions) for auth redirects, A/B testing, and geolocation routing without hitting the origin server.
+- **CDN-first asset serving**: All static assets (JS bundles, CSS, images) should always be CDN-served with long-lived cache headers (`Cache-Control: immutable, max-age=31536000`) and content-hashed filenames. Frameworks handle this automatically at build time.
+
+### Hydration Strategies
+
+Hydration is the process of attaching JavaScript interactivity to server-rendered HTML. It is the primary performance cost of SSR frameworks:
+
+- **Full hydration**: The entire component tree hydrates at load. Simplest, but pays full JS parse/execute cost even for static content. Next.js and Remix default behavior.
+- **Progressive hydration**: Hydrate high-priority interactive components first (navigation, above-fold CTAs), defer lower-priority components. Reduces TTI (Time to Interactive) without reducing interactivity.
+- **Selective hydration / Islands architecture**: Only interactive components hydrate; purely static content never runs JS. Implemented by Astro natively; Qwik takes this further with resumability.
+- **React Server Components (RSC)**: Components marked `"server"` never ship to the client. Their rendered output is streamed as a serialized component tree, not HTML. Zero hydration cost for server components.
+
+Match hydration strategy to interactivity requirements. A content site with sparse interactive elements benefits significantly from islands architecture. A complex dashboard with no static content benefits from full hydration.
+
+### BFF (Backend for Frontend) Pattern
+
+The BFF pattern places a purpose-built server layer between the frontend and backend microservices:
+
+- **Problem solved**: Frontend needs data aggregated from 5 microservices to render one page. Directly calling all 5 from the client creates waterfall requests, exposes internal service URLs, and splits auth concerns.
+- **BFF solution**: The frontend calls one BFF endpoint. The BFF aggregates service responses, transforms data to match the UI's needs, handles auth tokens, and returns a single optimized response.
+- **Implementation**: Next.js API routes or Remix loader functions are natural BFF layers. For separate backend services: a Node.js/Express/Fastify service that the frontend treats as its own API.
+
+Do not build a BFF that becomes an unowned monolith. The BFF is owned by the frontend team and changes with the frontend's needs.
+
+### Architecture Decision Record Template
+
+Document every significant architectural choice:
+
+```markdown
+# ADR-001: Rendering Strategy Selection
+
+## Status
+Accepted — 2024-01-15
+
+## Context
+Marketing site (40 pages, infrequent content updates) plus authenticated dashboard.
+
+## Decision
+- Marketing pages: SSG via Next.js; rebuild on content change via webhook
+- Dashboard: CSR with React Query; no SEO requirement
+
+## Consequences
+- Marketing pages: near-zero TTFB, excellent SEO, requires rebuild pipeline
+- Dashboard: full JS bundle on load; auth gate prevents SEO concerns
+- Hybrid in one codebase (Next.js handles both routing strategies)
+```
+
+### Micro-Frontend Considerations
+
+Micro-frontends split one frontend monolith into independently deployable pieces, each owned by a different team. Adopt only when the organizational cost exceeds the technical cost:
+
+- **When justified**: 50+ frontend engineers across 10+ teams, independent release cadences are blocked by coordination overhead, different teams own completely separate product domains
+- **When NOT justified**: Under 20 engineers, single team owns the frontend, coordination overhead is manageable
+- **Implementation options**: Module Federation (webpack), iframe composition (isolation but poor UX), server-side composition (ESI, Nginx include), link-based navigation (least coupling, least shared state)
+
+Most teams that adopt micro-frontends at 10 engineers regret it. Prefer well-structured monorepos with internal package boundaries first.
+
+### Streaming SSR
+
+React 18+ enables streaming HTML responses: send the page shell immediately, stream in component subtrees as their data resolves. This dramatically improves TTFB perception and LCP:
+
+- Critical path renders immediately; slow data sources do not block the initial HTML flush
+- Implement with React's `<Suspense>` boundaries and `renderToPipeableStream`
+- Next.js App Router uses streaming by default; wrap slow data-fetching components in `<Suspense>`
+- Monitor streaming behavior in production — if a slow database query is not wrapped in Suspense, it blocks the entire response stream

package/content/knowledge/web-app/web-app-auth-patterns.md

@@ -0,0 +1,256 @@
+---
+name: web-app-auth-patterns
+description: OAuth 2.0 + PKCE flows, cookie security, passkey/WebAuthn, social login, CSRF protection, and auth state management
+topics: [web-app, auth, oauth, pkce, webauthn, passkeys, csrf, security]
+---
+
+Authentication in web applications is a deep domain where implementation mistakes have severe security consequences. The auth surface spans the browser, the server, and third-party identity providers — and each boundary has its own threat model. OAuth 2.0 with PKCE is now the standard for delegated authorization; WebAuthn/passkeys are rapidly becoming the standard for credential-free authentication; and session cookie security attributes are the baseline that every web app must get right. Skipping any of these correctly has historically led to breaches.
+
+## Summary
+
+### OAuth 2.0 + PKCE Flow
+
+OAuth 2.0 Authorization Code flow with PKCE (Proof Key for Code Exchange) is the correct flow for user-facing web apps. It prevents authorization code interception attacks that plagued the original Authorization Code flow.
+
+**PKCE flow:**
+1. Client generates a cryptographically random `code_verifier` (43–128 chars)
+2. Client derives `code_challenge = BASE64URL(SHA256(code_verifier))`
+3. Client redirects user to authorization server with `code_challenge` and `code_challenge_method=S256`
+4. User authenticates with the identity provider
+5. Authorization server redirects back with `code` in the query string
+6. Client exchanges `code` + `code_verifier` for tokens — the server verifies the challenge hash
+7. Without the original `code_verifier`, a stolen `code` is useless
+
+Never store the `code_verifier` in `localStorage` — use `sessionStorage` or in-memory. The code exchange must happen from your backend (BFF pattern) to avoid exposing `client_secret` in browser code.
+
+### Cookie Security Attributes
+
+Every session cookie and auth cookie must have all four attributes correctly configured:
+
+- **HttpOnly** — prevents JavaScript access, blocking XSS-based token theft
+- **Secure** — restricts transmission to HTTPS, preventing network interception
+- **SameSite=Strict** — cookie not sent on any cross-site request, preventing CSRF
+- **SameSite=Lax** — cookie sent on top-level navigations only; use when cross-site POST is never needed but external links should work
+- **`__Host-` prefix** — enforces Secure + path=/ + no Domain; prevents subdomain hijacking
+
+Use `SameSite=Strict` for session cookies. If your app needs to accept inbound cross-site navigation with the user's session (e.g., linking from a third-party site into an authenticated page), use `Lax`.
+
+### Passkey / WebAuthn Implementation
+
+WebAuthn is the W3C standard for hardware-backed authentication. Passkeys are synced WebAuthn credentials — the user registers once and the credential is available on all their devices via iCloud Keychain or Google Password Manager.
+
+**Why passkeys matter:**
+- No password to phish, leak, or forget
+- Phishing-resistant by design — the credential is bound to the origin URL
+- Biometric authentication without biometric data leaving the device
+- Major platform support as of 2023 (iOS 16+, macOS Ventura+, Android 9+, Windows 11)
+
+**Registration flow:** `navigator.credentials.create()` with a challenge from your server → user authenticates with biometric/PIN → store the public key and credential ID on your server.
+
+**Authentication flow:** `navigator.credentials.get()` with a challenge → WebAuthn assertion → verify signature on server using stored public key.
+
+### Social Login Integration
+
+Social login (Google, GitHub, Apple, etc.) delegates authentication to a trusted identity provider. The implementation pattern:
+
+1. Redirect to provider OAuth endpoint (with PKCE)
+2. Provider redirects back with `code`
+3. Backend exchanges `code` for `id_token` + `access_token`
+4. Verify `id_token` signature against provider's public keys (JWKS endpoint)
+5. Extract user identity (`sub`, `email`, `name`) from verified token
+6. Look up or create user record; issue your app's session
+
+**Account linking:** The same email across different providers should map to the same user account. Store `provider:sub` pairs linked to a single user record to handle this.
+
+## Deep Guidance
+
+### PKCE Implementation
+
+```typescript
+// PKCE utilities — run in browser before redirect
+async function generatePKCE() {
+  // Generate cryptographically random code_verifier
+  const codeVerifier = base64URLEncode(crypto.getRandomValues(new Uint8Array(32)));
+
+  // Derive code_challenge via SHA-256
+  const codeChallenge = base64URLEncode(
+    new Uint8Array(
+      await crypto.subtle.digest('SHA-256', new TextEncoder().encode(codeVerifier))
+    )
+  );
+
+  return { codeVerifier, codeChallenge };
+}
+
+function base64URLEncode(buffer: Uint8Array): string {
+  return btoa(String.fromCharCode(...buffer))
+    .replace(/\+/g, '-')
+    .replace(/\//g, '_')
+    .replace(/=/g, '');
+}
+
+// Initiate login
+async function initiateOAuthLogin(provider: string) {
+  const { codeVerifier, codeChallenge } = await generatePKCE();
+  const state = base64URLEncode(crypto.getRandomValues(new Uint8Array(16)));
+
+  // Store verifier and state — sessionStorage, never localStorage
+  sessionStorage.setItem('pkce_verifier', codeVerifier);
+  sessionStorage.setItem('oauth_state', state);
+
+  const params = new URLSearchParams({
+    client_id: process.env.NEXT_PUBLIC_OAUTH_CLIENT_ID!,
+    redirect_uri: `${window.location.origin}/auth/callback`,
+    response_type: 'code',
+    scope: 'openid email profile',
+    code_challenge: codeChallenge,
+    code_challenge_method: 'S256',
+    state,
+  });
+
+  window.location.href = `${OAUTH_AUTHORIZATION_ENDPOINT}?${params}`;
+}
+
+// Handle callback
+async function handleOAuthCallback(searchParams: URLSearchParams) {
+  const code = searchParams.get('code');
+  const returnedState = searchParams.get('state');
+
+  // Verify state to prevent CSRF
+  const savedState = sessionStorage.getItem('oauth_state');
+  if (!savedState || returnedState !== savedState) {
+    throw new Error('State mismatch — possible CSRF attack');
+  }
+
+  const codeVerifier = sessionStorage.getItem('pkce_verifier');
+  sessionStorage.removeItem('pkce_verifier');
+  sessionStorage.removeItem('oauth_state');
+
+  // Exchange code + verifier for tokens (via your backend)
+  return fetch('/api/auth/callback', {
+    method: 'POST',
+    body: JSON.stringify({ code, codeVerifier }),
+    headers: { 'Content-Type': 'application/json' },
+  });
+}
+```
+
+### WebAuthn Passkey Registration
+
+```typescript
+// Register a new passkey
+async function registerPasskey(userId: string, username: string) {
+  // 1. Get challenge from server
+  const { challenge, rpId } = await api.getRegistrationChallenge();
+
+  // 2. Create credential
+  const credential = await navigator.credentials.create({
+    publicKey: {
+      challenge: base64URLDecode(challenge),
+      rp: { name: 'My App', id: rpId },
+      user: {
+        id: new TextEncoder().encode(userId),
+        name: username,
+        displayName: username,
+      },
+      pubKeyCredParams: [
+        { alg: -7, type: 'public-key' },   // ES256 (most supported)
+        { alg: -257, type: 'public-key' }, // RS256 (Windows Hello fallback)
+      ],
+      authenticatorSelection: {
+        residentKey: 'required',          // Required for passkeys
+        userVerification: 'required',     // Biometric/PIN required
+      },
+      attestation: 'none',                // No attestation for consumer apps
+    },
+  }) as PublicKeyCredential;
+
+  // 3. Send response to server for verification and storage
+  const response = credential.response as AuthenticatorAttestationResponse;
+  return api.completeRegistration({
+    credentialId: base64URLEncode(credential.rawId),
+    clientDataJSON: base64URLEncode(response.clientDataJSON),
+    attestationObject: base64URLEncode(response.attestationObject),
+  });
+}
+```
+
+Use the `@simplewebauthn/server` library on the backend for verification. It handles the complex binary parsing, signature verification, and CBOR decoding correctly.
+
+### CSRF Protection
+
+With `SameSite=Strict` cookies, CSRF is largely mitigated for standard same-origin flows. However, for APIs that accept `application/json` content type (which browsers can't trigger via forms or `<img>` tags), the risk is already limited.
+
+For applications that cannot use `SameSite=Strict` (e.g., cross-site embedded auth flows):
+
+```typescript
+// Double-submit cookie pattern
+// Server sets a CSRF token in a readable cookie (not HttpOnly)
+// Client reads the cookie and sends it as a request header
+// Server validates that header matches cookie value
+
+// Server: set CSRF cookie on login
+res.cookie('csrf-token', generateCSRFToken(), {
+  httpOnly: false,  // Must be readable by JavaScript
+  secure: true,
+  sameSite: 'lax',
+});
+
+// Client: inject header on every mutating request
+apiClient.defaults.headers.common['X-CSRF-Token'] = getCookie('csrf-token');
+
+// Server: validate on every mutation
+app.use((req, res, next) => {
+  if (['POST', 'PUT', 'PATCH', 'DELETE'].includes(req.method)) {
+    if (req.headers['x-csrf-token'] !== req.cookies['csrf-token']) {
+      return res.status(403).json({ error: 'CSRF token mismatch' });
+    }
+  }
+  next();
+});
+```
+
+### Auth State Management in React
+
+```typescript
+// Auth context — single source of truth for authentication state
+interface AuthState {
+  user: User | null;
+  isLoading: boolean;
+  isAuthenticated: boolean;
+}
+
+// Use React Query to manage auth state (benefits from cache, refetch on focus)
+export function useAuth() {
+  const { data: user, isLoading } = useQuery({
+    queryKey: ['auth', 'me'],
+    queryFn: () => api.getCurrentUser(),
+    retry: false,         // Don't retry 401s
+    staleTime: Infinity,  // Only refetch manually or on window focus
+  });
+
+  return {
+    user: user ?? null,
+    isLoading,
+    isAuthenticated: !!user,
+  };
+}
+
+// Route protection
+function ProtectedRoute({ children }: { children: React.ReactNode }) {
+  const { isAuthenticated, isLoading } = useAuth();
+  const router = useRouter();
+
+  useEffect(() => {
+    if (!isLoading && !isAuthenticated) {
+      router.replace(`/login?returnTo=${encodeURIComponent(router.asPath)}`);
+    }
+  }, [isAuthenticated, isLoading]);
+
+  if (isLoading) return <PageSpinner />;
+  if (!isAuthenticated) return null;
+  return <>{children}</>;
+}
+```
+
+Store the return URL before redirecting to login so users land on the page they were trying to reach after authentication.

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

@@ -0,0 +1,121 @@
+---
+name: web-app-conventions
+description: Component naming, file colocation, state management patterns, custom hook conventions, and CSS methodology selection for web apps
+topics: [web-app, conventions, components, state-management, css, hooks]
+---
+
+Conventions are the difference between a codebase where any engineer can find and modify any file in minutes versus one where only the original author can navigate it confidently. Establish these once, enforce them via linting and code review, and never let individual preferences override them during the project lifecycle.
+
+## Summary
+
+Web app conventions establish consistent patterns for component naming (PascalCase, domain-specific), file colocation (feature-based over type-based), state management (local, server, global, URL tiers), custom hook conventions, and CSS methodology selection. Choose one approach per area and enforce it via linting.
+
+## Deep Guidance
+
+### Component Naming
+
+- **PascalCase for components**: `UserProfile`, `NavigationMenu`, `CheckoutSummary`. This is universal across React, Vue (single-file components), and Svelte.
+- **Descriptive, domain-specific names**: `ProductCard` not `Card`, `AuthModal` not `Modal`, `OrderStatusBadge` not `Badge`. Generic names cause naming conflicts as the codebase grows.
+- **Suffix by type where ambiguous**: `UserList` (renders list), `UserListItem` (renders one item), `UserListContainer` (fetches data and passes to list). Be consistent — never mix `Container`/`Provider`/`Wrapper` conventions across the codebase.
+- **Page components**: `LoginPage`, `DashboardPage`, `CheckoutPage` — suffix with `Page` to distinguish from reusable components.
+
+### File Colocation
+
+Colocate files that change together. The industry has converged on feature-based colocation over type-based grouping:
+
+**Preferred (feature-colocated):**
+```
+features/
+  user-profile/
+    UserProfile.tsx
+    UserProfile.test.tsx
+    UserProfile.stories.tsx   # Storybook stories
+    useUserProfile.ts         # Feature-specific hook
+    user-profile.types.ts     # Feature-specific types
+    index.ts                  # Barrel export
+```
+
+**Avoid (type-segregated):**
+```
+components/UserProfile.tsx
+hooks/useUserProfile.ts
+types/userProfile.ts
+tests/UserProfile.test.tsx
+```
+
+The type-segregated structure requires navigating four directories to understand one feature. It also means deleting a feature requires hunting across the entire directory tree.
+
+**Exception**: Truly shared utilities (`lib/`, `utils/`, `hooks/`) that have no single feature owner belong in a flat shared directory, not inside any feature.
+
+### State Management Patterns
+
+Choose the state tier that matches the problem. Do not reach for Redux when `useState` is sufficient:
+
+- **Local state (`useState`, `useReducer`)**: UI-only state that no sibling or parent needs (open/closed, form draft, hover state). Keep it local.
+- **Server state (React Query, SWR, RTK Query)**: Data fetched from an API. Use a server-state library — it handles caching, deduplication, background refresh, and error states for free. Do not put API data in a global Redux store unless you have a compelling reason.
+- **Global client state (Zustand, Jotai, Redux Toolkit)**: Shared UI state that multiple distant components need (authenticated user, theme, cart items, notification queue). Use sparingly. Every piece of global state is a coupling point.
+- **URL state**: Sort order, filters, pagination, tab selection — anything that should survive a page reload or be shareable via link. Use `useSearchParams` or a URL state library. This is underused; most "global state" is actually URL state in disguise.
+
+### Custom Hook Conventions
+
+- Name all custom hooks with the `use` prefix: `useAuth`, `usePagination`, `useDebounce`.
+- Single responsibility: one hook does one thing. `useUserProfile` fetches and returns user data. It does not also handle form state.
+- Return stable references: memoize returned objects and callbacks to prevent unnecessary re-renders in consumers.
+- Keep hooks pure from the component's perspective: no side effects that the hook consumer cannot control. Accept options objects for configuration rather than hardcoding behavior.
+- Co-locate the hook with the feature that owns it. Move to `lib/hooks/` only when reused across three or more features.
+
+### CSS Methodology Selection
+
+Choose one methodology and enforce it. Mixing methodologies creates chaos:
+
+- **Tailwind CSS**: Best for teams that want to move fast and avoid naming bikeshedding. Excellent with design tokens. Downsides: verbose JSX, requires purging to avoid large CSS bundles, learning curve for custom designs.
+- **CSS Modules**: Best for teams that prefer semantic class names and encapsulation without a utility framework. No runtime, good TypeScript support via `typed-css-modules`.
+- **CSS-in-JS (styled-components, Emotion)**: Best for highly dynamic styles or design systems with programmatic theming. Downsides: runtime cost, hydration complexity with SSR.
+- **Vanilla CSS with custom properties**: Best for simple apps or teams who want zero abstraction. Use a consistent BEM-like naming convention.
+
+### Enforcing Conventions with Tooling
+
+Conventions without enforcement degrade immediately. Configure linting to automate the common cases:
+
+```json
+// ESLint rules for React component conventions
+{
+  "rules": {
+    "react/jsx-pascal-case": "error",          // Enforce PascalCase for JSX components
+    "import/no-default-export": "warn",         // Prefer named exports (easier to find with search)
+    "@typescript-eslint/naming-convention": [
+      "error",
+      { "selector": "function", "format": ["camelCase", "PascalCase"] },
+      { "selector": "variable", "format": ["camelCase", "UPPER_CASE", "PascalCase"] }
+    ]
+  }
+}
+```
+
+Add a Storybook or component documentation requirement: every shared component must have a story before it can be merged. This enforces composability — if you cannot write a story for it in isolation, the component is too coupled.
+
+### State Management Decision Flowchart
+
+When choosing state location, answer in order:
+
+1. Is this state only used by one component? → `useState`
+2. Is this state fetched from a server? → React Query / SWR
+3. Can this state live in the URL? → `useSearchParams` / URL state
+4. Is this state shared across multiple distant routes? → Zustand / Jotai / Redux Toolkit
+5. Is this state needed server-side during SSR? → Context with SSR-safe initialization
+
+Resist the urge to centralize all state globally. Distributed state is easier to delete when features are removed and easier to reason about during debugging.
+
+### Hook Testing Conventions
+
+Test hooks in isolation using `renderHook` from React Testing Library. This keeps hook logic testable without mounting a component:
+
+```typescript
+// Good: test hook behavior directly
+const { result } = renderHook(() => useDebounce("search", 300));
+expect(result.current).toBe("");
+act(() => { jest.advanceTimersByTime(300); });
+expect(result.current).toBe("search");
+```
+
+Never test a hook only via its parent component — that couples the hook test to the component's rendering and makes failures harder to diagnose.