keycloak init

frontend/architecture.md

@@ -7,11 +7,14 @@ Frontend stack:
 - Vite
 - React Admin
 - shadcn/ui
+- Keycloak JS
 
 The frontend is generated from the DSL and API specification.
 
 Each entity becomes a React Admin resource.
 
+The generated frontend must also include Keycloak authentication by default.
+
 ---
 
 # Project Structure
@@ -21,6 +24,17 @@ client/
 
     App.tsx
 
+    main.tsx
+
+    dataProvider.ts
+
+    auth/
+      keycloak.ts
+      authProvider.ts
+
+    config/
+      env.ts
+
     resources/
 
       {entity}/
@@ -35,6 +49,13 @@ client/
 
 Each resource must be registered in App.tsx.
 
+The generated `App.tsx` must register:
+
+- `dataProvider`
+- `authProvider`
+
+The generated `Admin` root must enforce authenticated operation. The generated frontend must not operate anonymously once auth is enabled.
+
 Example:
 
 <Resource
@@ -49,7 +70,7 @@ Example:
 
 # Data Provider
 
-React Admin uses the standard REST provider.
+React Admin uses a generated shared REST-compatible data provider.
 
 API format must follow:
 
@@ -66,6 +87,43 @@ List response format:
   total: number
 }
 
+The generated `dataProvider.ts` must remain the **single shared request seam** for backend API calls.
+
+Rules:
+
+1. Use an env-driven API base URL.
+2. Attach `Authorization: Bearer <access_token>` in this shared seam.
+3. Cover all React Admin operations, including references and bulk fetches.
+4. Do not scatter auth headers across resource components.
+
+---
+
+# Application Bootstrap
+
+The generated `main.tsx` must initialize Keycloak before rendering the SPA.
+
+Rules:
+
+1. Use redirect-based Keycloak login only.
+2. Use Authorization Code + PKCE (`S256`).
+3. Do not generate a custom in-app username/password login form.
+4. Do not render the authenticated admin app before Keycloak initialization completes.
+
+---
+
+# Config
+
+The generated frontend must include a dedicated config module in `src/config/`.
+
+Required env variables:
+
+- `VITE_API_URL`
+- `VITE_KEYCLOAK_URL`
+- `VITE_KEYCLOAK_REALM`
+- `VITE_KEYCLOAK_CLIENT_ID`
+
+The generated frontend config must fail fast if required auth variables are missing. The generated frontend must not silently fall back to production auth settings in code.
+
 ---
 
 # Foreign Keys
@@ -120,4 +178,4 @@ React Admin resource name (used in `<Resource name="..." />` and in `reference`
 Examples in App.tsx:
 - `<Resource name="equipment" list={EquipmentList} create={EquipmentCreate} edit={EquipmentEdit} show={EquipmentShow} />`
 - `<Resource name="equipment-types" list={EquipmentTypeList} ... />`
-- `<Resource name="repair-orders" list={RepairOrderList} ... />`
+- `<Resource name="repair-orders" list={RepairOrderList} ... />`

frontend/react-admin-rules.md

@@ -4,6 +4,55 @@ Entity attributes determine UI fields.
 
 ---
 
+# Authentication
+
+Generated React Admin applications in this repository must include an `authProvider`.
+
+Rules:
+
+1. `authProvider` is mandatory.
+2. The generated app must use redirect-based Keycloak login only.
+3. The generator must not create a custom in-app username/password form.
+4. The generated app must initialize authentication before rendering the admin UI.
+
+---
+
+# Shared Authenticated Request Layer
+
+The generated frontend must attach bearer tokens through the shared request seam in `client/src/dataProvider.ts`.
+
+Rules:
+
+1. All resource calls must use the same authenticated request layer.
+2. Reference lookups must use the same authenticated request layer.
+3. The generated frontend must not attach auth headers directly inside resource components.
+
+---
+
+# Error Handling
+
+The generated `authProvider.checkError` must distinguish authentication failures from authorization failures:
+
+- `401` -> force logout / re-authentication
+- `403` -> do not re-authenticate; surface access denied / permission error
+
+The generator must not treat `401` and `403` as the same outcome.
+
+---
+
+# Token Handling
+
+The generated frontend must use Keycloak JS token handling with these rules:
+
+1. Use Authorization Code + PKCE (`S256`).
+2. Refresh tokens before protected API calls when needed.
+3. Token refresh must be concurrency-safe:
+   - one shared in-flight refresh operation
+   - no parallel refresh stampede
+4. Do not store access tokens or refresh tokens in `localStorage` or `sessionStorage`.
+
+---
+
 # Type Mapping
 
 | DSL Type | React Admin Component |
@@ -95,4 +144,4 @@ API response must include `id` so React Admin can identify the record:
 
 If the response only had `{ "code": "pump", "name": "Pump" }`, React Admin would not work correctly because it expects `id`. The backend or frontend adapter must therefore set `id: record.code` (or equivalent) when the primary key is not `id`.
 
-This rule ensures compatibility with React Admin resource identity handling.
+This rule ensures compatibility with React Admin resource identity handling.