139 lines
3.9 KiB
Markdown
139 lines
3.9 KiB
Markdown
# Frontend Generation Process
|
|
|
|
Frontend generation must produce the React Admin CRUD application **and** the default Keycloak integration required by the runtime architecture.
|
|
|
|
Follow:
|
|
|
|
- `frontend/architecture.md`
|
|
- `frontend/react-admin-rules.md`
|
|
- `auth/keycloak-architecture.md`
|
|
- `auth/frontend-auth-rules.md`
|
|
- `auth/keycloak-realm-template-rules.md`
|
|
|
|
---
|
|
|
|
# Step 1 — Parse DSL
|
|
|
|
Extract:
|
|
|
|
- entities
|
|
- attributes
|
|
- relation fields required for reference inputs and reference displays
|
|
|
|
The generator must treat auth as default frontend infrastructure rather than as an optional feature.
|
|
|
|
---
|
|
|
|
# Step 2 — Generate frontend runtime structure
|
|
|
|
Generate the base frontend structure required by the proven runtime:
|
|
|
|
- `client/src/main.tsx`
|
|
- `client/src/App.tsx`
|
|
- `client/src/dataProvider.ts`
|
|
- `client/src/config/env.ts`
|
|
- `client/src/auth/keycloak.ts`
|
|
- `client/src/auth/authProvider.ts`
|
|
- `client/.env.example`
|
|
|
|
The generated frontend must:
|
|
|
|
- initialize Keycloak before rendering the SPA
|
|
- register React Admin with a mandatory `authProvider`
|
|
- enforce authenticated operation rather than anonymous operation
|
|
- use environment-driven runtime config and fail fast when required auth vars are missing
|
|
|
|
---
|
|
|
|
# Step 3 — Generate React Admin resources
|
|
|
|
For each entity create:
|
|
|
|
- `EntityList.tsx`
|
|
- `EntityCreate.tsx`
|
|
- `EntityEdit.tsx`
|
|
- `EntityShow.tsx`
|
|
|
|
Resource generation must remain compatible with the auth-aware shared request seam.
|
|
|
|
---
|
|
|
|
# Step 4 — Map fields
|
|
|
|
Map DSL attributes to React Admin components according to existing field rules and relation semantics.
|
|
|
|
Reference/resource lookups must continue to flow through the same shared authenticated request layer used by the main CRUD resources.
|
|
|
|
---
|
|
|
|
# Step 5 — Generate auth-aware API layer
|
|
|
|
Generate a shared `dataProvider.ts` that:
|
|
|
|
- reads the API base URL from `VITE_API_URL`
|
|
- attaches `Authorization: Bearer <access_token>` to every backend request
|
|
- uses the same request seam for all React Admin operations, including:
|
|
- list
|
|
- get one
|
|
- get many
|
|
- get many reference
|
|
- create
|
|
- update
|
|
- delete
|
|
- handles token refresh before protected requests
|
|
- keeps token refresh concurrency-safe by sharing one in-flight refresh operation
|
|
- does not store access tokens or refresh tokens in `localStorage` or `sessionStorage`
|
|
|
|
The generator must not create multiple competing HTTP clients for authenticated and unauthenticated traffic. The shared request seam is the single bearer injection point.
|
|
|
|
---
|
|
|
|
# Step 6 — Generate frontend auth flow
|
|
|
|
Generate Keycloak frontend integration with these required rules:
|
|
|
|
- use `keycloak-js`
|
|
- redirect-based login only
|
|
- no custom in-app username/password login form
|
|
- Authorization Code + PKCE with `S256`
|
|
- initialize Keycloak before React render
|
|
- provide a React Admin `authProvider`
|
|
- distinguish auth failures from authorization failures:
|
|
- `401` -> force logout / re-authentication
|
|
- `403` -> do not re-authenticate; surface access denied / permission error
|
|
|
|
The generator must not silently fall back to production auth settings in code. Example values belong in `.env.example`, but runtime config must fail fast if required values are absent.
|
|
|
|
---
|
|
|
|
# Step 7 — Register resources and auth
|
|
|
|
Register resources in `App.tsx` and wire them into an authenticated `Admin` root.
|
|
|
|
Generated `App.tsx` must:
|
|
|
|
- register the shared `dataProvider`
|
|
- register the mandatory `authProvider`
|
|
- configure the app so it does not operate anonymously once auth is enabled
|
|
|
|
Example shape:
|
|
|
|
```tsx
|
|
<Admin dataProvider={dataProvider} authProvider={authProvider}>
|
|
<Resource name="equipment" ... />
|
|
</Admin>
|
|
```
|
|
|
|
---
|
|
|
|
# Step 8 — Frontend runtime config
|
|
|
|
Generate frontend env examples and config access for:
|
|
|
|
- `VITE_API_URL`
|
|
- `VITE_KEYCLOAK_URL`
|
|
- `VITE_KEYCLOAK_REALM`
|
|
- `VITE_KEYCLOAK_CLIENT_ID`
|
|
|
|
`client/.env.example` must use filled example values that match the documented Keycloak and local dev topology, while runtime code must fail fast if any required variable is missing.
|