# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

NetFoundry UI — an enterprise Angular 20 monorepo managed with Nx 21. Contains three apps (`nfconsole`, `cloud-ziti`, `zeds`) and 200+ libraries under `libs/`. Uses Auth0 for authentication, NGXS for state management, Angular Material + PrimeNG for UI, and Highcharts/D3 for data visualization.

Note: the dev-server (`@angular-devkit/build-angular:dev-server`) is Vite-backed in Angular 17+, even when the `build` target still uses the legacy `:browser` executor. Host-header checks, HMR, and allowed-hosts config follow Vite's rules.

## Common Commands

All commands use `node --max_old_space_size` wrappers. Use `npm run` or call `nx` directly.

```bash
# Dev server (uses --max_old_space_size=12288 for heap)
npm start                    # Serves nfconsole (default app)
npm start -- --project=cloud-ziti   # Serves cloud-ziti app

# Build
npm run build                # Dev build of nfconsole
npm run build-prod           # Production build with AOT

# Test (affected projects vs develop branch)
npm test                     # Affected tests (--runInBand)
npm run coverage             # All tests with coverage

# Test a single library
npx nx test <project-name>   # e.g. npx nx test feature-data-table
npx nx test <project-name> --watch   # Watch mode

# Lint
npm run lint                 # Affected lint
npm run fixlint              # Affected lint with --fix
npx nx lint <project-name>   # Lint single project

# E2E
npm run nfconsole:e2e        # Cypress E2E for nfconsole
npm run zeds:e2e             # Cypress E2E for zeds

# Nx utilities
npx nx dep-graph             # Visualize dependency graph
npx nx affected:apps --base origin/develop   # List affected apps
```

## Architecture

### Monorepo Library Structure

Libraries live in `libs/` with enforced dependency constraints (via `@nx/enforce-module-boundaries` in `.eslintrc.json`):

| Scope | Can Depend On | Purpose |
|-------|--------------|---------|
| `page` | page, feature, shared, ui, util | Routable pages (lazy-loaded) |
| `feature` | feature, shared, ui, util | Business logic, smart components, forms |
| `shared` | shared, ui, util | Cross-cutting Angular services/modules |
| `ui` | ui, shared, util | Presentational components (inputs only, no injected services) |
| `util` | util only | Framework-agnostic pure functions |
| `data-access` | util only | API client layers, state management |

### Import Paths

All libraries use `@netfoundry-ui/*` path aliases defined in `tsconfig.base.json` (200+ mappings). Example: `@netfoundry-ui/feature/data-table`.

### Key Libraries

- **`libs/shared/apiv2/`** — V2 API service clients
- **`libs/shared/model/`** — Data models (80+ files, V2 subdirectory)
- **`libs/shared/authorization/`** — Auth0/OIDC guards and login
- **`libs/shared/services/`** — Core services (API, URL, Azure, etc.)
- **`libs/feature/form/`** — 50+ entity form components
- **`libs/feature/data-table/`** — Reusable data table component
- **`libs/page/`** — All routable page modules

### App Routing

- **nfconsole**: `apps/nfconsole/src/app/app-routing.module.ts` — routes prefixed with `/v7/`, lazy-loaded with `AuthenticationGuard` and `AuthorizationResolveService`.
- **cloud-ziti**: `apps/cloud-ziti/src/app/app-routing.module.ts` — routes organized by sub-app (see below).

### Cloud-Ziti Sub-Applications

The cloud-ziti app contains multiple sub-applications, each with its own sidebar navigation, routes, and page libraries. Sub-apps are:

| Sub-App | Route Prefix | Example Pages |
|---------|-------------|---------------|
| **Network** | `/network/`, `/identities`, `/services` | Dashboard, Identities, Services, Edge Routers, Policies |
| **Organization** | `/organizations`, `/user-identities/` | Org Settings, Users, Roles, API Tokens, Invitations |
| **Frontdoor** | `/frontdoor/` | Shares, Agents, Frontends, Authentication, Certificates, Metrics |
| **Billing** | `/billing/` | Dashboard, Payment Profile, Subscriptions, Invoices, Usage |
| **Support** | `/support/` | Help resources |

**Key files for sub-app wiring:**

1. **Routes** — `apps/cloud-ziti/src/app/app-routing.module.ts` — lazy-loaded routes per page
2. **Sidebar navigation** — `libs/feature/navigator/src/lib/side-navigator/side-navigator.service.ts` — each sub-app has a navigator constant (e.g., `FRONTDOOR_NAVIGATOR`) defining menu groups and items
3. **URL constants** — `libs/shared/services/src/lib/urls.ts` — all route paths as named constants (e.g., `URLS.FRONTDOOR_AGENTS`)

**Adding a new page to a sub-app (e.g., Frontdoor):**

1. **Create page library**: `nx g lib page/my-new-page` — produces `libs/page/my-new-page/` with component, routing module, and page module
2. **Add route** in `apps/cloud-ziti/src/app/app-routing.module.ts`:
   ```typescript
   { path: 'frontdoor/my-new-page',
     loadChildren: () => import('@netfoundry-ui/page/my-new-page').then((m) => m.PageMyNewPageModule) }
   ```
3. **Add URL constant** in `libs/shared/services/src/lib/urls.ts`:
   ```typescript
   FRONTDOOR_MY_NEW_PAGE: '/frontdoor/my-new-page',
   ```
4. **Add menu item** to the sub-app's navigator in `side-navigator.service.ts`:
   ```typescript
   { label: 'My New Page', route: URLS.FRONTDOOR_MY_NEW_PAGE, iconClass: 'icon-Something',
     selectedRoutes: [URLS.FRONTDOOR_MY_NEW_PAGE] }
   ```
5. **Add path alias** in `tsconfig.base.json` (if not auto-generated by `nx g`):
   ```json
   "@netfoundry-ui/page/my-new-page": ["libs/page/my-new-page/src/index.ts"]
   ```

### Generating New Libraries

```bash
nx g lib feature/mylib       # New feature library
nx g lib shared/mylib        # New shared library
nx g component my-component --project=feature-mylib   # Component in existing lib
```

Look up project names in `angular.json` if unsure of the slug.

## Code Style

- **Prettier**: 4-space indent, single quotes, semicolons, 120 char line width, ES5 trailing commas
- **Component selectors**: `app-` prefix, kebab-case (`@angular-eslint/component-selector`)
- **Directive selectors**: `app` prefix, camelCase (`@angular-eslint/directive-selector`)
- **TypeScript**: `@typescript-eslint/no-explicit-any` is off; `prefer-const` and `eqeqeq` (smart) are enforced
- **Imports**: `rxjs/Rx` is restricted; `import/order` is warned

## Environment Configs

14 environment variants in `apps/nfconsole/src/environments/` including production, staging, sandbox, integration, and Siemens-branded variants. The `version.ts` file is auto-generated by `version.js` at postinstall.

## CI/CD

Jenkins pipelines in `jenkinsfiles/`. Docker build image: `netfoundry/netfoundry-ui-build`. Build output: `dist/apps/nfconsole`.