enforce-react-spa-architecture

Category: Development & Coding | Uploader: anaregdesign | Downloads: 0 | Version: v1.0（Latest）
Enforce clean-architecture-based development for Vite + React Router + Prisma v7 single-page applications. Use when implementing features, refactoring structure, reviewing code, running quality gates, or preparing to push changes in a React Router SPA that should keep FlatRoute modules thin, components presentational, Prisma server-only, and dependencies flowing inward.
Changelog: Source: GitHub https://github.com/anaregdesign/local-playground
Directory Structure

Current level: skills/enforce-react-spa-architecture/
📁 agents/
- 📄 openai.yaml 326 B
📁 references/
- 📄 flat-route-rest-api-guidelines.md 5.2 KB
- 📄 hotspot-refactor-workflow.md 5.5 KB
- 📄 layout-and-dependency-rules.md 25.0 KB
- 📄 prisma-boundary-rules.md 2.8 KB
- 📄 stateful-flow-compromises.md 4.7 KB
- 📄 verification-gates.md 4.1 KB
- 📄 view-state-and-handler-patterns.md 6.5 KB
📄 SKILL.md 11.7 KB
SKILL.md

---
name: enforce-react-spa-architecture
description: Enforce clean-architecture-based development for Vite + React Router + Prisma v7 single-page applications. Use when implementing features, refactoring structure, reviewing code, running quality gates, or preparing to push changes in a React Router SPA that should keep FlatRoute modules thin, components presentational, Prisma server-only, and dependencies flowing inward.
---

# Enforce React Spa Architecture

## Overview

Use this skill as the default architecture workflow for a React Router SPA that uses Vite and Prisma v7. Keep FlatRoute modules declarative, view files thin, data access server-only, and dependency direction explicit before writing code.

## 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/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:
   - dependency and placement rules: [`references/layout-and-dependency-rules.md`](references/layout-and-dependency-rules.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)
   - 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.
- 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.
- Fix Prisma usage to Prisma ORM v7.x. Treat non-v7 setup as migration work, not as an equal baseline.
- 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.
- 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

### 1. Model the change around a use case

- Name the user intent first.
- Put invariants in `domain/entities` or `domain/value-objects`, and put cross-entity rules in `domain/policies` or `domain/services` when they do not naturally belong to one model.
- Put repository interfaces in `domain/repositories`.
- Keep request or response shapes next to the route, API client, or use case that owns them. Promote them only after the boundary is stable and truly reused.
- Do not move transport `Request` or `Response` types into `domain` just because several modules share them.

### 2. Keep view logic out of components

- Build a custom Hook, controller, or view-model module in `app/lib/client/usecase/` for each non-trivial screen or interaction flow.
- When the interaction has enough complexity to need submodules, create a feature directory and keep the use case internals there.
- Keep feature components near the feature by default. Promote a component to `app/components/shared/` only after it proves to be truly feature-agnostic.
- Let that module own:
  - async calls
  - reducer logic
  - derived screen state
  - event handlers
  - error and pending mapping
- Pass view-ready props into `app/components/`.

### 3. Use React Router primitives before inventing new state containers

- Use loader data for route reads.
- Use action or fetcher state for mutations.
- Use navigation or fetcher pending state instead of duplicating network flags in component state.
- Add client state only for interaction state that is not already owned by the router.

### 4. Move DTOs through the client boundary explicitly

- Return JSON DTOs from route loaders, actions, or API endpoints.
- Let `client/infrastructure/api` fetch those DTOs.
- Rebuild client-facing objects or value objects inside the owning use case only when that adds real value.
- Do not expect server-side `Entity` instance identity to cross the network boundary.

### 5. Assemble dependencies at the edge

- Keep `usecase` and `domain` code constructor-injected.
- Build repository, gateway, and service instances in route loaders, actions, server entry points, or dedicated dependency factories.
- Prefer manual DI with explicit factory functions before introducing a DI container.
- Recreate request-scoped dependencies such as transaction-bound repositories from the current request or transaction context.

### 6. Validate and map errors by layer

- Keep request parsing and input shape validation at the HTTP or client transport boundary.
- Keep use-case rule validation in `server/usecase` or `client/usecase`.
- Keep invariant enforcement in `domain`.
- Map domain, application, and infrastructure errors to transport responses at the edge.

### 7. Keep authorization and serialization explicit

- Resolve authentication at the edge, but keep authorization decisions in use cases or domain policies.
- Convert `Date`, ids, money-like values, and value objects at boundaries rather than leaking transport or ORM shapes inward.

### 8. Keep mutable state scoped

- Do not store request-specific state in module globals or singleton services.
- Pass auth context, user context, tenant context, and correlation metadata explicitly.
- Keep transaction handles scoped to the current transaction only.
- Treat client-side async race conditions as correctness issues and guard against stale responses.

### 9. Use explicit compromises for stateful flows

- For chat, streaming, session, playback, or wizard-style flows, allow a feature-local controller or store when lifecycle and identity genuinely matter.
- Keep that compromise inside `app/lib/client/usecase/<feature>/` rather than spreading mutable state across routes or components.
- Split durable state, ephemeral runtime state, and infrastructure handles explicitly.

### 10. Push side effects and migrations into explicit workflows

- Keep schema changes, background jobs, external notifications, and indexing side effects visible and testable.
- Do not hide them inside random route handlers or repositories.
- Use barrel exports sparingly and only when they do not obscure ownership or create cycles.

### 11. Verify before push

- Run targeted tests for the touched area.
- Run typecheck and lint or the project quality gate.
- Audit for boundary drift and forbidden imports.
- Fix architecture violations before pushing even if tests pass.

### 12. Refactor overloaded files in phases

- When a `ts` or `tsx` file has too many responsibilities, do not rewrite it in one jump.
- Follow the hotspot workflow in [`references/hotspot-refactor-workflow.md`](references/hotspot-refactor-workflow.md).
- Separate analysis, planning, extraction sequencing, execution, and verification.
- Move one stable seam at a time and keep the file working after each batch.

## Placement Guide

- Need pure rendering and markup: `app/components/`
- Need reusable pure UI primitives: `app/components/shared/`
- Need route composition or loader/action bridging: `app/routes/`
- Need client-side state, handlers, reducers, selectors, or orchestration: `app/lib/client/usecase/<feature>/`
- Need browser APIs, API clients, or router adapters: `app/lib/client/infrastructure/`
- Need endpoint-specific API clients: `app/lib/client/infrastructure/api/`
- Need browser-only adapters such as storage, clipboard, media queries, or channel APIs: `app/lib/client/infrastructure/browser/`
- Need a business invariant or behavior-rich model: `app/lib/domain/entities/`
- Need a small immutable business concept with validation: `app/lib/domain/value-objects/`
- Need cross-entity business rules: prefer `app/lib/domain/policies/`
- Need domain-level orchestration that is still infrastructure-free: `app/lib/domain/services/`
- Need a repository port or domain-facing persistence contract: `app/lib/domain/repositories/`
- Need server orchestration: `app/lib/server/usecase/`
- Need Prisma, file system, or external service code: `app/lib/server/infrastructure/`
- Need persistence implementations: `app/lib/server/infrastructure/repositories/`
- Need external SDK or HTTP adapters: `app/lib/server/infrastructure/gateways/`
- Need a reusable type or utility: place it with the owning route, use case, or domain module first; extract only after repeated reuse proves the boundary

## References

- [`references/layout-and-dependency-rules.md`](references/layout-and-dependency-rules.md)
- [`references/flat-route-rest-api-guidelines.md`](references/flat-route-rest-api-guidelines.md)
- [`references/prisma-boundary-rules.md`](references/prisma-boundary-rules.md)
- [`references/view-state-and-handler-patterns.md`](references/view-state-and-handler-patterns.md)
- [`references/stateful-flow-compromises.md`](references/stateful-flow-compromises.md)
- [`references/hotspot-refactor-workflow.md`](references/hotspot-refactor-workflow.md)
- [`references/verification-gates.md`](references/verification-gates.md)
Comments 0
Latest | Hot
Please login before commenting.
No comments yet. Be the first one!
enforce-react-spa-architecture

Directory Structure

SKILL.md

Report

Notice
