devendra-skill-package 1.0.2

package/.github/skills/clean-architecture-generator/references/platform-react.md

@@ -0,0 +1,261 @@
+# Platform File — React (Web)
+
+Read `architecture-core.md` first. This file supplies the React web-specific implementation of the
+universal layers. It intentionally differs from `platform-react-native.md` in the places where the
+browser environment is genuinely different (storage, no native SSL pinning, routing, no
+Keychain/MMKV) — everything else (domain/data separation, use case pattern, mapper pattern) is
+shared with RN because both are plain React with TypeScript.
+
+Everything under "Stack Fingerprint Defaults" applies **only** when Phase 1 detection found nothing
+in the target repo — if the repo already uses a different state library, HTTP client, storage, or
+router, generate against what's already there instead.
+
+---
+
+## Sub-Variant Detection (run before anything else)
+
+| Signal | Sub-variant | Affects |
+|---|---|---|
+| `"next"` in `package.json` | Next.js | Routing (App Router or Pages Router — check for an `app/` vs `pages/` directory), env var prefix (`NEXT_PUBLIC_`) |
+| `"react-scripts"` in `package.json` | Create React App | env var prefix (`REACT_APP_`) |
+| `"vite"` in `package.json`, no meta-framework | Vite | env var prefix (`VITE_`) |
+
+State this project's detected sub-variant before generating any file — it changes the routing
+pattern and the environment variable prefix used in `data/config/`.
+
+---
+
+## Stack Fingerprint Defaults (greenfield only)
+
+| Concern | Detect first (search for) | Default if nothing detected |
+|---|---|---|
+| Language | — | TypeScript, strict mode |
+| State management | `createSlice(`, `create(` from `'zustand'`, `makeAutoObservable(`/`observable(` (mobx), `QueryClient`/`useQuery` (React Query), `useReducer`+`createContext` | Redux Toolkit (`createSlice`, `createAsyncThunk`) + RTK Query (`createApi`) |
+| HTTP client | `axios.create(`, `fetch(`, `createApi(` | Axios with interceptors |
+| Browser storage | existing `storageService`/`localStorage`/`sessionStorage` wrapper | `sessionStorage` for tokens (see Security Rules below), `localStorage` for non-sensitive persisted UI state |
+| Routing | `react-router-dom`, Next.js `app/`/`pages/` directory | React Router v6 (or Next.js's own router if Next.js was detected above) |
+| DI mechanism | existing `di/[feature]Container.ts` files | manual DI — Pattern A or B (identical to the RN patterns, see below) |
+| Test runner | `jest.config.*`, `vitest.config.*` | Vitest for Vite projects, Jest otherwise |
+
+---
+
+## Folder Tree
+
+```
+src/
+├── app/                        # App bootstrap — orchestration only
+│   ├── App.tsx
+│   ├── index.ts
+│   ├── di/
+│   │   ├── container.ts        # Global DI container — wires all feature containers
+│   │   └── index.ts
+│   ├── environment/
+│   │   ├── env.ts               # Reads import.meta.env / process.env with the correct prefix
+│   │   └── index.ts
+│   ├── routing/
+│   │   ├── AppRouter.tsx        # React Router <Routes> tree (or Next.js layout, if Next.js)
+│   │   └── index.ts
+│   └── state/
+│       └── store.ts
+│
+├── core/                       # Infrastructure — shared by all features
+│   ├── api/
+│   │   ├── httpClient.ts       # Singleton Axios/fetch instance + interceptors
+│   │   ├── apiErrorHandler.ts
+│   │   ├── AppError.ts
+│   │   ├── tokenProvider.ts    # Token getter/setter (prevents circular deps)
+│   │   ├── unauthorizedHandler.ts
+│   │   └── index.ts
+│   ├── cache/
+│   │   ├── baseApiSlice.ts     # Single createApi instance for the whole app
+│   │   └── index.ts
+│   ├── config/
+│   │   ├── constants.ts
+│   │   └── index.ts
+│   ├── error/
+│   │   └── errorHandler.ts
+│   ├── logging/
+│   │   └── loggerService.ts
+│   ├── storage/
+│   │   ├── storageService.ts   # sessionStorage/localStorage wrapper — see Security Rules
+│   │   └── index.ts
+│   ├── store/
+│   │   └── hooks.ts            # useAppDispatch, useAppSelector
+│   └── analytics/
+│       └── eventTracker.ts
+│
+├── features/                   # One folder per feature, fully self-contained
+│   └── [feature-name]/
+│       ├── domain/              # Pure TypeScript — ZERO framework imports
+│       │   ├── entities/
+│       │   ├── usecases/
+│       │   ├── repositories/    # Interfaces only (I-prefixed)
+│       │   └── index.ts
+│       ├── data/
+│       │   ├── api/             # Feature-specific HTTP client class
+│       │   ├── dtos/
+│       │   ├── mappers/
+│       │   ├── repositories/
+│       │   ├── config/          # Feature API base URLs, endpoint paths
+│       │   ├── mock/            # Static mock responses (dev/test only)
+│       │   └── index.ts
+│       ├── presentation/
+│       │   ├── pages/            # (RN calls this "screens" — web calls it "pages")
+│       │   ├── components/
+│       │   ├── hooks/
+│       │   ├── routing/          # this feature's route definitions, mounted into AppRouter
+│       │   ├── state/            # Redux slices/thunks/selectors (or detected equivalent)
+│       │   ├── styles/
+│       │   ├── config/
+│       │   ├── utils/
+│       │   ├── validation/
+│       │   └── index.ts
+│       ├── di/
+│       │   └── [Feature]Container.ts
+│       ├── __tests__/
+│       └── index.ts             # Public API — barrel exports everything public
+│
+├── shared/
+│   └── theme/                   # Design tokens only — NO logic, NO components
+│
+├── constants/
+└── types/
+```
+
+---
+
+## Naming Extensions (React web-specific, on top of architecture-core.md)
+
+Identical to the RN naming table in `platform-react-native.md`, with these substitutions:
+
+| Artifact | Convention | Example |
+|----------|------------|---------|
+| Page file (was "Screen" in RN) | PascalCase + `Page` | `HoldingDetailPage.tsx` |
+| Route definitions file | camelCase + `Routes` | `holdingRoutes.tsx` |
+| Everything else (Entity, Repository, UseCase, DTO, Mapper, Slice, Thunks, Selectors, Hook, DI container, Test) | same as `platform-react-native.md` | — |
+
+---
+
+## DI Patterns
+
+Identical mechanism to React Native — plain React has no built-in DI container, so the same manual
+patterns apply. Copy **DI Pattern A (Lazy Getter Object)** and **DI Pattern B (Factory Function)**
+verbatim from `platform-react-native.md`, replacing only the import paths.
+
+## Redux Store, Slice, Thunk, Selector, RTK Query, Domain Layer, Data Layer Patterns
+
+Identical to `platform-react-native.md` — copy those patterns verbatim. The only substitution is
+`axiosClient`/`httpClient` import path (`@core/api/httpClient` instead of `@core/api/axiosClient`)
+and no `react-native-*` imports anywhere.
+
+## Routing Pattern (replaces RN's React Navigation pattern)
+
+**React Router v6:**
+
+```tsx
+// presentation/routing/[feature]Routes.tsx
+import { Route } from 'react-router-dom';
+import { [Feature]MainPage } from '../pages/[Feature]MainPage';
+import { [Feature]DetailPage } from '../pages/[Feature]DetailPage';
+
+export const [feature]Routes = (
+  <>
+    <Route path="/[feature]" element={<[Feature]MainPage />} />
+    <Route path="/[feature]/:id" element={<[Feature]DetailPage />} />
+  </>
+);
+```
+
+Mount `[feature]Routes` inside `app/routing/AppRouter.tsx`'s top-level `<Routes>` tree.
+
+**Next.js (if detected):** do not create a `routing/` folder — the file-system router is the
+routing layer. A "page" is the file at `app/[feature]/page.tsx` (App Router) or
+`pages/[feature]/index.tsx` (Pages Router). The `presentation/pages/[Feature]MainPage.tsx` component
+still lives in the feature folder; the Next.js route file only imports and renders it, so the
+feature remains portable if the app ever migrates off Next.js routing.
+
+## Typed Store Hooks
+
+Identical to `platform-react-native.md` — copy verbatim.
+
+---
+
+## Offline Handling (replaces RN's NetInfo/MMKV offline queue — browser has no native equivalent)
+
+The browser does not have `NetInfo` or a native offline-queue OS primitive. Use the web platform's
+own signals instead — do not port the RN offline-queue pattern uncritically:
+
+1. Detect connectivity via `navigator.onLine` and the `window.addEventListener('online' | 'offline', …)` events.
+2. For simple cases, disable mutating actions while offline and show a banner — RTK Query's
+   `refetchOnReconnect: true` + `setupListeners(store.dispatch)` still applies unchanged.
+3. If the project genuinely needs an offline write queue (not just read-refetch-on-reconnect), that
+   requires a Service Worker + IndexedDB (e.g. Background Sync API) — this is a materially bigger
+   scope than the RN MMKV-backed queue and must be scoped with the user explicitly before building
+   it; do not silently generate a partial Service Worker.
+
+## Security Rules (browser-specific — on top of architecture-core.md)
+
+1. There is no OS Keychain/Keystore in a browser — the closest equivalents by risk profile are, in
+   order of preference: an httpOnly cookie set by the server (not readable by JS, immune to XSS
+   token theft), or in-memory storage with refresh-token rotation, or `sessionStorage` as a lower bar.
+2. **Never** use `localStorage` for access/refresh tokens without explicitly accepting the XSS risk
+   tradeoff with the user — `localStorage` persists across tabs/restarts and is readable by any
+   script on the page, including an injected one. If the project already stores tokens in
+   `localStorage`, do not silently "fix" it; flag the tradeoff and continue only with confirmation.
+3. **Never** disable TLS certificate validation in a Node-side proxy/BFF that this frontend talks to.
+4. Every outbound request signed the same way as RN (nonce header, correlation ID) if the backend
+   contract requires it — read the actual API contract, do not assume the mobile app's signing
+   scheme applies unless the same backend is shared.
+
+---
+
+## Anti-Patterns (React web-specific, on top of architecture-core.md)
+
+- **Never** call `fetch`/`axios` directly from a component or hook — always go through the
+  feature's API client class.
+- **Never** use `useDispatch` / `useSelector` directly if the project defines typed
+  `useAppDispatch/useAppSelector` — use the typed hooks.
+- **Never** use a `boolean` for loading state in a Redux slice — use
+  `'idle' | 'loading' | 'succeeded' | 'failed'`.
+- **Never** define `ThunkExtra` inside the DI container file — define it in the thunks file.
+- **Never** use the class-based `getInstance()` singleton pattern for feature DI containers.
+- **Never** reference `AsyncStorage`, `react-native-keychain`, `MMKV`, or any RN-only package —
+  this is a web target.
+- **Never** hardcode a Next.js/CRA/Vite env var prefix that doesn't match the detected sub-variant.
+
+---
+
+## Worked Example
+
+**Request**: "Add a watchlist feature with ability to fetch and display watchlist items."
+
+**Artifacts**:
+- Domain: `WatchlistItemEntity`, `IWatchlistRepository`, `GetWatchlistUseCase`
+- Data: `WatchlistApiClient`, `WatchlistItemDTO`, `mapWatchlistDTOToDomain`, `WatchlistRepositoryImpl`
+- Presentation: `watchlistSlice`, `watchlistThunks`, `watchlistSelectors`, `WatchlistMainPage`, `watchlistRoutes`
+- DI: `watchlistContainer` (Pattern A)
+
+**Output**:
+```
+Created:
+  src/features/watchlist/domain/entities/WatchlistItemEntity.ts
+  src/features/watchlist/domain/repositories/IWatchlistRepository.ts
+  src/features/watchlist/domain/usecases/GetWatchlistUseCase.ts
+  src/features/watchlist/data/api/WatchlistApiClient.ts
+  src/features/watchlist/data/dtos/WatchlistItemDTO.ts
+  src/features/watchlist/data/mappers/watchlistMappers.ts
+  src/features/watchlist/data/repositories/WatchlistRepositoryImpl.ts
+  src/features/watchlist/presentation/state/watchlistSlice.ts
+  src/features/watchlist/presentation/state/watchlistThunks.ts
+  src/features/watchlist/presentation/state/watchlistSelectors.ts
+  src/features/watchlist/presentation/pages/WatchlistMainPage.tsx
+  src/features/watchlist/presentation/routing/watchlistRoutes.tsx
+  src/features/watchlist/di/watchlistContainer.ts
+  src/features/watchlist/index.ts
+
+Updated:
+  src/app/state/store.ts   (added reducer + container to extraArgument)
+  src/app/routing/AppRouter.tsx  (mounted watchlistRoutes)
+
+Dependency check: PASS — no layer boundary violations detected
+```