This document provides guidance for AI agents working on the Open Data Hub (ODH) Dashboard monorepo.
ODH Dashboard is a monorepo containing the main dashboard application and multiple feature packages. It provides the web UI for Red Hat OpenShift AI (RHOAI) and Open Data Hub.
odh-dashboard/
├── frontend/ # Main dashboard frontend application
│ └── src/
│ └── __mocks__/ # Shared mock data (@odh-dashboard/internal/__mocks__)
├── backend/ # Main dashboard backend (Node.js/Express)
│ └── src/
├── dashboard-operator/ # Dashboard Module Controller (Go, controller-runtime)
│ ├── api/v1alpha1/ # CRD types (Dashboard kind)
│ ├── cmd/manager/ # Controller entry point
│ ├── internal/controller/ # Reconciler, actions, support utilities
│ └── config/ # Generated CRD, RBAC, manager manifests
├── distributions/ # Independently-deployable dashboard variants
│ ├── base/ # Shared app shell library (not deployed on its own)
│ ├── core-bff/ # Full Go BFF + React frontend (has BFF)
│ └── rhaii/ # RHAII-specific distribution (frontend-only)
├── packages/ # Feature packages
│ ├── cypress/ # Cypress test framework and shared tests
│ ├── gen-ai/ # Gen AI / LLM features (has BFF)
│ ├── maas/ # Mod Arch starter (has BFF)
│ ├── model-registry/ # Model Registry UI (has BFF)
│ ├── model-serving/ # Model Serving UI
│ └── ... # Other packages
├── .github/ # GitHub workflows and templates
├── .tekton/ # Tekton CI/CD pipelines
└── docs/ # Documentation
- Node.js: >= 22.0.0
- npm: >= 10.0.0
- Go: >= 1.26 (for packages with BFF), >= 1.25 (for dashboard-operator)
| Technology | Purpose |
|---|---|
| React 18 | Frontend framework |
| TypeScript | Type safety |
| PatternFly v6 | Primary UI component library (RHOAI/ODH) |
| Material UI | Secondary UI library (Kubeflow mode) |
| Webpack | Build tooling with Module Federation |
| Cypress | E2E and component testing |
| Jest | Unit testing |
| Turbo | Monorepo task runner |
# Install dependencies
npm install
# Start development server (main dashboard)
npm run dev
# Build all packages
npm run build
# Run tests
npm run test
# Lint all packages
npm run lint
npm run lint:fix
# Type checking
npm run type-checkBOOKMARKS.md indexes key documentation for frontend areas, the backend, and packages. Review relevant docs for the area you are working on before starting a task.
Multi-Agent Workflows covers running parallel agent sessions locally (git worktrees, Agent Teams, terminal layout) and remotely (Ambient platform).
Some packages have their own AGENTS.md with package-specific guidance. Check the package directory for its own AGENTS.md file.
Before performing certain tasks, read and follow the corresponding specialized rules.
Rules live in .claude/rules/. Read the relevant rule file before starting the task.
| Rule | File | Trigger |
|---|---|---|
| Architecture | architecture.md |
When making structural changes, adding packages, modifying package boundaries, or working on distributions |
| BFF Go | bff-go.md |
When working on Go BFF code in packages/*/bff/ or distributions/core-bff/bff/ |
| Contract Tests | contract-tests.md |
When working on contract tests or BFF API validation |
| Conventions | conventions.md |
When writing or reviewing TypeScript, React, or backend code |
| CSS & PatternFly | css-patternfly.md |
When writing or modifying styles, SCSS, or PatternFly components |
| Distributions | distributions.md |
When working on code in distributions/ |
| Cypress E2E Tests | cypress-e2e.md |
When creating or modifying E2E tests, Robot Framework migrations |
| Cypress Mock Tests | cypress-mock.md |
When creating or modifying mock/component tests |
| Jira Creation | jira-creation.md |
When asked to create Jira issues, tickets, bugs, stories, tasks, or epics |
| Modular Architecture | modular-architecture.md |
When working on the plugin/extension system or package integration |
| Module Federation | module-federation.md |
When configuring Module Federation, webpack remotes, or shared dependencies |
| Module Onboarding | module-onboarding.md |
When creating a new package/module in the monorepo |
| Operator Controller | operator-controller.md |
When working on Go operator/controller-runtime code in dashboard-operator/ |
| Pull Requests | pull-requests.md |
When creating a pull request — must follow .github/pull_request_template.md |
| React | react.md |
When writing React components, hooks, or pages |
| Security | security.md |
When working on auth, secrets, input validation, or K8s API interactions |
| Testing Standards | testing-standards.md |
When working across multiple test types or choosing a testing strategy |
| Third-Party Theming | third-party-theming.md |
When theming external libraries (Perses, MLflow, etc.) or mapping PF tokens into non-PF component systems |
| Prototype Fork Ops | prototype-fork-ops.md |
When running /prototype-spec or /prototype-tickets — shared fork clone, upstream detection, and Jira error handling |
| Unit Tests | unit-tests.md |
When creating or modifying Jest unit tests for utilities, hooks, or components |
Skills provide multi-step workflows. They live in .claude/skills/. Read the relevant skill file before starting the task.
| Skill | Directory | Use when |
|---|---|---|
| Dev Workflow | skills/dev-workflow/ |
Implementing a feature, fix, or refactor — runs lint, type-check, tests, and optional browser verification |
| Docs Create | skills/docs-create/ |
Creating a new documentation file from a description |
| Docs Create Package | skills/docs-create-package/ |
Scaffolding a package doc and registering it in BOOKMARKS.md |
| Docs Update | skills/docs-update/ |
Updating existing docs after code changes |
| Upstream Sync Status | skills/upstream-sync-status/ |
Checking whether a package's upstream copy is up to date (pass package name or be prompted) |
| Upstream Sync | skills/upstream-sync/ |
Syncing upstream changes for a package and opening a PR (pass package name or be prompted) |
| Upstream Sync Local | skills/upstream-sync-local/ |
Syncing upstream changes from a local repository clone (pass package name, local repo path, and branch) |
| Style Review | skills/style-review/ |
Reviewing code for PF priority-order compliance, wrapper component usage, and class naming conventions per css-patternfly.md |
| RBAC Review | skills/rbac-review/ |
Reviewing code for proper RBAC enforcement — catches missing SSAR gates, assumed access from isAdmin, and pages that break for limited-access users |
| Jira Triage | skills/jira-triage/ |
Fetching Jira issues by filter criteria, running full triage on New issues (orchestrates all analysis skills), defining triage operations, and bulk-applying them |
| Jira Validate Priority/Severity | skills/jira-validate-priority-severity/ |
Analyzing bugs for missing or incorrect severity and priority fields |
| Jira Validate Description | skills/jira-validate-description/ |
Validating issue descriptions for completeness per type, requesting missing information from reporters |
| Jira Evaluate Blockers | skills/jira-evaluate-blockers/ |
Applying needs-* labels and blocking state during triage, or evaluating whether existing blockers have been resolved |
| Jira Validate Issue Type | skills/jira-validate-issue-type/ |
Validating or correcting issue types (Bug, Story, Task) and labeling feature requests |
| Jira Validate Area Label | skills/jira-validate-area-label/ |
Validating or assigning dashboard-area-* labels based on multi-signal content analysis |
| Jira Assign Scrum Team | skills/jira-assign-scrum-team/ |
Assigning a scrum team label based on area-to-scrum mapping during triage |
| Jira Eval Review | skills/jira-eval-review/ |
Evaluating PR code changes against Jira acceptance criteria for per-criterion verdicts |
| Module Onboarding | skills/module-onboarding/ |
Scaffolding a new federated module under packages/ — handles installer, port allocation, host registration, and build verification (pass module name as argument) |
| Konflux Onboarding | skills/konflux-onboarding/ |
Onboarding a component to Konflux CI/CD — Dockerfiles, Tekton pipelines, DevOps coordination, RHOAI downstream setup |
| Prototype Spec | skills/prototype-spec/ |
Extracting PF component details from a UX prototype fork, scoped to a Jira ticket or epic |
| Prototype Tickets | skills/prototype-tickets/ |
Drafting Jira tickets from a UX prototype fork — splits by feature area, generates ACs from prototype scenarios |
| CI Flake Classifier | skills/ci-flake-classifier/ |
Classifying PR CI failures as flaky or genuine — cross-PR recurrence, rerun detection, symptom matching (also used by preflight) |
Important: Always read the relevant rule or skill file before starting the task to ensure you follow the project's conventions and patterns.