Files
clean-architecture-frontend…/docs/architecture/starter-experience.md
T
DongHyeonkaandClaude Opus 5.5 e0b20f50db docs(auth): document what readSubject must return and the fail-closed default (R3-3)
readSubject/getSubject must be an opaque, non-empty id that is stable per
user and never a token. Without it, every authenticated notification
clears server state.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-24 15:15:26 +09:00

4.1 KiB

Starter experience contract

The repository provides a runnable, domain-neutral application rather than only infrastructure contracts. The starter experience is intentionally replaceable at the page level while the shell, providers, boundaries, primitives, and state surfaces remain reusable.

Runtime composition

validated config + coherent release manifest
  -> concrete adapters
  -> QueryClientProvider
  -> ApplicationProvider
  -> RouterProvider
  -> ThemeProvider
  -> SessionProvider
  -> AppShell
  -> lazy route boundary

Boot stops before product mount when configuration or release coherence fails. Each lazy page renders inside Suspense and a telemetry-aware route boundary. Route changes move focus to the new page heading; the skip link and landmarks remain stable in the shell.

Registered routes

ID Path Access Surface
APP_HOME / public readiness dashboard
EXAMPLES_UI /examples/ui public interactive primitives and tokens
EXAMPLES_STATES /examples/states public async and access state matrix
EXAMPLES_AUTH /examples/auth public session integration controls
REFERENCE_RESOURCE_LIST /examples/reference-resources session-required removable vertical slice
NOT_FOUND * public safe navigation recovery

Navigation labels and order come from ROUTE_REGISTRY; the sidebar does not maintain a second route list. The client access decision never claims to be authorization.

Authentication seam

The session port exposes state subscription, sign-in start, sign-out, credential attachment, recovery, and unauthenticated notification. Credentials remain opaque to the application and presentation layers.

  • demo: local/development-only state transition with no credentials
  • external: delegates to globalThis.__CA_FRONTEND_AUTH_OWNER__
  • missing/invalid external owner: fails closed as integration-failed

An external owner implements readState, subscribe, beginSignIn, signOut, attachCredential, recoverSession, and notifyUnauthenticated. It owns token acquisition and storage.

The owner may also implement readSubject(). The server-state cache is cleared only when the session state or the subject changes, so a token refresh for the same user keeps cached data. readSubject() must return:

  • an opaque, non-empty string that stays the same for one user across token refreshes and differs between users, such as a hashed account id
  • null when nobody is signed in
  • never an access token, refresh token, or any other credential

Without readSubject() (or when it returns null or "" while authenticated), the runtime cannot tell a refresh from an account switch, so every notification from an authenticated owner clears server state. This is the safe default. The demo adapter reports one fixed demo user as its subject.

Extending the starter

The steps below describe the current extension path. New platform work should follow routing, page templates, and reusable patterns and the TypeScript, state, and data-flow target rather than adding another independent route or data-loading convention.

  1. Add a serializable contribution under the feature ownership boundary and install it through src/features/installed-feature-contracts.ts.
  2. Add the lazy component and route codecs through src/features/installed-feature-runtimes.tsx.
  3. Compose feature application inputs and outbound gateways only through src/features/installed-feature-adapters.ts.
  4. Use the semantic tokens, UI primitives, and state surfaces before adding a project-specific variant.
  5. Add component behavior, all-engine E2E, automated axe, and signed manual route evidence.
  6. Run test:sample-removal to prove the generic starter typechecks, passes architecture/registry/tests/coverage/source-evidence/home smoke, and builds without the complete reference feature.

Theme preference is the public COLOR_SCHEME storage contract. Authentication tokens and other secrets remain forbidden storage keys.