From: Fiete Ostkamp Date: Mon, 9 Mar 2026 06:45:09 +0000 (+0100) Subject: Add READMEs for cds-ui X-Git-Url: https://gerrit.onap.org/r/gitweb?a=commitdiff_plain;h=1fcf34b08beadbda9ed3b5e30fe2751117ea528e;p=ccsdk%2Fcds.git Add READMEs for cds-ui - add readme's for cds-ui modules (client, designer-client, cds-ui root folder) Issue-ID: CCSDK-4180 Change-Id: I36837bbd64700e2f64a8718ec6f015de3d94f31f Signed-off-by: Fiete Ostkamp --- diff --git a/cds-ui/README.md b/cds-ui/README.md new file mode 100644 index 000000000..cc2ac0969 --- /dev/null +++ b/cds-ui/README.md @@ -0,0 +1,123 @@ +# CDS UI + +The **CDS UI** module provides the full-stack web interface for the ONAP **Controller Design Studio (CDS)**. It consists of two Angular front-end applications, a LoopBack 4 backend-for-frontend (BFF) server, a Docker packaging layer, and an end-to-end test suite. + +## Module Structure + +``` +cds-ui/ +├── client/ # Legacy Angular 7 frontend +├── designer-client/ # Modernized Angular 8 frontend +├── server/ # LoopBack 4 BFF server (Node.js) +├── application/ # Docker container assembly +├── common/ # Shared models/resources between server and client +└── e2e-playwright/ # Playwright end-to-end tests +``` + +| Module | Description | +| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | +| **client** | Original Angular 7.1 UI with NgRx state management, blueprint designer, resource definitions, and controller catalog | +| **designer-client** | Modernized Angular 8.2 UI with simplified store pattern, package dashboard, multi-step creation wizard, and resource dictionary management | +| **server** | LoopBack 4 intermediary that serves the built Angular apps as static files and proxies REST/gRPC requests to the CDS Blueprints Processor | +| **application** | Multi-stage Dockerfile that builds client + server into the `onap/ccsdk-cds-ui` container image | +| **common** | Shared TypeScript models and resources used by both server and client | +| **e2e-playwright** | Playwright tests with a mock processor, enabling full E2E testing without external ONAP infrastructure | + +## Architecture + +``` +┌──────────────────────────────────────────────────────────┐ +│ Docker Container (onap/ccsdk-cds-ui) — port 3000 │ +│ │ +│ LoopBack 4 Server │ +│ ├── Static files: designer-client build (/) & client │ +│ ├── REST proxy: /controllerblueprint/*, /resource... │ +│ └── gRPC client: blueprint-proto communication │ +│ │ │ +└───────────────────────────┼──────────────────────────────┘ + ▼ + CDS Blueprints Processor (port 8080) +``` + +During development, the Angular dev servers (port 4200) proxy API requests to the LoopBack server (port 3000), which in turn forwards them to the Blueprints Processor backend (port 8080). + +## Prerequisites + +- **Java 11+** and **Maven 3.6+** (for the full Maven build) +- **Node.js** — managed per module by `frontend-maven-plugin` (client: 8.12, designer-client: 13.7, server: 16.14) +- A running **CDS Blueprints Processor** at `localhost:8080` (or use the mock processor for testing) + +## Building + +### Full Maven Build + +From the repository root: + +```bash +mvn clean install -pl cds-ui -amd +``` + +This builds all four Maven modules in order: client → designer-client → server → application. + +### Local Development Build + +To skip linting and use a faster local build for the designer-client: + +```bash +mvn clean install -pl cds-ui -amd -DnpmLocal +``` + +### Individual Modules + +```bash +# Build only the designer-client +mvn clean install -pl cds-ui/designer-client + +# Build only the server +mvn clean install -pl cds-ui/server +``` + +### Docker Image + +The application module produces the `onap/ccsdk-cds-ui` Docker image via a multi-stage build: + +1. **Stage 0** — Builds the Angular client +2. **Stage 1** — Builds the LoopBack server +3. **Final** — Combines built assets and starts the server on port 3000 + +## Development + +### Designer-Client (Recommended) + +```bash +cd designer-client +npm install +npm start # Lints, starts dev server at http://localhost:4200 +``` + +### Server + +```bash +cd server +npm install +npm run build +npm start # Starts LoopBack server at https://localhost:3000 +``` + +### Running E2E Tests + +The Playwright test suite runs against a mock processor, requiring no external services: + +```bash +cd e2e-playwright +npm install +npm test # Starts mock-processor + server + Angular, runs tests +``` + +See [e2e-playwright/README.md](e2e-playwright/README.md) for details on headed mode, UI mode, and the mock processor. + +## License + +Copyright (C) 2018 IBM Intellectual Property. All rights reserved. + +Licensed under the Apache License, Version 2.0. See the [LICENSE](http://www.apache.org/licenses/LICENSE-2.0) for details. diff --git a/cds-ui/client/README.md b/cds-ui/client/README.md index 8af87484d..97f819d88 100644 --- a/cds-ui/client/README.md +++ b/cds-ui/client/README.md @@ -1,48 +1,101 @@ -/* -============LICENSE_START========================================== -=================================================================== -Copyright (C) 2018 IBM Intellectual Property. All rights reserved. -=================================================================== +# CDS UI Client + +The **CDS UI Client** is the web-based front-end for the ONAP **Controller Design Studio (CDS)**. It provides a graphical interface for designing, managing, deploying, and testing service blueprints used in network automation. + +## Key Features + +- **Blueprint Designer** — Visual drag-and-drop blueprint design powered by JointJS +- **Blueprint Management** — Upload, modify, deploy, and test service blueprint packages (CBA) +- **Resource Definitions** — Create and manage resource definitions for services +- **Controller Catalog** — Browse and manage available controller functions +- **Integrated Code Editor** — Ace Editor with syntax highlighting for JSON, Python, XML, YAML, Kotlin, and Velocity templates +- **JSON Schema Editor** — Built-in JSON editor for blueprint and resource configurations + +## Technology Stack + +| Layer | Technology | +| ---------------- | ----------------------------------- | +| Framework | Angular 7.1 | +| State Management | NgRx (Store, Effects, Router Store) | +| UI Components | Angular Material 7.1, Bootstrap 4.3 | +| Diagramming | JointJS 3.0 | +| Code Editing | Ace Editor (ng2-ace-editor) | +| Package Handling | JSZip | +| Testing | Karma + Jasmine, Protractor (E2E) | -Unless otherwise specified, all software contained herein is licensed -under the Apache License, Version 2.0 (the License); -you may not use this software except in compliance with the License. -You may obtain a copy of the License at +## Prerequisites - http://www.apache.org/licenses/LICENSE-2.0 +- **Node.js** 8.9 or later +- **npm** 6.x +- **Angular CLI** 7.1 (`npm install -g @angular/cli@7.1`) +- A running **CDS Blueprints Processor** backend (default: `localhost:8080`) -Unless required by applicable law or agreed to in writing, software -distributed under the License is distributed on an "AS IS" BASIS, -WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -See the License for the specific language governing permissions and -limitations under the License. -============LICENSE_END============================================ -*/ +## Getting Started -# CdsUi +```bash +# Install dependencies +npm install -This project was generated with [Angular CLI](https://github.com/angular/angular-cli) version 7.1.0. +# Start the development server (http://localhost:4200) +npm start +``` -## Development server +The app proxies API requests through the LoopBack 4 server located in `../server/`, which forwards them to the CDS Blueprints Processor backend. -Run `ng serve` for a dev server. Navigate to `http://localhost:4200/`. The app will automatically reload if you change any of the source files. +## Available Scripts -## Code scaffolding +| Command | Description | +| --------------- | ---------------------------------------------------------- | +| `npm start` | Start the Angular dev server on port 4200 with live reload | +| `npm run build` | Build the app (output: `../server/public`) | +| `npm test` | Run unit tests via Karma | +| `npm run lint` | Lint the project with TSLint | +| `npm run e2e` | Run end-to-end tests via Protractor | -Run `ng generate component component-name` to generate a new component. You can also use `ng generate directive|pipe|service|class|guard|interface|enum|module`. +For a production build: -## Build +```bash +ng build --prod +``` -Run `ng build` to build the project. The build artifacts will be stored in the `dist/` directory. Use the `--prod` flag for a production build. +## Project Structure -## Running unit tests +``` +src/app/ +├── feature-modules/ +│ ├── blueprint/ # Blueprint CRUD (select, modify, deploy, test) +│ ├── blueprint-designer/ # Visual blueprint designer (JointJS) +│ ├── controller-catalog/ # Controller catalog management +│ └── resource-definition/ # Resource creation and editing +├── common/ +│ ├── constants/ # App-wide constants +│ ├── core/ # Core services and HTTP interceptors +│ ├── modules/ # Shared Angular modules +│ ├── shared/ # Shared components +│ └── utility/ # Utility functions +├── app.module.ts # Root module +└── app-routing.module.ts # Lazy-loaded feature routes +``` -Run `ng test` to execute the unit tests via [Karma](https://karma-runner.github.io). +## Architecture -## Running end-to-end tests +``` +Angular Client ──► LoopBack 4 Server (../server) ──► CDS Blueprints Processor + (port 4200) (intermediary) (port 8080) +``` -Run `ng e2e` to execute the end-to-end tests via [Protractor](http://www.protractortest.org/). +The Angular client communicates with a LoopBack 4 REST server that acts as a gateway to the CDS backend microservices. The built Angular assets are served as static files from the LoopBack server in production. -## Further help +## Building with Maven + +This module is part of the larger ONAP CDS Maven build. From the repository root: + +```bash +mvn clean install -pl cds-ui/client +``` + +## License + +Copyright (C) 2018 IBM Intellectual Property. All rights reserved. -To get more help on the Angular CLI use `ng help` or go check out the [Angular CLI README](https://github.com/angular/angular-cli/blob/master/README.md). +Licensed under the Apache License, Version 2.0. See the [LICENSE](http://www.apache.org/licenses/LICENSE-2.0) for details. diff --git a/cds-ui/designer-client/README.md b/cds-ui/designer-client/README.md index 444e36963..24e89eb59 100644 --- a/cds-ui/designer-client/README.md +++ b/cds-ui/designer-client/README.md @@ -1,27 +1,126 @@ -# designer-client +# CDS UI Designer Client -This project was generated with [Angular CLI](https://github.com/angular/angular-cli) version 8.3.9. +The **Designer Client** is the modernized Angular 8 web interface for the ONAP **Controller Design Studio (CDS)**. It replaces the legacy Angular 7 client with a streamlined architecture, providing tools for designing, creating, and managing CBA (Controller Blueprint Archive) packages and resource definitions for network automation. -## Development server +## Key Features -Run `ng serve` for a dev server. Navigate to `http://localhost:4200/`. The app will automatically reload if you change any of the source files. +- **Package Dashboard** — Browse, search, filter, and paginate published blueprint packages +- **Blueprint Designer** — Visual drag-and-drop blueprint composition powered by JointJS, with action and function attribute editing +- **Package Creation Wizard** — Multi-step workflow for creating CBA packages (metadata, DSL definitions, imports, templates, mappings, scripts) +- **Source Editor** — Raw JSON/YAML editing with Ace Editor (supports JSON, Python, XML, Kotlin, Velocity, YAML) +- **Resource Dictionary** — Create and manage resource definitions with metadata and source templates +- **Package Import** — Drag-and-drop file upload for importing existing packages +- **Guided Tours** — Built-in onboarding tours via ngx-tour -## Code scaffolding +## Technology Stack -Run `ng generate component component-name` to generate a new component. You can also use `ng generate directive|pipe|service|class|guard|interface|enum|module`. +| Layer | Technology | +| ---------------- | ----------------------------------------------------- | +| Framework | Angular 8.2 | +| State Management | Simple Store pattern (RxJS BehaviorSubjects) | +| UI Components | Angular Material 8.2, ng-bootstrap 5.1, Bootstrap 4.3 | +| Diagramming | JointJS 3.0 | +| Code Editing | Ace Editor (ng2-ace-editor) | +| Data Tables | angular-datatables 9.0 | +| Notifications | ngx-toastr | +| File Handling | ngx-file-drop, file-saver | +| Loading UI | ngx-ui-loader | +| Testing | Karma + Jasmine, Protractor (E2E) | -## Build +## Prerequisites -Run `ng build` to build the project. The build artifacts will be stored in the `dist/` directory. Use the `--prod` flag for a production build. +- **Node.js** 13.7+ (managed automatically via Maven) +- **npm** 6.13+ +- A running CDS backend server (LoopBack 4 server in `../server/`, proxying to the Blueprints Processor) -## Running unit tests +## Getting Started -Run `ng test` to execute the unit tests via [Karma](https://karma-runner.github.io). +```bash +# Install dependencies +npm install -## Running end-to-end tests +# Start the dev server with proxy and linting (http://localhost:4200) +npm start +``` -Run `ng e2e` to execute the end-to-end tests via [Protractor](http://www.protractortest.org/). +The dev server proxies `/controllerblueprint/*` and `/resourcedictionary/*` requests to `https://localhost:3000` (the LoopBack server), which forwards them to the CDS Blueprints Processor backend. -## Further help +## Available Scripts -To get more help on the Angular CLI use `ng help` or go check out the [Angular CLI README](https://github.com/angular/angular-cli/blob/master/README.md). +| Command | Description | +| --------------------- | ---------------------------------------------------------------------- | +| `npm start` | Lint, start the dev server with proxy config, and build for production | +| `npm run build` | Lint and create a production build (AOT, output: `../server/public`) | +| `npm run build:local` | Production build without linting | +| `npm test` | Run unit tests via Karma | +| `npm run lint` | Lint the project with TSLint | +| `npm run e2e` | Run end-to-end tests via Protractor | +| `npm run sonar` | Run SonarQube analysis | + +## Project Structure + +``` +src/app/ +├── modules/ +│ ├── feature-modules/ +│ │ ├── packages/ # Blueprint package management +│ │ │ ├── packages-dashboard/ # Dashboard (list, search, sort, filter, import) +│ │ │ ├── designer/ # Visual blueprint designer (JointJS) +│ │ │ │ ├── actions/ # Action editing +│ │ │ │ ├── action-attributes/ # Action attribute config +│ │ │ │ ├── functions-attribute/ # Function attribute config +│ │ │ │ ├── jointjs/ # JointJS integration +│ │ │ │ └── source-view/ # Raw source editor +│ │ │ ├── package-creation/ # Multi-step creation wizard +│ │ │ │ ├── metadata-tab/ # Package metadata +│ │ │ │ ├── dsl-definitions-tab/ # DSL & imports +│ │ │ │ ├── template-mapping/ # Template mappings +│ │ │ │ ├── topology-template/ # Topology template +│ │ │ │ └── scripts-tab/ # Script management +│ │ │ ├── configuration-dashboard/ # Existing package configuration +│ │ │ └── model/ # Blueprint data models +│ │ │ +│ │ └── resource-dictionary/ # Resource definition management +│ │ ├── resource-dictionary-dashboard/ # Dictionary listing +│ │ └── resource-dictionary-creation/ # Creation wizard +│ │ ├── dictionary-editor/ +│ │ ├── dictionary-metadata/ +│ │ └── sources-template/ +│ │ +│ └── shared-modules/ # Shared UI (header, etc.) +│ +└── common/ + ├── constants/ # Global endpoints and wizard steps + ├── core/ + │ ├── services/ # Base HTTP and typed API services + │ ├── stores/ # Base Store class + │ ├── pipes/ # Search filtering pipe + │ └── canDactivate/ # Route deactivation guards + └── model/ # Pagination model +``` + +## Architecture + +``` +Designer Client ──► LoopBack 4 Server (../server) ──► CDS Blueprints Processor + (port 4200) (port 3000) (port 8080) +``` + +API requests are proxied through the LoopBack server. In production, the built Angular assets (output to `../server/public`) are served as static files by the same server. + +## Building with Maven + +This module integrates into the ONAP CDS Maven build, which manages Node.js/npm versions automatically: + +```bash +# From the repository root +mvn clean install -pl cds-ui/designer-client +``` + +The Maven build uses `frontend-maven-plugin` to install Node.js 13.7.0, run `npm install`, and execute the production build. + +## License + +Copyright (C) 2018 IBM Intellectual Property. All rights reserved. + +Licensed under the Apache License, Version 2.0. See the [LICENSE](http://www.apache.org/licenses/LICENSE-2.0) for details.