enforce-react-spa-architecture

Files (19)

• SKILL.md
• openai.yaml · agents/
• boundary-and-contract-rules.md · references/
• chart-and-data-visualization-guidance.md · references/
• client-layer-responsibilities.md · references/
• dependency-injection-lifetime-and-side-effects.md · references/
• domain-modeling-and-type-rules.md · references/
• flat-route-rest-api-guidelines.md · references/
• hotspot-refactor-workflow.md · references/
• layout-and-dependency-rules.md · references/
• layout-and-module-placement.md · references/
• playwright-ui-verification.md · references/
• prisma-boundary-rules.md · references/
• project-bootstrap.md · references/
• responsive-and-mobile-ui-guidance.md · references/
• server-and-domain-layer-responsibilities.md · references/
• stateful-flow-compromises.md · references/
• verification-gates.md · references/
• view-state-and-handler-patterns.md · references/

SKILL.md (first lines)

# Enforce React Spa Architecture

## Overview

Use this skill as the default architecture workflow for a React Router SPA that uses Vite and Prisma v7. Use it from initial bootstrap through ongoing implementation. Keep FlatRoute modules declarative, view files thin, data access server-only, and dependency direction explicit before writing code.
This skill owns code structure, dependency direction, UI guardrails, and verification for the app codebase. Do not use it to define cloud provider choice, identity provisioning, secret-store topology, IaC layout, or deployment infrastructure; let a companion hosting skill add those concerns while preserving these rules.
This skill also does not own `/doc/spec`, `/doc/plan.md`, commit-log workflow, branch naming workflow, or PR management; use a repository workflow skill for those concerns and keep this skill focused on app code.
For new or unstandardized UI work, prefer Fluent UI React v9 and a quiet, simple visual presentation. Keep primary labels and layouts concise, and move only supplemental, non-essential detail into Tooltip or InfoLabel patterns.
When data visualization is required, prefer the simplest accessible chart that matches the analytical task and keep chart interaction lightweight.
For responsive behavior, prefer guidance that keeps the same feature usable on both desktop and mobile rather than treating `mobile-first` as a universal process requirement.
If a companion hosting skill explicitly overrides runtime mode or config bootstrap, keep these architecture and boundary rules and let the companion override only the hosting-specific pieces.

## Quick Start

1. Classify the requested change:
   - route composition
   - presentational UI
   - client interaction flow
   - server use case
   - persistence or external integration
   - domain rule
   - cross-boundary contract or utility
2. Place code in the canonical layout:
   - `app/routes/`
   - `app/components/`
   - `app/components/shared/`
   - `app/lib/client/usecase/`
   - `app/lib/client/usecase/<feature>/use-<feature>.ts`
   - `app/lib/client/usecase/<feature>/state.ts`
   - `app/lib/client/usecase/<feature>/reducer.ts`
   - `app/lib/client/usecase/<feature>/selectors.ts`
   - `app/lib/client/usecase/<feature>/handlers.ts`
   - `app/lib/client/infrastructure/`
   - `app/lib/client/infrastructure/api/`
   - `app/lib/client/infrastructure/browser/`
   - `app/lib/server/usecase/`
   - `app/lib/server/infrastructure/`
   - `app/lib/server/infrastructure/config/`
   - `app/lib/server/infrastructure/repositories/`
   - `app/lib/server/infrastructure/gateways/`
   - `app/lib/domain/entities/`
   - `app/lib/domain/value-objects/`
   - `app/lib/domain/policies/`
   - `app/lib/domain/services/`
   - `app/lib/domain/repositories/`
3. Read the matching reference file before implementing:
   - project bootstrap and dependency install: [`references/project-bootstrap.md`](references/project-bootstrap.md)
   - architecture overview index for multi-boundary changes: [`references/layout-and-dependency-rules.md`](references/layout-and-dependency-rules.md)
   - layout and module placement: [`references/layout-and-module-placement.md`](references/layout-and-module-placement.md)
   - client layer responsibilities: [`references/client-layer-responsibilities.md`](references/client-layer-responsibilities.md)
   - server and domain layer responsibilities: [`references/server-and-domain-layer-responsibilities.md`](references/server-and-domain-layer-responsibilities.md)
   - boundary, contract, and validation rules: [`references/boundary-and-contract-rules.md`](references/boundary-and-contract-rules.md)
   - domain modeling and type rules: [`references/domain-modeling-and-type-rules.md`](references/domain-modeling-and-type-rules.md)
   - dependency injection, lifetime, and side-effect rules: [`references/dependency-injection-lifetime-and-side-effects.md`](references/dependency-injection-lifetime-and-side-effects.md)
   - FlatRoute REST API rules: [`references/flat-route-rest-api-guidelines.md`](references/flat-route-rest-api-guidelines.md)
   - Prisma usage rules: [`references/prisma-boundary-rules.md`](references/prisma-boundary-rules.md)
   - state and handler composition: [`references/view-state-and-handler-patterns.md`](references/view-state-and-handler-patterns.md)
   - chart and data visualization guidance: [`references/chart-and-data-visualization-guidance.md`](references/chart-and-data-visualization-guidance.md)
   - responsive and mobile UI guidance: [`references/responsive-and-mobile-ui-guidance.md`](references/responsive-and-mobile-ui-guidance.md)
   - Playwright UI verification workflow: [`references/playwright-ui-verification.md`](references/playwright-ui-verification.md)
   - stateful flow compromise rules: [`references/stateful-flow-compromises.md`](references/stateful-flow-compromises.md)
   - hotspot refactor workflow: [`references/hotspot-refactor-workflow.md`](references/hotspot-refactor-workflow.md)
   - verification before push: [`references/verification-gates.md`](references/verification-gates.md)

## Non-Negotiable Rules

- Keep dependency direction inward:
  - `app/routes` and `app/components` depend on client-facing orchestration, never on Prisma
  - `app/lib/client/usecase` depends on `domain` and client adapters
  - `app/lib/server/usecase` depends on `domain` and repository ports
  - `app/lib/server/infrastructure` implements repository ports and external integrations
  - `app/lib/domain/*` depends only on other domain modules
- Keep Prisma imports inside `app/lib/server/infrastructure/`.
- Keep `app/components/` presentational. Allow only ephemeral UI state there, such as local input focus or disclosure toggles.
- Prefer Fluent UI React v9 (`@fluentui/react-components`) for new UI work unless the repository already has a clear design-system standard or an approved migration plan says otherwise.
- Keep UI visually simple: concise labels, low-noise layouts, restrained text density, and deliberate spacing over decorative complexity.
- Use Tooltip or InfoLabel for supplemental, non-essential detail. Do not hide required labels, key instructions, validation messages, or critical status only inside a Tooltip.
- When rendering charts, choose the simplest chart that matches the task: line charts for continuous trends over time, and bar or column charts for comparing discrete categories or ranked values.
- Keep charts low-noise and accessible: avoid 3D or decorative chart junk, avoid color-only encoding, and keep critical values or explanations discoverable without hover.
- For important charts, provide a nearby text summary and, when exact inspection matters, an accessible table or equivalent non-hover path to the underlying values.
- Build responsive UI so the same feature stays capable on both desktop and mobile, using fluid layout primitives and content-driven breakpoints rather than device-name-specific forks or fixed desktop widths.
- Support narrow-screen reflow and avoid ordinary horizontal scrolling for app UI. Do not lock orientation unless a single orientation is genuinely essential.
- Do not rely on hover-only or fine-pointer-only interaction for primary actions, labels, or critical explanation. Keep a touch and keyboard path for the same task.
- Keep touch targets and spacing mobile-usable. Meet at least WCAG 2.2 minimum target size expectations or provide equivalent spacing, and use larger targets when practical.
- For UI-affecting changes, verify the actual rendered result with Playwright before pushing instead of relying only on code inspection.
- Prefer accessible locators and web-first assertions in Playwright, and check the touched flow at the relevant route and viewport sizes.
- Keep async state, mutation handlers, and derived view models in `app/lib/client/usecase/`.
- Co-locate `state`, `reducer`, `selector`, and `handler` modules inside the owning feature directory under `app/lib/client/usecase/<feature>/`.
- Do not create horizontal buckets such as `app/state/`, `app/reducers/`, `app/stores/`, `app/handlers/`, or `app/lib/client/usecase/state/`.
- Keep route modules responsible for HTTP, loader/action wiring, and top-level composition only.
- Validate at the correct layer: transport shape in routes or API adapters, application rules in use cases, business invariants in domain.
- Default client-side data access to `api` adapters plus DTO mapping inside the owning use case. Introduce a client-side repository abstraction only for clear multi-source or local-first requirements.
- Instantiate repositories and gateways in a composition root or dependency factory, not inside domain models or use cases.
- Prefer React Router's official Vite-powered bootstrap for new projects. Use plain `create-vite` only when you intentionally choose a lower-level React Router mode or must retrofit an existing starter.
- Fix Prisma usage to Prisma ORM v7.x. Treat non-v7 setup as migration work, not as an equal baseline.
- Do not put cloud-provider provisioning, app registration, secret-store policy, IaC topology, or release-infrastructure rules in this skill. Keep those in a companion hosting skill while preserving these code-level boundaries.
- Keep authorization, serialization, migration steps, background side effects, and barrel exports intentional rather than ad hoc.
- Treat thread safety mainly as async safety and request safety: avoid module-level mutable state, keep request context out of singletons, and rebuild transaction-scoped dependencies per request.
- Keep feature internals private by default and avoid circular dependencies across extracted modules.
- Use `class` only when identity, invariants, or lifecycle matter. Prefer composition over inheritance, and keep DTO or transport shapes as `type` plus function-based modules.
- Use `interface` for stable object-shaped ports or contracts with multiple implementations. Use `type` for DTOs, unions, mapped shapes, and local view-model shapes.
- Use `unknown` at trust boundaries when a value exists but its shape is not yet proven. Narrow or parse it immediately; do not let raw `unknown` drift into use cases, components, or domain models.
- Keep one concept under one owner. Consolidate duplicate same-role modules only when they represent the same concept in the same boundary.
- Build business behavior around domain models and domain language, but do not force UI state, DTOs, or infrastructure concerns into `domain`.
- Keep constants in the narrowest owning module or feature. Extract repeated stable literals into `constants.ts` only when they have one clear owner; do not build a global constants dump.
- Do not create a generic common bucket. Keep code in the narrowest owning layer, and duplicate small utilities until a stable abstraction is obvious.
- Prefer direct replacement over compatibility aliases when renaming architecture terms.

## Implementation Workflow

### 0. Bootstrap new projects correctly

- When starting from scratch, follow [`references/project-bootstrap.md`](references/project-bootstrap.md) before writing features.
- Prefer `create-react-router` for this skill's architecture because it already aligns with Vite, route modules, and SPA mode.
- Add Prisma v7, the correct driver adapter, `@react-router/fs-routes`, and SPA configuration before layering domain or use-case code.
- Add Fluent UI React v9 early for new UI work so components, theming, and accessibility patterns stay consistent from the first screen.
- Before substantial feature work begins, prefer installing the baseline dependencies the project already knows it will need so architecture work does not drift around missing packages mid-implementation.
- When hosting, identity, or deployment requirements appear, keep this skill on code-level architecture and hand the platform-specific decisions to the companion hosting skill.

From anaregdesign/skills, MIT.

More from anaregdesign/skills