@react-vault/create-app 0.1.0

package/templates/rtk-query/.claude/skills/constants-organization/references/example-files.md

@@ -0,0 +1,134 @@
+# Constants files — templates
+
+## `src/utils/constants/apiConstants.ts`
+
+```ts
+export const API_VERSION = '/v1';
+export const API_URL = import.meta.env.VITE_API_BASE_URL;
+
+// HTTP methods as constants — used by axiosBaseQuery method comparisons
+export const GET = 'GET' as const;
+export const POST = 'POST' as const;
+export const PUT = 'PUT' as const;
+export const PATCH = 'PATCH' as const;
+export const DELETE = 'DELETE' as const;
+```
+
+## `src/utils/constants/appConstants.ts`
+
+```ts
+// Storage keys
+export const LOGGED_IN_USER = 'loggedInUser';
+export const SELECTED_LOCALE = 'selectedLocale';
+export const THEME_PREFERENCE = 'themePreference';
+
+// Notification types
+export const SUCCESS = 'success' as const;
+export const ERROR = 'error' as const;
+export const INFO = 'info' as const;
+export const WARNING = 'warning' as const;
+
+// Status enums
+export const KYC_STATUS = {
+  PENDING: 'pending',
+  APPROVED: 'approved',
+  REJECTED: 'rejected',
+  REVIEW: 'review',
+} as const;
+export type KycStatus = (typeof KYC_STATUS)[keyof typeof KYC_STATUS];
+```
+
+## `src/utils/constants/urlConstants.ts`
+
+```ts
+// Group endpoints by feature. Use functions for dynamic paths.
+
+export const AUTH_URLS = {
+  LOGIN: '/auth/login',
+  LOGOUT: '/auth/logout',
+  REFRESH: '/auth/refresh',
+  PROFILE: '/auth/profile',
+} as const;
+
+export const KYC_URLS = {
+  LIST: '/kyc',
+  DETAIL: (id: string) => `/kyc/${id}`,
+  SUBMIT: '/kyc/submit',
+  APPROVE: (id: string) => `/kyc/${id}/approve`,
+  REJECT: (id: string) => `/kyc/${id}/reject`,
+} as const;
+
+export const TRANSACTION_URLS = {
+  LIST: '/transactions',
+  DETAIL: (id: string) => `/transactions/${id}`,
+  CREATE: '/transactions',
+} as const;
+
+// Used by request interceptor side-paths (if any)
+export const VALIDATE_INVITATION = '/auth/validate-invitation';
+```
+
+## `src/utils/constants/routeConstants.ts`
+
+```ts
+export const ROUTES = {
+  home: '/',
+  login: '/login',
+  dashboard: '/dashboard',
+  kyc: {
+    list: '/kyc',
+    detail: '/kyc/:id',
+    submit: '/kyc/submit',
+  },
+  transactions: {
+    list: '/transactions',
+    detail: '/transactions/:id',
+    create: '/transactions/new',
+  },
+  notFound: '*',
+} as const;
+
+// For useNavigate() with dynamic params, write small helpers:
+export const kycDetailPath = (id: string): string => `/kyc/${id}`;
+export const transactionDetailPath = (id: string): string => `/transactions/${id}`;
+```
+
+## `src/utils/constants/tagTypes.ts`
+
+```ts
+// Every RTK Query API's tagTypes array unions from here.
+// One literal per feature/entity. Keep this list as the source of truth.
+
+export const TAG_TYPES = [
+  'User',
+  'Kyc',
+  'Transaction',
+  'Loan',
+  'Document',
+  'AccessRights',
+] as const;
+
+export type TagType = (typeof TAG_TYPES)[number];
+```
+
+## `src/utils/constants/regexConstants.ts`
+
+```ts
+// Re-export the BFSI patterns from core so there's one source of truth.
+// Add app-specific regexes below.
+
+export { PII_PATTERNS } from '@<scope>/core/pii';
+
+// Pull out common ones with friendlier names:
+import { PII_PATTERNS } from '@<scope>/core/pii';
+export const PAN_REGEX = PII_PATTERNS.pan;
+export const AADHAAR_REGEX = PII_PATTERNS.aadhaar;
+export const MOBILE_REGEX = PII_PATTERNS.mobileIndia;
+export const IFSC_REGEX = PII_PATTERNS.ifsc;
+export const PINCODE_REGEX = PII_PATTERNS.pincodeIndia;
+export const EMAIL_REGEX = PII_PATTERNS.email;
+
+// App-specific patterns:
+export const REFERENCE_CODE_REGEX = /^ERR-[A-Z0-9]{4}$/;
+export const TRANSACTION_ID_REGEX = /^TXN[0-9]{12}$/;
+```

package/templates/rtk-query/.claude/skills/constants-organization/references/tag-types-catalog.md

@@ -0,0 +1,53 @@
+# Tag types catalog
+
+RTK Query uses tag types for cache invalidation. Each feature picks ONE tag type per entity it manages.
+
+## Naming
+
+- Singular, PascalCase: `User`, `Kyc`, `Transaction`, `Loan`
+- One tag per logical entity, not per endpoint
+- A single tag covers list + detail of the same entity
+
+## Provides vs invalidates
+
+| Endpoint       | Use                                                           | Why                                                                |
+| -------------- | ------------------------------------------------------------- | ------------------------------------------------------------------ |
+| `getKycList`   | `providesTags: ['Kyc']`                                       | Reads → marks the cache as having Kyc data                         |
+| `getKycDetail` | `providesTags: (_, _, id) => [{ type: 'Kyc', id }]`           | Read for one — tagged with the id so detail invalidates separately |
+| `submitKyc`    | `invalidatesTags: ['Kyc']`                                    | Mutation → invalidates ALL Kyc-tagged caches (list refetches)      |
+| `approveKyc`   | `invalidatesTags: (_, _, id) => [{ type: 'Kyc', id }, 'Kyc']` | Per-record + list                                                  |
+
+## Cross-feature invalidation
+
+When a mutation in feature A should invalidate caches in feature B, two patterns:
+
+### Pattern 1 — Tag both features
+
+```ts
+// transactionsApi.ts
+endpoints: (builder) => ({
+  createTransaction: builder.mutation({
+    query: ...,
+    invalidatesTags: ['Transaction', 'AccountBalance'],
+  }),
+}),
+```
+
+If both `Transaction` and `AccountBalance` are tag types provided by their respective APIs, both refetch.
+
+### Pattern 2 — Middleware-driven
+
+Use the `invalidateCacheMiddleware` (in `src/redux/`). When `transactionsApi.endpoints.create.matchFulfilled(action)` fires, dispatch invalidation on another API:
+
+```ts
+store.dispatch(accountsApi.util.invalidateTags(['AccountBalance']));
+```
+
+Use Pattern 2 when there's a chain (one mutation affects N caches) and listing them all in `invalidatesTags` becomes noisy.
+
+## Anti-patterns
+
+- ❌ A tag per endpoint (`KycList`, `KycDetail`, `KycSubmit`) — proliferates without benefit
+- ❌ Forgetting `as const` on the array — types degrade to `string[]`
+- ❌ Same tag name across multiple APIs without sharing — invalidations don't cross
+- ❌ String-typed tag references instead of using the exported `TagType` union

package/templates/rtk-query/.claude/skills/redux-store-integration/SKILL.md

@@ -0,0 +1,159 @@
+---
+name: redux-store-integration
+description: Wire a new RTK Query API or Redux slice into the store. Covers registering reducers in rootReducer.ts, appending middleware in store.ts, using typed hooks (useAppDispatch / useAppSelector), and cross-API cache invalidation. Use when the user just scaffolded a new feature's api.ts or slice.ts and needs to plug it into the store, or asks about cache invalidation middleware, typed hooks, or Redux wiring.
+---
+
+# Redux Store Integration
+
+After scaffolding a new feature with an `api.ts` (RTK Query) or `slice.ts` (regular Redux), you have to register it in TWO places. Both are tiny but easy to forget.
+
+## File map
+
+```
+src/redux/
+├── store.ts                       configureStore + middleware concat
+├── rootReducer.ts                 combineReducers (slices + API reducers)
+├── reduxHooks.ts                  typed useAppDispatch / useAppSelector
+└── invalidateCacheMiddleware.ts   cross-API cache invalidation rules
+```
+
+## Workflow — adding an RTK Query API
+
+### Step 1 — Register the reducer
+
+Open `src/redux/rootReducer.ts`:
+
+```ts
+import { combineReducers } from '@reduxjs/toolkit';
+import kycApi from '@/features/Kyc/api';
+
+const rootReducer = combineReducers({
+  [kycApi.reducerPath]: kycApi.reducer,
+});
+
+export default rootReducer;
+```
+
+Use `[api.reducerPath]` as the key — never a hardcoded string. The `reducerPath` is set inside `createApi({ reducerPath: 'kycApi', ... })`.
+
+### Step 2 — Append the middleware
+
+Open `src/redux/store.ts`:
+
+```ts
+import kycApi from '@/features/Kyc/api';
+
+const store = configureStore({
+  reducer: rootReducer,
+  middleware: (getDefaultMiddleware) => getDefaultMiddleware().concat([kycApi.middleware]),
+  devTools: true,
+});
+```
+
+Without this, RTK Query won't intercept the API's actions. Symptoms: queries fire but cache never updates, subscriptions don't trigger refetch.
+
+### Step 3 — Use the API in components
+
+```tsx
+import { useGetKycListQuery } from '@/features/Kyc/api';
+import { useAppDispatch, useAppSelector } from '@/redux/reduxHooks';
+
+function KycList() {
+  const { data, isLoading, error } = useGetKycListQuery();
+  // ...
+}
+```
+
+NEVER use plain `useDispatch` / `useSelector` directly — use the typed hooks. They give you `RootState` autocomplete + `AppDispatch` action types.
+
+## Workflow — adding a regular Redux slice
+
+### Step 1 — Create the slice
+
+In `src/features/<Feature>/slice.ts`:
+
+```ts
+import { createSlice, type PayloadAction } from '@reduxjs/toolkit';
+
+interface FeatureState {
+  selectedId: string | null;
+  filters: Record<string, unknown>;
+}
+
+const initialState: FeatureState = { selectedId: null, filters: {} };
+
+const featureSlice = createSlice({
+  name: 'feature',
+  initialState,
+  reducers: {
+    setSelected: (state, action: PayloadAction<string | null>) => {
+      state.selectedId = action.payload;
+    },
+    setFilters: (state, action: PayloadAction<Record<string, unknown>>) => {
+      state.filters = action.payload;
+    },
+    reset: () => initialState,
+  },
+});
+
+export const { setSelected, setFilters, reset } = featureSlice.actions;
+export const featureReducer = featureSlice.reducer;
+```
+
+### Step 2 — Register
+
+In `src/redux/rootReducer.ts`:
+
+```ts
+import { featureReducer } from '@/features/Feature/slice';
+
+const rootReducer = combineReducers({
+  feature: featureReducer,
+});
+```
+
+No middleware step for plain slices (they go through `getDefaultMiddleware` automatically).
+
+## Cross-API cache invalidation
+
+When mutation in one API should invalidate another API's cache, use `src/redux/invalidateCacheMiddleware.ts`:
+
+```ts
+import type { Middleware } from '@reduxjs/toolkit';
+import kycApi from '@/features/Kyc/api';
+import userApi from '@/features/User/api';
+
+const invalidateCacheMiddleware: Middleware = (storeApi) => (next) => (action) => {
+  if (kycApi.endpoints.submitKyc.matchFulfilled(action)) {
+    storeApi.dispatch(userApi.util.invalidateTags(['User']));
+  }
+  return next(action);
+};
+
+export default invalidateCacheMiddleware;
+```
+
+Make sure `invalidateCacheMiddleware` is included in `store.ts`'s middleware concat array.
+
+See [`references/middleware-patterns.md`](references/middleware-patterns.md) for common invalidation patterns.
+
+## Conventions enforced
+
+- ❌ NEVER import `useDispatch` / `useSelector` from `react-redux` — use `useAppDispatch` / `useAppSelector` from `reduxHooks`.
+- ❌ NEVER hardcode an API's reducerPath as a string in `rootReducer.ts` — use `[api.reducerPath]`.
+- ❌ NEVER skip the middleware registration — leads to silent cache-bust failures.
+- ✅ Register middleware in the order: `invalidateCacheMiddleware` first, then feature APIs.
+- ✅ Slices live next to their feature (`src/features/<Feature>/slice.ts`).
+- ✅ Each API has a unique `reducerPath`; never share.
+
+## Checklist when wiring a new feature
+
+- [ ] Reducer registered in `rootReducer.ts`
+- [ ] Middleware appended in `store.ts` (if it's an API)
+- [ ] Containers use `useAppDispatch` / `useAppSelector` (typed)
+- [ ] Cross-API invalidations added to `invalidateCacheMiddleware.ts` (if any)
+
+## References
+
+- [`references/middleware-patterns.md`](references/middleware-patterns.md) — common cross-API invalidation patterns
+- [`references/localStorage-persistence.md`](references/localStorage-persistence.md) — pattern for persisting a slice to localStorage

package/templates/rtk-query/.claude/skills/redux-store-integration/references/localStorage-persistence.md

@@ -0,0 +1,70 @@
+# Persisting a slice to localStorage
+
+For state that must survive a page reload (locale, theme, in-progress form drafts) but is NOT sensitive (no PII, no tokens).
+
+## Rule
+
+> Tokens NEVER go in localStorage. Use `setAuthToken()` from `@<scope>/core/http` instead, which keeps them in memory.
+
+For non-sensitive state, this pattern is fine.
+
+## Pattern — `store.subscribe`
+
+```ts
+// src/redux/store.ts
+import { LOCALE_KEY, THEME_KEY } from '@/utils/constants/appConstants';
+
+store.subscribe(() => {
+  const state = store.getState();
+  // Only persist allow-listed slices, not the entire store:
+  localStorage.setItem(LOCALE_KEY, JSON.stringify(state.locale));
+  localStorage.setItem(THEME_KEY, JSON.stringify(state.theme));
+});
+```
+
+## Pattern — `preloadedState`
+
+Rehydrate on store init:
+
+```ts
+const preloadedState = {
+  locale: tryParse(localStorage.getItem(LOCALE_KEY)) ?? initialLocaleState,
+  theme: tryParse(localStorage.getItem(THEME_KEY)) ?? initialThemeState,
+};
+
+const store = configureStore({
+  reducer: rootReducer,
+  preloadedState,
+  middleware: ...,
+});
+
+function tryParse<T>(raw: string | null): T | null {
+  if (!raw) return null;
+  try { return JSON.parse(raw) as T; } catch { return null; }
+}
+```
+
+## Don't persist these slices
+
+- Anything containing auth tokens
+- Anything containing PII (PAN, Aadhaar, account#)
+- RTK Query API cache (`[api.reducerPath]`) — let RTK Query handle its own cache lifecycle
+- Anything with timestamps that go stale (notifications, idle markers)
+
+## Preferred alternative for non-trivial cases
+
+Use `@<scope>/core/storage` (`secureStorage.put/get`) with sensitivity tier `'session'`. It does the same job but:
+
+- One memory + sessionStorage codepath (no leak risk)
+- Optional TTL eviction
+- Easier to swap to encrypted IndexedDB later
+
+```ts
+import { put, get } from '@<scope>/core/storage';
+
+// On store.subscribe:
+put('locale', state.locale, { sensitivity: 'session' });
+
+// On init:
+const persisted = get<LocaleState>('locale', { sensitivity: 'session' });
+```

package/templates/rtk-query/.claude/skills/redux-store-integration/references/middleware-patterns.md

@@ -0,0 +1,82 @@
+# Cross-API cache invalidation patterns
+
+When `invalidatesTags` on a single endpoint isn't enough — typically because the mutation in API A should invalidate caches in API B that's not coupled to A's tagTypes.
+
+## Pattern: One mutation invalidates many APIs
+
+```ts
+import type { Middleware } from '@reduxjs/toolkit';
+import authApi from '@/features/Auth/api';
+import userApi from '@/features/User/api';
+import permissionsApi from '@/features/Permissions/api';
+
+const invalidateCacheMiddleware: Middleware = (storeApi) => (next) => (action) => {
+  // Login → re-fetch user profile + permissions
+  if (authApi.endpoints.login.matchFulfilled(action)) {
+    storeApi.dispatch(userApi.util.invalidateTags(['User']));
+    storeApi.dispatch(permissionsApi.util.invalidateTags(['Permission']));
+  }
+
+  return next(action);
+};
+```
+
+## Pattern: Conditional invalidation
+
+```ts
+if (kycApi.endpoints.submitKyc.matchFulfilled(action)) {
+  const newStatus = action.payload?.status;
+  if (newStatus === 'approved') {
+    storeApi.dispatch(accountsApi.util.invalidateTags(['Account']));
+  }
+}
+```
+
+## Pattern: Reset on logout
+
+```ts
+if (authApi.endpoints.logout.matchFulfilled(action)) {
+  storeApi.dispatch(kycApi.util.resetApiState());
+  storeApi.dispatch(transactionsApi.util.resetApiState());
+  storeApi.dispatch(userApi.util.resetApiState());
+}
+```
+
+`resetApiState` wipes all cached data for that API — safer than tag invalidation on logout because it also clears in-flight queries.
+
+## Pattern: matchAny for grouped events
+
+```ts
+import { isAnyOf } from '@reduxjs/toolkit';
+
+const matchAnyMutation = isAnyOf(
+  kycApi.endpoints.submitKyc.matchFulfilled,
+  kycApi.endpoints.approveKyc.matchFulfilled,
+  kycApi.endpoints.rejectKyc.matchFulfilled,
+);
+
+if (matchAnyMutation(action)) {
+  storeApi.dispatch(auditApi.util.invalidateTags(['AuditEvent']));
+}
+```
+
+## Anti-pattern: invalidate inside endpoints' `onQueryStarted`
+
+Tempting but bad: it couples the source API to the target. Prefer middleware so the source API stays unaware. Easier to grep for invalidations (one file) and easier to test.
+
+## Order matters
+
+In `store.ts`, register `invalidateCacheMiddleware` BEFORE the feature APIs' middleware:
+
+```ts
+middleware: (getDefaultMiddleware) =>
+  getDefaultMiddleware().concat([
+    invalidateCacheMiddleware,    // first
+    authApi.middleware,
+    userApi.middleware,
+    kycApi.middleware,
+    // ...
+  ]),
+```
+
+This way the invalidation middleware sees the fulfilled action BEFORE the API's own subscription dispatches a refetch, avoiding a brief stale window.

package/templates/rtk-query/.claude/skills/rtk-query-api/SKILL.md

@@ -0,0 +1,148 @@
+---
+name: rtk-query-api
+description: Create an RTK Query API file for a feature. Covers createApi with axiosBaseQuery, query/mutation endpoints, tagTypes for cache invalidation, opt-in success/error notifications, typed request/response interfaces with Zod parse, and exported React hooks. Use when adding a new feature's api.ts, adding endpoints to an existing API, or wiring tag types.
+---
+
+# RTK Query API
+
+Every feature has an `api.ts` at `src/features/<Feature>/api.ts`. It uses `createApi` with the project's `axiosBaseQuery` and exposes auto-generated React hooks.
+
+## File map (typical feature)
+
+```
+src/features/<Feature>/
+├── api.ts             createApi + endpoints
+├── schema.ts          Zod schemas (request + response)
+├── types.ts           inferred types from Zod
+├── constants.ts       cache tag references + audit event names
+└── containers/...
+```
+
+## Workflow — new feature API
+
+### Step 1 — Define schemas
+
+`src/features/Kyc/schema.ts`:
+
+```ts
+import { z } from 'zod';
+import { PAN_REGEX, AADHAAR_REGEX } from '@/utils/constants/regexConstants';
+
+export const kycRecordSchema = z.object({
+  id: z.string(),
+  pan: z.string().regex(PAN_REGEX),
+  aadhaar: z.string().regex(AADHAAR_REGEX),
+  status: z.enum(['pending', 'approved', 'rejected']),
+  createdAt: z.coerce.date(),
+});
+
+export const kycListResponseSchema = z.object({
+  items: z.array(kycRecordSchema),
+  total: z.number().int().nonnegative(),
+});
+
+export const kycSubmitRequestSchema = z.object({
+  pan: z.string().regex(PAN_REGEX),
+  aadhaar: z.string().regex(AADHAAR_REGEX),
+});
+```
+
+Types are inferred — never hand-write them:
+
+```ts
+// types.ts
+import { z } from 'zod';
+import type { kycRecordSchema, kycListResponseSchema, kycSubmitRequestSchema } from './schema';
+
+export type KycRecord = z.infer<typeof kycRecordSchema>;
+export type KycListResponse = z.infer<typeof kycListResponseSchema>;
+export type KycSubmitRequest = z.infer<typeof kycSubmitRequestSchema>;
+```
+
+### Step 2 — Create the API
+
+`src/features/Kyc/api.ts`:
+
+```ts
+import { createApi } from '@reduxjs/toolkit/query/react';
+import axiosBaseQuery from '@/axiosconfig/baseQuery';
+import { KYC_URLS } from '@/utils/constants/urlConstants';
+import { GET, POST } from '@/utils/constants/apiConstants';
+import { kycRecordSchema, kycListResponseSchema } from './schema';
+import type { KycListResponse, KycSubmitRequest, KycRecord } from './types';
+
+const kycApi = createApi({
+  reducerPath: 'kycApi',
+  baseQuery: axiosBaseQuery(),
+  tagTypes: ['Kyc'],
+  endpoints: (builder) => ({
+    getKycList: builder.query<KycListResponse, void>({
+      query: () => ({ url: KYC_URLS.LIST, method: GET }),
+      transformResponse: (raw: unknown) => kycListResponseSchema.parse(raw),
+      providesTags: ['Kyc'],
+    }),
+    getKycDetail: builder.query<KycRecord, string>({
+      query: (id) => ({ url: KYC_URLS.DETAIL(id), method: GET }),
+      transformResponse: (raw: unknown) => kycRecordSchema.parse(raw),
+      providesTags: (_, __, id) => [{ type: 'Kyc', id }],
+    }),
+    submitKyc: builder.mutation<KycRecord, KycSubmitRequest>({
+      query: (body) => ({
+        url: KYC_URLS.SUBMIT,
+        method: POST,
+        data: body,
+        showSuccessNotification: true,
+        showFailureNotification: true,
+      }),
+      transformResponse: (raw: unknown) => kycRecordSchema.parse(raw),
+      invalidatesTags: ['Kyc'],
+    }),
+  }),
+});
+
+export const { useGetKycListQuery, useGetKycDetailQuery, useSubmitKycMutation } = kycApi;
+export default kycApi;
+```
+
+### Step 3 — Register in the store
+
+See the `redux-store-integration` skill: register `kycApi.reducer` in `rootReducer.ts` and `kycApi.middleware` in `store.ts`.
+
+### Step 4 — Use the hooks
+
+```tsx
+import { useGetKycListQuery, useSubmitKycMutation } from '@/features/Kyc/api';
+
+function KycList() {
+  const { data, isLoading, error } = useGetKycListQuery();
+  const [submit] = useSubmitKycMutation();
+  // ...
+}
+```
+
+## Conventions enforced
+
+- ❌ NEVER use `fetchBaseQuery` — always `axiosBaseQuery()` (so notifications/auth/interceptors apply).
+- ❌ NEVER skip `transformResponse: schema.parse` — every response must validate at runtime.
+- ❌ NEVER hand-write request/response types — infer from Zod.
+- ❌ NEVER inline a URL string — use `urlConstants.ts`.
+- ❌ NEVER inline a method string — use `apiConstants.ts` (`GET`, `POST`, …).
+- ✅ One `reducerPath` per feature API (kebab → camelCase: `kycApi`, `loanApi`).
+- ✅ Mutations always set `showFailureNotification: true`. Queries usually don't.
+- ✅ `tagTypes` from `tagTypes.ts` catalog (see constants-organization skill).
+- ✅ Audit-sensitive mutations also dispatch audit events (see the toolkit's `bfsi-audit-action` skill).
+
+## Notification flags
+
+```ts
+showSuccessNotification: true; // success path dispatches toast
+showFailureNotification: true; // error path dispatches toast
+```
+
+Both default to `false` — opt-in per endpoint. Read by `axiosBaseQuery` and routed through your Notification slice (see the `axios-auth` skill's notification-wiring reference).
+
+## References
+
+- [`references/endpoint-cookbook.md`](references/endpoint-cookbook.md) — list, detail, create, update, delete, paginated, polling, file-upload examples
+- [`references/optimistic-update.md`](references/optimistic-update.md) — when and how to do optimistic UI updates with `onQueryStarted`
+- [`references/cache-strategies.md`](references/cache-strategies.md) — `providesTags` / `invalidatesTags` patterns by feature shape