80 lines
3.3 KiB
Markdown
80 lines
3.3 KiB
Markdown
# 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
|
|
|
|
```text
|
|
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](./routing-pages-and-patterns.md)
|
|
and the
|
|
[TypeScript, state, and data-flow target](./typescript-state-and-data-flow.md)
|
|
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.
|