# Bulletproof React Notes For CodeAlmanac

Source: https://github.com/alan2207/bulletproof-react, cloned 2026-06-29.
License: MIT; see `LICENSE.md` in this folder.

## What Applies

- Treat the frontend as a set of features, not a flat script pile, once `serve`
  grows beyond a small static viewer.
- Keep API declarations close to the feature that consumes them, with typed
  request/response contracts on the Python side.
- Keep shared visual primitives separate from wiki-specific components.
- Prefer integration and browser tests for viewer behavior because the value is
  whether the user can browse the wiki, search, follow links, and inspect page
  context.
- Use battle-tested libraries for real UI machinery if the viewer becomes a
  React app. Do not hand-roll complex dropdowns, routing, focus traps, or data
  caching once those concerns exist.

## What Does Not Automatically Apply

- Bulletproof React is not a mandate to create a React or Next.js build step for
  `codealmanac serve` today.
- The current viewer ships as Python package data and is read-only. A static
  HTML/CSS/JS surface is acceptable while the UI is small and has no complex
  client state.
- If a React/Next.js rewrite becomes justified, it must preserve the local-only
  serve contract: no hosted routes, no account/billing semantics, no SDK/MCP,
  and no CLI shell-out.

## Current Serve Guidance

Use UseAlmanac as the source for visual language: alpine colors, dashboard
chrome, account-picker styling, readable wiki typography, and polished shell
spacing.

Do not copy UseAlmanac's hosted wiki information architecture wholesale. The
CodeAlmanac local viewer remains wiki-first: sidebar navigation, page/topic/search
views, backlinks, related pages, and file-reference graph navigation.

Rohan clarified on 2026-06-29 that the current UseAlmanac wiki page and search
experience is not the desired CodeAlmanac shape. Keep the sidebar-led local
viewer direction from CodeAlmanac; borrow design polish around it, not the
UseAlmanac page/search interaction model.
