Skip to content

Commit 55c4c29

Browse files
ddecrulleddecrulle
committed
following up
1 parent 9b15171 commit 55c4c29

14 files changed

Lines changed: 754 additions & 58 deletions

File tree

‎web/CLAUDE.md‎

Lines changed: 108 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,108 @@
1+
# CLAUDE.md
2+
3+
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4+
5+
## Commands
6+
7+
All commands use **Yarn** (not npm).
8+
9+
```bash
10+
yarn dev # Start dev server (processes env YAML first via scripts/unyamlify-env-local.ts)
11+
yarn build # Type-check (tsc) then build for production
12+
yarn test # Run all tests once (Vitest, non-watch)
13+
yarn format # Format all .ts/.tsx/.json/.md files with Prettier
14+
yarn format:check # Check formatting without writing
15+
yarn storybook # Launch Storybook on port 6006
16+
```
17+
18+
**Run a single test file:**
19+
20+
```bash
21+
yarn vitest run src/core/usecases/launcher/decoupledLogic/computeHelmValues.test.ts
22+
```
23+
24+
**Run tests matching a name pattern:**
25+
26+
```bash
27+
yarn vitest run --reporter=verbose -t "pattern"
28+
```
29+
30+
Pre-commit hooks run `eslint --fix` and `prettier --write` via lint-staged.
31+
32+
## Architecture
33+
34+
Onyxia Web is a React SPA — a data science platform portal for launching Kubernetes services (Helm charts), browsing catalogs, managing S3 files, managing Vault secrets, and querying data via DuckDB. It is deployed as static files served by nginx.
35+
36+
### Core principles
37+
38+
- **React is only for rendering.** Business logic is React-agnostic and lives in `src/core/`. The `src/ui/` layer is strictly for React components and hooks.
39+
- **Unidirectional dependencies.** `src/core/` never imports from `src/ui/`, not even for types.
40+
- **Reactive over promise-based.** Thunks update observable state; the UI reacts to state changes. Prefer dispatching actions and reading state over returning values from thunks.
41+
- **Constants outside Redux state.** Values that don't change are not stored in state — they are retrieved from thunks when needed, to avoid unnecessary re-renders.
42+
43+
### `src/core/` — Business logic
44+
45+
Follows a clean-architecture / ports-and-adapters pattern using the `clean-architecture` npm package (a Redux-like store without Redux).
46+
47+
- **`ports/`** — TypeScript interfaces defining contracts for external dependencies (`OnyxiaApi`, `Oidc`, `S3Client`, `SecretsManager`, `SqlOlap`).
48+
- **`adapters/`** — Concrete implementations: `onyxiaApi/` (axios-based HTTP), `oidc/` (oidc-spa), `s3Client/` (AWS SDK v3), `secretManager/` (Vault), `sqlOlap/` (DuckDB WASM). Each adapter has a mock counterpart for dev/testing.
49+
- **`usecases/`** — One folder per feature (20+ total: `catalog`, `launcher`, `serviceManagement`, `fileExplorer`, `secretExplorer`, `dataExplorer`, etc.). Each usecase follows the pattern:
50+
- `state.ts` — state shape + `createUsecaseActions` (slice-like)
51+
- `thunks.ts` — async side effects, accesses adapters via `createUsecaseContextApi`
52+
- `selectors.ts` — memoized state derivations
53+
- `index.ts` — re-exports all three
54+
- **`bootstrap.ts`** — Wires adapters together and creates the core store.
55+
- **`index.ts`** — Exports `useCoreState`, `getCore`, `createReactApi` bindings consumed by `src/ui/`.
56+
57+
**Complex use-cases** (especially `launcher/`) have a `decoupledLogic/` subfolder with pure functions and no framework dependencies — this is where most unit tests live.
58+
59+
### `src/ui/` — React layer
60+
61+
- **`App/`** — Root layout: Header, LeftBar, Main, Footer. `App.tsx` triggers core bootstrap; `Main.tsx` is the route-based page switcher.
62+
- **`pages/`** — One folder per route/page. Each page exports `routeDefs` (via `type-route`'s `defineRoute`) and `routeGroup`. All are merged in `pages/index.ts`.
63+
- **`routes.tsx`** — Router instantiation. Navigation uses `routes.catalog(...).push()` or `session.push()`.
64+
- **`i18n/`** — i18nifty setup. Translation keys are declared at the component level via `declareComponentKeys`, collected into a `ComponentKey` union in `i18n/types.ts`. Nine languages: en, fr, zh-CN, no, fi, nl, it, es, de.
65+
- **`theme/`** — onyxia-ui theme setup (palette, fonts, favicon).
66+
- **`shared/`** — Reusable components (CommandBar, CodeBlock, SettingField, etc.).
67+
68+
### Key patterns
69+
70+
**Consuming core state in React:**
71+
72+
```ts
73+
import { useCoreState, getCore } from "core";
74+
const helmReleases = useCoreState(state => state.serviceManagement.helmReleases);
75+
await getCore().dispatch(usecases.serviceManagement.thunks.initialize());
76+
```
77+
78+
**Styling — tss-react** (not plain CSS modules):
79+
80+
```ts
81+
import { tss } from "tss";
82+
const useStyles = tss.withName({ MyComponent }).create(({ theme }) => ({ ... }));
83+
const { classes, cx } = useStyles();
84+
```
85+
86+
**Absolute imports** — `tsconfig.json` sets `baseUrl: "src"`, so use `import { foo } from "core/usecases/catalog"` (not relative paths).
87+
88+
**Environment variables** — All env vars are centrally parsed and validated in `src/env.ts`. The `index.html` is an EJS template processed by `vite-envs` at build time.
89+
90+
**Authentication** — OIDC init (`oidc-spa`) happens before React renders, in `main.tsx`. Use the `Oidc` port interface, not the adapter directly.
91+
92+
**Plugin system** — `src/pluginSystem.ts` exposes `window.onyxia` after boot and fires an `"onyxiaready"` `CustomEvent`, allowing external JS to interact with core state, routes, theme, and i18n.
93+
94+
**Keycloak theme** — `src/keycloak-theme/` is a Keycloakify login theme that shares env and i18n infrastructure with the main app. Build with `yarn build-keycloak-theme`.
95+
96+
## Key libraries
97+
98+
| Library | Role |
99+
| -------------------- | ------------------------------------------------------------ |
100+
| `onyxia-ui` | In-house design system on top of MUI v6 |
101+
| `type-route` | Strongly-typed client-side router |
102+
| `i18nifty` | Component-level i18n |
103+
| `clean-architecture` | Redux-like store (ports/usecases pattern) |
104+
| `oidc-spa` | OIDC/OAuth2 authentication |
105+
| `keycloakify` | Keycloak login theme from React components |
106+
| `tss-react` | CSS-in-JS bound to onyxia-ui theme |
107+
| `vite-envs` | Env var injection into EJS `index.html` at build time |
108+
| DuckDB WASM | In-browser SQL OLAP queries (`dataExplorer`, `sqlOlapShell`) |

‎web/src/core/usecases/ai/selectors.ts‎

Lines changed: 10 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -29,15 +29,23 @@ const main = createSelector(
2929
return { isEnabled: false as const, initializationStatus };
3030
}
3131

32-
const { webUiUrl, apiBase, token, availableModels, selectedModel } = state;
32+
const {
33+
webUiUrl,
34+
apiBase,
35+
token,
36+
availableModels,
37+
selectedModel,
38+
customProviders
39+
} = state;
3340

3441
return {
3542
isEnabled: true as const,
3643
webUiUrl,
3744
apiBase,
3845
token,
3946
availableModels,
40-
selectedModel
47+
selectedModel,
48+
customProviders
4149
};
4250
}
4351
);

‎web/src/core/usecases/ai/state.ts‎

Lines changed: 62 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,16 @@ import { id } from "tsafe/id";
33

44
export const name = "ai";
55

6+
export type CustomAiProvider = {
7+
id: string;
8+
label: string;
9+
apiBase: string;
10+
apiKey: string;
11+
availableModels: string[];
12+
selectedModel: string | undefined;
13+
modelsFetchStatus: "fetching" | "success" | "error";
14+
};
15+
616
type State = State.Disabled | State.Enabled;
717

818
export declare namespace State {
@@ -18,6 +28,7 @@ export declare namespace State {
1828
token: string | undefined;
1929
availableModels: string[];
2030
selectedModel: string | undefined;
31+
customProviders: CustomAiProvider[];
2132
};
2233
}
2334

@@ -50,18 +61,27 @@ export const { reducer, actions } = createUsecaseActions({
5061
token: string;
5162
availableModels: string[];
5263
selectedModel: string | undefined;
64+
customProviders: CustomAiProvider[];
5365
};
5466
}
5567
) => {
56-
const { webUiUrl, apiBase, token, availableModels, selectedModel } = payload;
68+
const {
69+
webUiUrl,
70+
apiBase,
71+
token,
72+
availableModels,
73+
selectedModel,
74+
customProviders
75+
} = payload;
5776

5877
return id<State.Enabled>({
5978
isEnabled: true,
6079
webUiUrl,
6180
apiBase,
6281
token,
6382
availableModels,
64-
selectedModel: selectedModel ?? availableModels[0]
83+
selectedModel: selectedModel ?? availableModels[0],
84+
customProviders
6585
});
6686
},
6787
tokenRefreshed: (state, { payload }: { payload: { token: string } }) => {
@@ -75,6 +95,46 @@ export const { reducer, actions } = createUsecaseActions({
7595
selectedModelSet: (state, { payload }: { payload: { model: string } }) => {
7696
if (!state.isEnabled) return;
7797
state.selectedModel = payload.model;
98+
},
99+
customProviderAdded: (state, { payload }: { payload: CustomAiProvider }) => {
100+
if (!state.isEnabled) return;
101+
state.customProviders.push(payload);
102+
},
103+
customProviderDeleted: (state, { payload }: { payload: { id: string } }) => {
104+
if (!state.isEnabled) return;
105+
const i = state.customProviders.findIndex(p => p.id === payload.id);
106+
if (i !== -1) state.customProviders.splice(i, 1);
107+
},
108+
customProviderModelsLoaded: (
109+
state,
110+
{ payload }: { payload: { id: string; models: string[] } }
111+
) => {
112+
if (!state.isEnabled) return;
113+
const provider = state.customProviders.find(p => p.id === payload.id);
114+
if (provider === undefined) return;
115+
provider.availableModels = payload.models;
116+
provider.modelsFetchStatus = "success";
117+
if (provider.selectedModel === undefined && payload.models.length > 0) {
118+
provider.selectedModel = payload.models[0];
119+
}
120+
},
121+
customProviderModelsFetchFailed: (
122+
state,
123+
{ payload }: { payload: { id: string } }
124+
) => {
125+
if (!state.isEnabled) return;
126+
const provider = state.customProviders.find(p => p.id === payload.id);
127+
if (provider === undefined) return;
128+
provider.modelsFetchStatus = "error";
129+
},
130+
customProviderSelectedModelSet: (
131+
state,
132+
{ payload }: { payload: { id: string; model: string } }
133+
) => {
134+
if (!state.isEnabled) return;
135+
const provider = state.customProviders.find(p => p.id === payload.id);
136+
if (provider === undefined) return;
137+
provider.selectedModel = payload.model;
78138
}
79139
}
80140
});

0 commit comments

Comments
 (0)