|
| 1 | +--- |
| 2 | +description: Conventions for distribution variants — base app shell, core-bff, and rhaii |
| 3 | +globs: "distributions/**" |
| 4 | +alwaysApply: false |
| 5 | +paths: |
| 6 | + - "distributions/**" |
| 7 | +--- |
| 8 | + |
| 9 | +# Distribution Conventions |
| 10 | + |
| 11 | +Distributions are independently-deployable dashboard variants in `distributions/`. They are NOT part of the npm workspace or Turbo pipeline — monorepo-wide `npm run` commands do not apply. |
| 12 | + |
| 13 | +## Sub-distributions |
| 14 | + |
| 15 | +| Directory | Type | Has BFF? | Build | |
| 16 | +|-----------|------|----------|-------| |
| 17 | +| `base/` | Shared app shell library (PatternFly chrome, no features) — **not deployed on its own** | Stub only | `npm run build` | |
| 18 | +| `core-bff/` | Full Go BFF + React frontend for sidecar/xKC deployments | Yes (Go 1.25+) | `make build` | |
| 19 | +| `rhaii/` | RHAII-specific distribution | No | `npm run build` | |
| 20 | + |
| 21 | +> **`base/` is a library, not a deployable distribution.** It provides the shared app shell framework (masthead, sidebar, error boundary, theme context, extensibility hooks) that concrete distributions like `core-bff/` and `rhaii/` extend. Do not treat it as a standalone application. |
| 22 | +
|
| 23 | +## Isolation from npm workspaces |
| 24 | + |
| 25 | +Distributions are self-contained. Always `cd` into the distribution directory before running commands: |
| 26 | + |
| 27 | +```bash |
| 28 | +# WRONG — distributions are invisible to the root workspace |
| 29 | +npm run lint # won't touch distributions/ |
| 30 | +npm run type-check # won't touch distributions/ |
| 31 | + |
| 32 | +# RIGHT — run from within the distribution |
| 33 | +cd distributions/base && npx eslint src/ |
| 34 | +cd distributions/core-bff && make lint |
| 35 | +``` |
| 36 | + |
| 37 | +## Build and dev commands |
| 38 | + |
| 39 | +### `base/` (shared library) and `rhaii/` (frontend-only) |
| 40 | + |
| 41 | +`base/` is a library — run these commands for development and testing, not for standalone deployment. `rhaii/` is a deployable distribution that extends `base/`. |
| 42 | + |
| 43 | +```bash |
| 44 | +npm run build # Webpack production build |
| 45 | +npm run start:dev # Webpack dev server (local development/testing only for base/) |
| 46 | +npx eslint src/ # Lint |
| 47 | +npx tsc --noEmit # Type-check |
| 48 | +``` |
| 49 | + |
| 50 | +### `core-bff/` (Go BFF + React frontend) |
| 51 | + |
| 52 | +```bash |
| 53 | +make dev-start # Start both BFF and frontend in dev mode (mocked) |
| 54 | +make dev-bff # BFF only on port 4000 |
| 55 | +make dev-frontend # Frontend dev server only |
| 56 | +make build # Build BFF + frontend |
| 57 | +make dev-start-federated # Start in federated mode |
| 58 | +``` |
| 59 | + |
| 60 | +#### BFF commands (from `bff/`) |
| 61 | + |
| 62 | +```bash |
| 63 | +make run # Run BFF |
| 64 | +make lint # golangci-lint |
| 65 | +make test # Go tests |
| 66 | +make build # Build binary |
| 67 | +``` |
| 68 | + |
| 69 | +#### Frontend commands (from `frontend/`) |
| 70 | + |
| 71 | +```bash |
| 72 | +npm run test # Full suite (lint + type-check + unit + cypress) |
| 73 | +npm run test:lint # Lint only |
| 74 | +npm run test:type-check # TypeScript check |
| 75 | +npm run test:unit # Jest unit tests |
| 76 | +npm run test:cypress-ci # Cypress headless |
| 77 | +``` |
| 78 | + |
| 79 | +#### Contract tests |
| 80 | + |
| 81 | +```bash |
| 82 | +npm run test:contract # Both platforms |
| 83 | +npm run test:contract:openshift # Foundation + OpenShift tests |
| 84 | +npm run test:contract:xks # Foundation + XKS tests |
| 85 | +``` |
| 86 | + |
| 87 | +## Module Federation |
| 88 | + |
| 89 | +`base/` and `rhaii/` are Module Federation **hosts** — they load federated remotes at runtime. Webpack configs in `config/` define the host setup. `core-bff/frontend/` also supports federated mode via `config/moduleFederation.js`. |
| 90 | + |
| 91 | +When modifying Module Federation config in distributions, verify that remote names and shared dependencies stay consistent with the host dashboard's expectations. |
| 92 | + |
| 93 | +## core-bff contract-first workflow |
| 94 | + |
| 95 | +`core-bff/` follows a mandatory 4-stage development flow. See `core-bff/AGENTS.md` for full details: |
| 96 | + |
| 97 | +1. **Contract first** — Update OpenAPI spec in `bff/openapi/src/core-bff.yaml` |
| 98 | +2. **BFF stub second** — Implement handlers in `bff/internal/api/` |
| 99 | +3. **Frontend third** — Build UI in `frontend/src/app/` |
| 100 | +4. **Production BFF last** — Replace mocks with real Kubernetes logic |
| 101 | + |
| 102 | +## core-bff deployment modes |
| 103 | + |
| 104 | +| Mode | Description | BFF Port | Frontend Port | |
| 105 | +|------|-------------|----------|---------------| |
| 106 | +| `standalone` | UI served by BFF, isolated deployment | 4000 | 4000 (static) | |
| 107 | +| `federated` | Micro-frontend loaded by host dashboard | 8082 | 9112 (dev) / 8843 (prod) | |
| 108 | + |
| 109 | +## Common mistakes |
| 110 | + |
| 111 | +- **Running `npm install` from a distribution directory without the workspace workaround** — dependencies on internal packages (`@odh-dashboard/eslint-config`, `@odh-dashboard/tsconfig`) won't resolve. See `distributions/base/README.md` for the workaround. |
| 112 | +- **Confusing `core-bff/bff/` with `dashboard-operator/`** — They are separate Go modules with different `go.mod` files and different patterns. `core-bff/bff/` is an HTTP BFF (uses httprouter); `dashboard-operator/` is a Kubernetes controller (uses controller-runtime). |
| 113 | +- **Assuming monorepo-wide lint/test commands cover distributions** — They don't. Always run validation from within the distribution directory. |
| 114 | +- **Forgetting to update the OpenAPI spec** when adding new endpoints to `core-bff/bff/` — Reviewers must see a diff in the OpenAPI file alongside code changes. |
0 commit comments