Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 11 additions & 0 deletions .claude/launch.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
{
"version": "0.0.1",
"configurations": [
{
"name": "storybook",
"runtimeExecutable": "pnpm",
"runtimeArgs": ["--filter", "@irene/ui", "storybook", "--no-open"],
"port": 6006
}
]
}
85 changes: 85 additions & 0 deletions .claude/skills/irene-react-patterns/SKILL.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,85 @@
---
name: irene-react-patterns
description: How code is written in the irene-react monorepo (Appknox dashboard, React + TanStack Router/Query + Tailwind + Zustand). Use this skill whenever adding or changing anything in apps/dashboard or packages/* — a page, route, component, form, layout, API endpoint, service, query, mutation, store, websocket/live-update handling, normalized cache, configuration (getConfigValue, feature flags, whitelabel), translation, or test — and whenever porting a screen from the Ember app (irene). Also use it when the user asks where something should go, how a feature should be structured, or "how do we do X here", even if they don't name a specific pattern.
---

# irene-react patterns

A React port of Appknox's Ember dashboard (irene). New code should look like the
code around it. `CLAUDE.md` is the authority on styling, TypeScript, comments,
tests, storage and commits; read it first. This skill covers structure and
per-layer patterns.

## Map

```
apps/dashboard/src/
routes/ thin TanStack file routes: guards, search params, loader, title, component
features/<name>/ real code for one domain
pages/<page>/ index.tsx + components/ hooks/ used only by that page
components/ hooks/ queries/ schemas/ actions/ utils/ store.ts
index.ts public entry, only if something outside renders the feature
components/ layouts/ hooks/ queries/ actions/ utils/ app-wide equivalents
packages/
api/ endpoints, services, types, transforms, stores, normalization, request client
websocket/ server push
ui/ Ak* components, icons, svgs, styles/theme.css
translations/ en.json + ja.json, akMT, <AkMessageTranslate>, FORMATS
config/ constants/ enums/
```

## Where does it go?

Narrowest level that uses it; move up when a second user appears.

| What | Where |
| ------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| URL, guard, search params, title | `routes/…/<name>.tsx` |
| Page | `features/<f>/pages/<page>/index.tsx` |
| Component: one page / one feature / app-wide | `pages/<page>/components/` / `features/<f>/components/` / `src/components/` |
| Generic, no app data or API | `packages/ui/src/components/ak-<name>/` |
| Endpoint paths / HTTP call / response types | `packages/api/src/services/<domain>/endpoints.ts` / `service.ts` / `types.ts` |
| Query keys + `xOptions()` | `features/<f>/queries/` or `src/queries/` |
| Form schema + typed field | `features/<f>/schemas/<form>.ts` |
| **Action**: plain async fn taking `queryClient`; spans cache/stores/storage, or called from guards/loaders | `actions/` (`endSession`, `setupUserAndOrgContext`) |
| **Hook** (`use…`): re-renders on state, or tied to component lifetime. Hands work to actions (`useLogout` → `endSession`) | `hooks/` (`useOrganization`, `useDashboardWebsocket`) |
| Client-only shared state | Zustand: `features/<f>/store.ts` or `packages/api/src/stores/` |
| Server codes (status, platform, risk…) | `ENUMS` from `@irene/enums`, never raw numbers |
| Client-named constants (HTTP statuses, hostnames, support email) | `@irene/constants` |
| Deployment settings / release constants / backend config | `@irene/config` / `@irene/config/product` / `configurationStore` (see [configuration.md](references/configuration.md)) |
| Live updates | tag records in services, then `useWebsocketSignal` / `useWebsocketRecord` (see [websocket.md](references/websocket.md)) |

## Building a feature (bottom-up)

1. Endpoints, types, service in `packages/api`. Then query keys and options.
See [api-and-data.md](references/api-and-data.md).
2. A thin route. See [routing.md](references/routing.md).
3. The page and its components. See [components-and-styles.md](references/components-and-styles.md).
4. Live updates if the data changes server-side. Usually tagging the record is
enough. See [websocket.md](references/websocket.md).
5. Copy in **both** `en.json` and `ja.json`. Use `<AkMessageTranslate id>` in
JSX, and `akMT()` in props, schemas, toasts and titles. Format dates and
numbers through the named `FORMATS`.
6. Tests next to the code (MSW + factories, ≥90% coverage). See
[testing.md](references/testing.md).
7. Porting from irene: carry every condition across. Record deliberate
differences in `DESIGN-DECISIONS.md` and scenarios in `QA-SCENARIOS.md`.

## Everywhere

- JSDoc on every export, saying what it does and **why**.
- Import via package paths (`@irene/ui/ak-button`, `@/features/…`). Apps never
use `@ui/*`, `@api/*` or `@config/*`.
- No `any`, `!`, `@ts-ignore` or `as unknown as`. Derive types from `z.infer`,
`ReturnType`, enums or the route tree.
- Server data lives in TanStack Query. Stores hold client state only.
- Records that are pushed or shared across queries are tagged in the service
(`tagRecordForCaching`).
- Component files stay under 350 lines of code (lint). Private helpers are
`_prefixed` and not exported. Use `data-test-*` hooks for tests.

## Before finishing

```bash
pnpm lint:fix && pnpm lint && pnpm lint:types && pnpm --filter @irene/dashboard test
```
200 changes: 200 additions & 0 deletions .claude/skills/irene-react-patterns/references/api-and-data.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,200 @@
# API, queries, mutations and state

Flow: **endpoints → service → query options → component**, one file per step.

## Endpoints, types, index (`packages/api/src/services/<domain>/`)

```ts
// endpoints.ts: path builders only; encode segments; `as const`
export const OrganizationEndpoints = {
list: () => `${API_NAMESPACES.v1}/organizations` as const,
me: (id: number | string) =>
`${API_NAMESPACES.v1}/organizations/${encodeURIComponent(id)}/me` as const,
};

// index.ts: always this shape
export * from './endpoints';
export type * from './types';
export { default as OrganizationService } from './service';
```

- Namespaces: `v1` `api`, `v2` `api/v2`, `v3` `api/v3`, `hudson`
`api/hudson-api`. Use the one irene used for that endpoint. Tests build MSW
URLs from the same endpoints.
- `types.ts`: `Api*` interfaces with the server's snake_case fields, plus
`Api<X>Request` and `Api<X>Response`.

## Service (`service.ts`)

A default-exported class of `public static readonly` arrow functions. Each one
calls `apiRequest.<verb><T>(url, …)`, which returns the **body**.

```ts
public static readonly getOrganizations = async () => {
const page = await apiRequest.get<ApiPageEnvelope<ApiOrganization>>(
OrganizationEndpoints.list(), { signal: AbortSignal.timeout(REQUEST_ABORT_TIMEOUT_MS) });

return transformPaginatedResponse(page);
};
```

- **Lists**: `ApiPageEnvelope` → `transformPaginatedResponse` → `ApiPage<T>`
(`items`, `count`, `hasNext`…). Components never read `results`.
- **JSON:API responses** (`data.attributes`, kebab-case) are flattened in
`utils/transforms.ts`.
- **Timeouts** are off by default. Add `AbortSignal.timeout(REQUEST_ABORT_TIMEOUT_MS)`
to requests that hold a screen (loaders, boot). Never add it to uploads.
- **Tag** records that are pushed or shared (see Normalized cache below).
- Resolve instead of rejecting only when failure _is_ the answer
(`StatusService`). Otherwise let it reject.

## Enums and status codes

- Server codes come from `ENUMS` (`@irene/enums`, ported 1:1 from irene):
`submission.status === ENUMS.SUBMISSION_STATUS.ANALYZING`, never `=== 6`.
- Each group also has `UNKNOWN` (-1), `BASE_VALUES` / `BASE_CHOICES` (as
declared), and `VALUES` / `CHOICES` (with UNKNOWN).
- Type fields from the group:
`type ApiSubmissionStatus = (typeof ENUMS.SUBMISSION_STATUS)['BASE_VALUES'][number]`.
- Group values with typed `Set`s and `Record`s (`FAILED_STATUSES`,
`PROGRESS_BY_STATUS` in `upload-app/utils.ts`), not `===` chains.
- Display, in order of preference: the server's `*_humanized` field, then
`ENUMS_DISPLAY` (e.g. `'iOS'`), then reduce to an outcome and `akMT` it.
Never show the key.
- Adding an enum: copy it exactly from irene into
`packages/enums/src/categories/<area>.ts`, and update the group and key
counts in `packages/enums/src/index.test.ts`.
- HTTP statuses: `HTTP_STATUS_CODES` from `@irene/constants`, compared against
`getApiErrorStatus(error)`. Never bare numbers. Add missing codes, with a doc
comment, to `status-codes.ts`. The type is `HttpStatusCode`.

## Queries (`features/<f>/queries/<thing>.ts`)

```ts
export const organizationKeys = {
all: () => ['organization'] as const,
me: (orgId: number | string) => [...organizationKeys.all(), 'me', orgId] as const,
};

/** Builds the query for this account's role in one organization. */
export const organizationMeOptions = (orgId: number | string) =>
queryOptions({
queryKey: organizationKeys.me(orgId),
queryFn: () => OrganizationService.getOrganizationMe(orgId),
staleTime: Infinity,
});
```

- **Every `queryFn` calls a service**, never `apiRequest` or `fetch`. It may
add logic around the call.
- Keys nest under `all()`, so `invalidateQueries({ queryKey: xKeys.all() })`
clears the whole domain.
- Defaults: 30s stale time, retries only on network errors and 5xx, no
refetch on focus. Comment any override (`staleTime: Infinity`,
`retry: false` when a 404 is an answer).

**Reading**, always through the `xOptions()` builder:

- In a component that renders the data: `useQuery(xOptions())`. Handle
`isPending` with a skeleton and errors in place (`getApiErrorStatus`,
`isRateLimited`). Most pages fetch this way.
- In guards, loaders and actions: `await queryClient.query(xOptions())`. If a
loader pre-fills the cache, the component still reads it with `useQuery`.
Never use `useLoaderData`.
- Conditional queries use `enabled`, never a hook inside an `if`. No
`useEffect` fetching. `getQueryData` only for rare merges.
`useSuspenseQuery` and `useInfiniteQuery` aren't used.

## Mutations

Put `useMutation` inline when it's short, or in a `use<Action>` hook when the
logic is long or reused (`useLogin`, which returns `{ login, failure }`).

```ts
const recover = useMutation({
mutationFn: ({ username }: RecoverFormSchema) => AuthService.recoverPassword(username),
onError: unlessRateLimited((error) => {
const message = getApiFieldErrors<'username'>(error).username?.[0];

if (message) {
form.setError('username', { message });
} else {
akNotify.error(akMT('somethingWentWrong'));
}
}),
});
```

- `mutationFn` calls a service. Trigger with `.mutate()` and handle outcomes
in callbacks; `mutateAsync` isn't used.
- `isPending` → `<AkButton loading>`. Use `onSettled` for "either way" cleanup
(`useLogout`). Mutations are never retried.
- Wrap `onError` in `unlessRateLimited` (429s are announced globally). Field
errors go onto the form; anything else becomes `akNotify.error(akMT(…))`.
- Updating the cache afterwards, in order of preference:
1. tagged reply → `useNormalizedRecordCache().write(type, record)`
2. new row in a visible list → `prependRecordToPage`
3. patch one row → `setQueryData` + `patchPaginationItem`
4. otherwise `invalidateQueries`
- Optimistic updates only for small, reversible toggles (the notification
read state): `cancelQueries`, snapshot, `setQueryData` in `onMutate`, and
restore the snapshot in `onError`.

## Normalized cache (`@normy/react-query`)

`NormalizationProvider` (in `App.tsx` and the test render helpers) keys records
by `"<type>:<id>"`, so writing a record once updates **every** query holding
it. Only records carrying the client-added `__record` field take part;
everything else behaves like plain TanStack Query.

- **Tag in the service**, after any transform:
`tagRecordForCaching('file', file)` or
`tagPaginatedRecordsForCaching('submission', page)`. The result type is
`ApiTaggedRecord<T>`. Tag every endpoint that returns that type, or one copy
never updates.
- **New type**: add it to `API_RECORD_TYPES` (the server's name), and to
`ApiRecordShapes` if hooks need it typed. Only tag types that are pushed or
shared.
- **Writing**: `useNormalizedRecordCache()` gives `.write(type, record)` to
patch everywhere and `.readQueriesHolding(type, id)` to invalidate.
Normalization can't _add_ rows to a list, so use `prependRecordToPage` for
that.
- **Gotcha**: strip `__record` before sending a cached record as a request
body.

## Actions

Plain async functions taking `queryClient` first (`endSession`,
`loadConfiguration`, `setupUserAndOrgContext`), callable from routes, hooks
and tests. Use `Promise.all` for independent fetches, and `allSettled` when
one failure shouldn't block the rest.

## Stores (Zustand) vs queries

| | Query | Store |
| --------------------- | -------------------------------- | ------------------------------------------------------------------- |
| Holds | server data (a service's answer) | client state, or a server value that must be read synchronously |
| Filled by | its `queryFn` → service | an action, the interceptor or the UI. **Never a service directly.** |
| Stays fresh by itself | yes | no |
| Read | `useQuery` / `queryClient.query` | a `use…` hook / `xStore.getState()` |

Today's stores: `configurationStore`, `organizationStore` and
`vulnerabilityStore` are filled from queries by actions for synchronous
reads. `rateLimitStore` is filled by the 429 interceptor, and `uploadAppStore`
holds client-only upload progress.

```ts
export const organizationStore = createStore<OrganizationStore>((set) => ({
...NONE_SELECTED,
select: (organization) => set({ selected: organization }),
clear: () => set(NONE_SELECTED),
}));

export const useOrganization = () => useStore(organizationStore); // src/hooks
```

- Use `createStore` from `zustand/vanilla`, so guards can read it.
- Give each store a `clear()` and call it from `endSession`, or one account's
data leaks into the next sign-in.
- Persisted values go under `irene:<name>` keys, with storage access wrapped
in try/catch.
Loading
Loading