@zigrivers/scaffold 3.6.0 → 3.7.0

package/content/knowledge/cli/cli-shell-integration.md

@@ -0,0 +1,130 @@
+---
+name: cli-shell-integration
+description: Shell completion generation for bash/zsh/fish, man page generation, dotfile conventions, PATH management, and shell aliases
+topics: [cli, shell-integration, completion, man-pages, dotfiles, path-management, aliases]
+---
+
+Shell integration is the difference between a CLI that feels native and one that feels like a foreign object. Completion, man pages, and dotfile patterns are not optional polish — they are the features that determine whether power users adopt the tool or abandon it for something that respects their shell workflow.
+
+## Summary
+
+Shell integration — completion scripts, man pages, dotfile modifications, and PATH management — determines whether power users adopt the tool or abandon it. Generate completion scripts from the CLI definition for bash, zsh, and fish. Provide an `install-completions` subcommand. When modifying shell startup files, use clearly marked comment blocks and always provide an uninstall command.
+
+## Deep Guidance
+
+### Shell Completion Generation
+
+Provide completion scripts for bash, zsh, and fish. Generate them from the CLI definition rather than hand-writing them — they will stay in sync as commands and flags evolve:
+
+**Node.js (yargs)**
+```bash
+my-cli completion     # Outputs bash/zsh completion script
+my-cli completion >> ~/.bashrc
+```
+
+**Cobra (Go)**
+```bash
+my-cli completion bash   # bash
+my-cli completion zsh    # zsh
+my-cli completion fish   # fish
+my-cli completion powershell
+```
+
+**clap (Rust)** with `clap_complete`:
+```rust
+// Generate at build time and install to /usr/local/share/bash-completion/completions/
+generate(Shell::Bash, &mut cmd, "my-cli", &mut io::stdout());
+```
+
+**click (Python)**: Use `click-completion` or the built-in `shell_complete` parameter.
+
+Completion installation patterns:
+- **bash**: Source from `~/.bashrc` or drop in `/etc/bash_completion.d/` or `~/.bash_completion.d/`
+- **zsh**: Drop in `$fpath` directory, e.g., `/usr/local/share/zsh/site-functions/_my-cli`
+- **fish**: Drop in `~/.config/fish/completions/my-cli.fish`
+
+Provide a `my-cli install-completions` subcommand that writes the correct file for the detected shell. Always print the path written and what the user must do to activate it (e.g., restart shell or run `source ~/.bashrc`).
+
+### Man Page Generation
+
+Man pages are the canonical reference documentation. Generate them from the CLI definition:
+
+**Go (cobra)**: `cobra-man` generates man pages from Cobra commands.
+
+**Node.js**: `marked-man` converts Markdown to man format. `ronn` (Ruby) converts richly formatted Markdown to man.
+
+**Rust (clap)**: `clap_mangen` generates man pages from clap definitions.
+
+Man page installation:
+- System-wide: `/usr/local/share/man/man1/my-cli.1`
+- User-local: `~/.local/share/man/man1/my-cli.1`
+- Run `mandb` (Linux) or ensure `$MANPATH` includes the directory
+
+Homebrew formulae automatically install man pages if placed in `share/man/man1/`. For npm packages, include a `man` field in `package.json`.
+
+### Dotfile Conventions
+
+When the CLI modifies shell startup files (`~/.bashrc`, `~/.zshrc`), follow these rules:
+
+- Never overwrite startup files — append only
+- Use clearly marked comment blocks:
+  ```bash
+  # >>> my-cli init >>>
+  export PATH="$HOME/.my-cli/bin:$PATH"
+  eval "$(my-cli shell-init)"
+  # <<< my-cli init <<<
+  ```
+- The markers enable the tool to detect existing installation and idempotently update the block
+- Always provide `my-cli uninstall` or `my-cli shell-remove` that removes exactly these markers
+- Never add content outside the marked block
+
+On first install, detect which shell config files exist and are writable: check `$SHELL`, then look for `~/.zshrc`, `~/.bashrc`, `~/.bash_profile` in that order.
+
+### PATH Management
+
+When the tool installs binaries or shims to a user-local directory:
+
+```bash
+# Typical user-local bin directory
+~/.local/bin/          # XDG standard (Linux/macOS)
+~/.my-cli/bin/         # Tool-specific (when multiple versions coexist)
+```
+
+Check if the directory is already on `$PATH` before suggesting the user add it. If not on `$PATH`, print the exact line to add and which file to add it to:
+
+```
+Add this to ~/.zshrc:
+  export PATH="$HOME/.local/bin:$PATH"
+```
+
+Do not silently modify PATH for the current process and assume it persists — shell environment changes only persist through startup file modification or explicit user action.
+
+### Shell Aliases
+
+Provide a mechanism to generate useful shell aliases for common command combinations:
+
+```bash
+# my-cli generates aliases for common workflows
+my-cli alias generate >> ~/.zshrc
+```
+
+Aliases should be documented and user-editable. Never require aliases for core functionality — they are convenience, not architecture.
+
+### Shell Detection
+
+Detect the user's shell reliably:
+
+```bash
+# Most reliable: check $SHELL environment variable
+SHELL_NAME=$(basename "$SHELL")
+
+# Fallback: check running process
+ps -p $PPID -o comm= | sed 's/^-//'
+```
+
+Map shell name to config file:
+- `zsh` → `~/.zshrc`
+- `bash` → `~/.bashrc` (Linux) or `~/.bash_profile` (macOS interactive login shells)
+- `fish` → `~/.config/fish/config.fish`
+
+When the shell cannot be detected, print instructions for all three common shells and let the user pick. Never guess and silently write to the wrong file.

package/content/knowledge/cli/cli-testing.md

@@ -0,0 +1,134 @@
+---
+name: cli-testing
+description: CLI integration testing by spawning processes, snapshot testing help text, mock filesystem, environment variable testing, and CI matrix testing
+topics: [cli, testing, integration-tests, snapshot-testing, mock-filesystem, ci-matrix, exit-codes]
+---
+
+CLI testing requires a different mindset than library testing. The contract being tested is behavioral: given this argv and environment, what does the tool write to stdout, what does it write to stderr, and what exit code does it return? Unit tests for business logic are necessary but not sufficient — integration tests that spawn the actual binary catch the class of bugs that only appear at the boundary between argument parsing and execution.
+
+## Summary
+
+CLI testing requires spawning the actual binary and asserting on stdout, stderr, and exit code. Snapshot test help text to catch accidental regressions. Isolate filesystem tests with temporary directories and mock `$HOME`/`XDG_CONFIG_HOME`. Test across OS/runtime matrices in CI including Windows.
+
+## Deep Guidance
+
+### Integration Testing by Spawning the Process
+
+The most valuable CLI test spawns the actual binary and asserts on stdout, stderr, and exit code:
+
+**Node.js (vitest or jest)**
+```typescript
+import { execSync } from 'child_process';
+
+test('build succeeds with valid input', () => {
+  const result = execSync('node bin/my-cli build --input fixture.txt', {
+    encoding: 'utf8',
+    env: { ...process.env, XDG_CONFIG_HOME: tmpDir }
+  });
+  expect(result).toContain('Build complete');
+});
+
+test('exits 2 on unknown flag', () => {
+  expect(() =>
+    execSync('node bin/my-cli --unknown-flag', { encoding: 'utf8', stdio: 'pipe' })
+  ).toThrow('exit code 2');
+});
+```
+
+**Rust**
+```rust
+use assert_cmd::Command;
+
+#[test]
+fn build_succeeds() {
+    Command::cargo_bin("my-cli")
+        .unwrap()
+        .arg("build")
+        .assert()
+        .success()
+        .stdout(predicates::str::contains("Build complete"));
+}
+```
+
+**Bats (shell)**
+```bash
+@test "exits 2 on missing required argument" {
+  run my-cli deploy
+  [ "$status" -eq 2 ]
+  [[ "$output" =~ "required" ]]
+}
+```
+
+Always test exit codes. Always test that error output goes to stderr. Always test the success path and the most common failure paths.
+
+### Snapshot Testing for Help Text
+
+Help text is part of the public API — changes should be intentional. Snapshot tests catch accidental regressions:
+
+```typescript
+test('help text matches snapshot', () => {
+  const { stdout } = execSync('node bin/my-cli --help', { encoding: 'utf8' });
+  expect(stdout).toMatchSnapshot();
+});
+```
+
+Update snapshots intentionally when help text changes. In CI, fail on unexpected snapshot drift. This also catches typos and formatting issues in help output.
+
+### Mock Filesystem
+
+Tests that interact with the filesystem must be isolated. Use temporary directories or a mock filesystem:
+
+**Node.js**
+```typescript
+import { mkdtempSync, rmSync } from 'fs';
+import { tmpdir } from 'os';
+
+let tmpDir: string;
+beforeEach(() => { tmpDir = mkdtempSync(tmpdir() + '/my-cli-test-'); });
+afterEach(() => { rmSync(tmpDir, { recursive: true }); });
+```
+
+For unit tests that don't need real disk I/O, `memfs` provides an in-memory filesystem that satisfies the Node.js `fs` module interface.
+
+**Rust**: Use `tempfile::TempDir`. Tests run in parallel by default — each test gets its own temp directory to avoid interference.
+
+**Key rule**: Never write to `$HOME`, `~/.config`, or any real user directory in tests. Set `HOME` and `XDG_CONFIG_HOME` to the temp directory.
+
+### Environment Variable Testing
+
+Test behavior driven by environment variables:
+
+```typescript
+test('respects NO_COLOR', () => {
+  const result = execSync('node bin/my-cli status', {
+    encoding: 'utf8',
+    env: { ...process.env, NO_COLOR: '1' }
+  });
+  // Assert no ANSI escape sequences in output
+  expect(result).not.toMatch(/\x1b\[/);
+});
+```
+
+Test the full env var precedence chain: flag overrides env var, env var overrides config file. Each level should be independently testable.
+
+### CI Matrix Testing
+
+Test across multiple operating systems and runtime versions:
+
+```yaml
+# GitHub Actions
+strategy:
+  matrix:
+    os: [ubuntu-latest, macos-latest, windows-latest]
+    node: ['18', '20', '22']
+```
+
+Windows-specific concerns: path separators (`\` vs `/`), line endings (`\r\n` vs `\n`), `%APPDATA%` vs `$HOME/.config`, and `PATHEXT` for binary extension handling. Test on Windows even if you do not primarily develop on it.
+
+### Test Pyramid for CLIs
+
+- **Unit tests (fast)**: Business logic in `utils/`, pure functions, config parsing, output formatters
+- **Integration tests (medium)**: Spawn the CLI process, assert stdout/stderr/exit code for key scenarios
+- **End-to-end tests (slow, optional)**: Full workflow against real external services — run in CI on schedule, not on every PR
+
+Keep integration tests fast by using fixtures (pre-created files) rather than generating test input dynamically. A full integration test suite should complete in under 30 seconds.

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

@@ -0,0 +1,224 @@
+---
+name: web-app-api-patterns
+description: REST API design for web clients, GraphQL client patterns, error handling strategies, request deduplication, auth injection, and CORS
+topics: [web-app, api, rest, graphql, cors, error-handling, auth]
+---
+
+The API layer is the seam between frontend and backend. Poor design here manifests as waterfall requests that serialize page loads, inconsistent error shapes that require fragile client-side guessing, auth token handling bugs that cause random 401 errors, and CORS misconfigurations that block legitimate requests. A well-designed API client is boring: it handles auth transparently, errors consistently, and requests efficiently — so product engineers can focus on features rather than network plumbing.
+
+## Summary
+
+### REST API Design for Web Clients
+
+REST conventions for web clients go beyond HTTP verb selection:
+
+**Resource naming:** `/users/{id}/posts` not `/getUserPosts`. Nouns, not verbs. Plural collections.
+
+**Consistent response envelope:** Every response should have a predictable shape. Either always return the resource directly (`200 OK` with the object) or always wrap it (`{ data: {...}, meta: {...} }`) — never mix.
+
+**Status codes must be semantically correct:**
+- `200 OK` — successful read
+- `201 Created` — successful create (include `Location` header with new resource URL)
+- `204 No Content` — successful delete or update with no response body
+- `400 Bad Request` — validation failure (include field-level errors)
+- `401 Unauthorized` — not authenticated
+- `403 Forbidden` — authenticated but not authorized
+- `404 Not Found` — resource does not exist
+- `409 Conflict` — state conflict (duplicate resource, version mismatch)
+- `422 Unprocessable Entity` — business rule violation
+- `429 Too Many Requests` — rate limited (include `Retry-After` header)
+
+**Error response shape (standardize on RFC 7807 Problem Details):**
+```json
+{
+  "type": "https://api.example.com/errors/validation",
+  "title": "Validation Failed",
+  "status": 400,
+  "detail": "2 fields failed validation",
+  "errors": [
+    { "field": "email", "message": "Invalid email format" },
+    { "field": "username", "message": "Username already taken" }
+  ]
+}
+```
+
+### GraphQL Client Patterns
+
+GraphQL shifts the API design from server-defined endpoints to client-defined data requirements:
+
+**Fragments for co-location:** Define data requirements alongside the component that uses the data. This prevents over-fetching and makes it obvious when a component's data requirements change.
+
+**Normalized caching:** Apollo Client and urql maintain a normalized cache where each entity is stored once (by `__typename + id`) and automatically updated across all queries that reference it. Mutations that return the updated entity automatically update all queries that include that entity.
+
+**Fragment colocation pattern:** Each component defines its own fragment; the parent query composes them. This is the Relay-inspired pattern that scales to large teams.
+
+### Error Handling: Toast vs Inline
+
+Two display patterns for API errors, each appropriate in different contexts:
+
+**Toast notifications:** Background mutations, non-blocking operations, and errors where the user's current context is unchanged. "Failed to save changes — try again." The user doesn't lose their work.
+
+**Inline errors:** Form submissions, operations where the error requires user action to resolve. Show the error adjacent to the field or action that caused it. A `400` validation error must show which fields failed.
+
+**Never show raw API errors to users.** Map error codes to human-readable messages on the client. Log the technical detail to your error tracker.
+
+### Request Deduplication
+
+Multiple components mounting simultaneously and each calling the same endpoint produces redundant parallel requests. Deduplication ensures the second identical in-flight request waits for the first's result rather than issuing a new request.
+
+React Query deduplicates automatically — all components with the same `queryKey` share one in-flight request. For custom fetch layers, implement deduplication with a request-in-flight map.
+
+## Deep Guidance
+
+### API Client with Auth Injection and Token Refresh
+
+```typescript
+// api-client.ts — Centralized API client with automatic token refresh
+import ky from 'ky';  // Or axios, or native fetch
+
+let isRefreshing = false;
+let refreshQueue: Array<(token: string) => void> = [];
+
+export const apiClient = ky.create({
+  prefixUrl: process.env.NEXT_PUBLIC_API_URL,
+  hooks: {
+    beforeRequest: [
+      async (request) => {
+        const token = getAccessToken();  // From memory, not localStorage
+        if (token) {
+          request.headers.set('Authorization', `Bearer ${token}`);
+        }
+      },
+    ],
+    afterResponse: [
+      async (request, options, response) => {
+        if (response.status !== 401) return response;
+
+        // Token expired — refresh and retry
+        if (isRefreshing) {
+          // Queue this request until refresh completes
+          return new Promise((resolve) => {
+            refreshQueue.push((newToken) => {
+              request.headers.set('Authorization', `Bearer ${newToken}`);
+              resolve(ky(request));
+            });
+          });
+        }
+
+        isRefreshing = true;
+        try {
+          const newToken = await refreshAccessToken();
+          setAccessToken(newToken);
+
+          // Replay all queued requests with new token
+          refreshQueue.forEach(cb => cb(newToken));
+          refreshQueue = [];
+
+          // Retry the original request
+          request.headers.set('Authorization', `Bearer ${newToken}`);
+          return ky(request);
+        } catch (refreshError) {
+          // Refresh failed — redirect to login
+          clearSession();
+          window.location.href = '/login';
+          throw refreshError;
+        } finally {
+          isRefreshing = false;
+        }
+      },
+    ],
+  },
+});
+```
+
+The token refresh queue pattern prevents multiple simultaneous 401s from triggering multiple refresh requests. Only the first request initiates the refresh; subsequent requests queue and replay once the token is available.
+
+### CORS Configuration
+
+CORS is a browser-enforced security mechanism, not an API security mechanism. Servers must explicitly allow cross-origin requests from trusted origins.
+
+```typescript
+// Express CORS configuration
+import cors from 'cors';
+
+const allowedOrigins = [
+  'https://app.example.com',
+  'https://www.example.com',
+  // Development origins — only in non-production
+  ...(process.env.NODE_ENV !== 'production' ? ['http://localhost:3000'] : []),
+];
+
+app.use(cors({
+  origin: (origin, callback) => {
+    // Allow requests with no origin (server-to-server, curl)
+    if (!origin) return callback(null, true);
+    if (allowedOrigins.includes(origin)) return callback(null, true);
+    callback(new Error(`Origin ${origin} not allowed by CORS policy`));
+  },
+  credentials: true,      // Required when client sends cookies
+  methods: ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'OPTIONS'],
+  allowedHeaders: ['Content-Type', 'Authorization', 'X-Request-ID'],
+  exposedHeaders: ['X-Request-ID', 'X-Rate-Limit-Remaining'],
+  maxAge: 86400,          // Cache preflight for 24 hours (reduces OPTIONS requests)
+}));
+```
+
+**CORS mistakes to avoid:**
+- `origin: '*'` with `credentials: true` is invalid and rejected by browsers
+- Wildcard subdomain matching (`*.example.com`) requires explicit pattern matching, not a string
+- Missing `maxAge` causes an OPTIONS preflight on every non-simple cross-origin request
+
+### GraphQL Fragment Colocation
+
+```typescript
+// UserCard.tsx — Component defines its own data requirements
+const USER_CARD_FRAGMENT = gql`
+  fragment UserCardFields on User {
+    id
+    displayName
+    avatarUrl
+    followerCount
+  }
+`;
+
+function UserCard({ user }: { user: UserCardFields }) {
+  return (/* render using user.displayName, user.avatarUrl, etc. */);
+}
+
+UserCard.fragments = { user: USER_CARD_FRAGMENT };
+
+// ProfilePage.tsx — Composes fragments, doesn't know what UserCard needs
+const PROFILE_PAGE_QUERY = gql`
+  query ProfilePage($userId: ID!) {
+    user(id: $userId) {
+      ...UserCardFields
+      email        # Only ProfilePage needs this
+      createdAt
+    }
+  }
+  ${UserCard.fragments.user}
+`;
+```
+
+When `UserCard` needs a new field, the change is isolated to the fragment and its parent query is automatically updated. No need to modify multiple components or add fields "just in case."
+
+### API Error Handling Pattern
+
+```typescript
+// Typed error handling — map API errors to user-facing messages
+const API_ERROR_MESSAGES: Record<string, string> = {
+  'validation/email-taken': 'That email address is already registered.',
+  'auth/session-expired': 'Your session has expired. Please sign in again.',
+  'rate-limit/exceeded': 'Too many attempts. Please wait a moment and try again.',
+};
+
+function getErrorMessage(error: ApiError): string {
+  if (error.type && API_ERROR_MESSAGES[error.type]) {
+    return API_ERROR_MESSAGES[error.type];
+  }
+  // Safe fallback — never expose raw server errors
+  return 'Something went wrong. Please try again.';
+}
+```
+
+Maintain error message strings in one place. Never construct user-facing messages from raw `error.message` strings returned by the server.

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