clean-architecture-frontend-template/docs/architecture/starter-experience.md

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	integration-defined	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.

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.js.
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/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.