Improve readme

.secrets.baseline

@@ -3,7 +3,7 @@
     "files": "go.mod|go.sum|^.secrets.baseline$",
     "lines": null
   },
-  "generated_at": "2026-04-29T13:06:06Z",
+  "generated_at": "2026-05-26T06:43:32Z",
   "plugins_used": [
     {
       "name": "AWSKeyDetector"
@@ -220,39 +220,31 @@
         "hashed_secret": "d033e22ae348aeb5660fc2140aec35850c4da997",
         "is_secret": false,
         "is_verified": false,
-        "line_number": 15,
+        "line_number": 26,
         "type": "Secret Keyword",
         "verified_result": null
       },
       {
         "hashed_secret": "414a7f369189eeb86510894706810e861da56eee",
         "is_secret": false,
         "is_verified": false,
-        "line_number": 23,
+        "line_number": 34,
         "type": "Secret Keyword",
         "verified_result": null
       },
       {
         "hashed_secret": "0d1ba0da3e84e54f29846c93c43182eede365858",
         "is_secret": false,
         "is_verified": false,
-        "line_number": 51,
+        "line_number": 83,
         "type": "Secret Keyword",
         "verified_result": null
       },
       {
         "hashed_secret": "227aaf5c107c722bf5bf81203b4c61bddb1a5601",
         "is_secret": false,
         "is_verified": false,
-        "line_number": 55,
-        "type": "Secret Keyword",
-        "verified_result": null
-      },
-      {
-        "hashed_secret": "12e532ff4ad20c8604dbc101ef3de2dbc644b4a5",
-        "is_secret": false,
-        "is_verified": false,
-        "line_number": 100,
+        "line_number": 87,
         "type": "Secret Keyword",
         "verified_result": null
       }

api/internal/README.md

@@ -1,14 +1,25 @@
 # IBM® Power® Access Cloud Dev Setup Guide
+
 This guide provides step-by-step instructions for setting up and running the IBM® Power® Access Cloud locally.
 
 ## Prerequisites
 
-* Git
-* Go
-* Node.js and npm
-* Yarn package manager
+* **Git** - Version control
+* **Go 1.24**
+* **Node.js v18+** - Frontend runtime
+* **Yarn** - Package manager (not npm)
+* **Kubernetes cluster** - minikube, kind, or cloud-based
+* **Podman or Docker** - For running Keycloak and MongoDB
+
+## Architecture Overview
+
+PAC consists of three main components:
 
-### Part 1: Keycloak and MongoDB setup
+1. **PAC Controller** - Kubernetes operator managing Catalog and Service CRDs
+2. **PAC Go Server** - REST API backend for UI and integrations
+3. **PAC Web UI** - React/Vite frontend with Keycloak authentication
+
+### Part 1: Keycloak and MongoDB Setup
 
 1. From a terminal, enter the following command to start Keycloak:
     ```
@@ -24,29 +35,50 @@ This guide provides step-by-step instructions for setting up and running the IBM
     mongo:latest
     ```
 
-### Part 2: PAC Server Setup
+### Part 2: PAC Controller Setup (Local Testing)
 
-1. Clone Repository
+The PAC Controller is a Kubernetes operator that manages Catalog and Service custom resources.
 
-    ```
-    git clone https://github.com/IBM/power-access-cloud/api.git
-    cd power-access-cloud
+> **Note:** This setup is for **local development and testing**.
+1. **Clone Repository**
+
+    ```bash
+    git clone https://github.com/IBM/power-access-cloud.git
+    cd power-access-cloud/api
     ```
 
-2. Set Up Kubernetes Cluster
+2. **Set Up Kubernetes Cluster**
 
-    Bring up any Kubernetes cluster (minikube, kind, or cloud-based cluster).
+    Bring up any Kubernetes cluster:
+    ```bash
+    # Using minikube
+    minikube start
+
+    # Or using kind
+    kind create cluster
+    ```
 
-3. Generate Manifests and Deploy
+3. **Generate Manifests and Install CRDs**
 
-    ```
+    ```bash
+    cd api
     make generate && make manifests
-    make deploy
+    make install  # Install CRDs
     ```
 
-4. Configure Environment Variables
+### Part 3: PAC Go Server Setup
 
+The PAC Go Server provides REST APIs for the web UI and external integrations.
+
+1. **Navigate to API Directory**
+
+    ```bash
+    cd api
     ```
+
+2. **Configure Environment Variables**
+
+    ```bash
     export KEYCLOAK_CLIENT_ID=your_client_id
     export KEYCLOAK_CLIENT_SECRET=your_client_secret
     export KEYCLOAK_REALM=your_realm
@@ -56,13 +88,31 @@ This guide provides step-by-step instructions for setting up and running the IBM
     export MONGODB_URI=your_mongodb_connection_string
     ```
 
-5. Start the Backend Server
+3. **Build and Run**
+
+    ```bash
+    # Build all binaries
+    make build
+
+    # Run pac-go-server
+    ./bin/pac-go-server
 
+    # Or run directly with go
+    go run ./cmd/pac-go-server/main.go
     ```
-    go run main.go
+
+    The API server will be available at `http://localhost:8080`
+
+4. **View API Documentation**
+
+    Generate Swagger docs:
+    ```bash
+    make swagger
     ```
+
+    Access Swagger UI at: `http://localhost:8080/swagger/index.html`
 
-### Part 3: PAC UI Setup
+### Part 4: PAC UI Setup
 
 1. Clone Repository
 
@@ -86,18 +136,32 @@ This guide provides step-by-step instructions for setting up and running the IBM
 3. Install Dependencies and Run
 
     ```
+    cd web
     yarn install
-    npm start
+    yarn dev
     ```
 
     The UI will be available at http://localhost:3000
 
-### Part 4: PAC Controller Setup
-1. Create IBM Cloud API Key
-2. Configure and Run Controller
-
-    ```
-    export IBMCLOUD_APIKEY=your_ibm_cloud_api_key
-    cd pac
-    make run
-    ```    
+## Project Structure
+
+```
+api/
+├── main.go                    # Controller entry point
+├── cmd/
+│   ├── pac-go-server/        # REST API server
+│   ├── event-notifier/       # Event notification service
+│   └── swagger/              # Swagger documentation
+├── controllers/              # Kubernetes controllers
+│   └── app/                  # App controllers (Catalog, Service)
+├── apis/                     # CRD definitions
+│   └── app/v1alpha1/        # App CRDs (Catalog, Service, Config)
+├── internal/                 # Internal packages
+│   └── pkg/pac-go-server/   # API server implementation
+└── config/                   # Kubernetes manifests
+
+web/
+├── src/                      # React source code
+├── public/                   # Static assets
+└── package.json             # Dependencies (uses Yarn)
+```

web/README.md

@@ -1,74 +1,79 @@
-# Getting Started with Create React App
+# PAC Web UI
 
-This project was bootstrapped with [Create React App](https://github.com/facebook/create-react-app).
+Power Access Cloud (PAC) web frontend built with React and Vite.
 
-## Available Scripts
-
-In the project directory, you can run:
-
-### `npm start`
-
-Runs the app in the development mode.\
-Open [http://localhost:3000](http://localhost:3000) to view it in your browser.
+## Prerequisites
 
-The page will reload when you make changes.\
-You may also see any lint errors in the console.
+- Node.js (v18 or higher recommended)
+- Yarn package manager
 
-### `npm test`
+## Getting Started
 
-Launches the test runner in the interactive watch mode.\
-See the section about [running tests](https://facebook.github.io/create-react-app/docs/running-tests) for more information.
+### Install Dependencies
 
-### `npm run build`
-
-Builds the app for production to the `build` folder.\
-It correctly bundles React in production mode and optimizes the build for the best performance.
-
-The build is minified and the filenames include the hashes.\
-Your app is ready to be deployed!
-
-See the section about [deployment](https://facebook.github.io/create-react-app/docs/deployment) for more information.
-
-### `npm run eject`
+```bash
+yarn install
+```
 
-**Note: this is a one-way operation. Once you `eject`, you can't go back!**
+## Available Scripts
 
-If you aren't satisfied with the build tool and configuration choices, you can `eject` at any time. This command will remove the single build dependency from your project.
+In the project directory, you can run:
 
-Instead, it will copy all the configuration files and the transitive dependencies (webpack, Babel, ESLint, etc) right into your project so you have full control over them. All of the commands except `eject` will still work, but they will point to the copied scripts so you can tweak them. At this point you're on your own.
+### `yarn dev`
 
-You don't have to ever use `eject`. The curated feature set is suitable for small and middle deployments, and you shouldn't feel obligated to use this feature. However we understand that this tool wouldn't be useful if you couldn't customize it when you are ready for it.
+Runs the app in development mode with environment configuration.\
+This script sets up environment variables and starts the Vite dev server.
 
-## Learn More
+```bash
+yarn dev
+```
 
-You can learn more in the [Create React App documentation](https://facebook.github.io/create-react-app/docs/getting-started).
+Open [http://localhost:3000](http://localhost:3000) to view it in your browser.
 
-To learn React, check out the [React documentation](https://reactjs.org/).
+The page will reload when you make changes. You may also see any lint errors in the console.
 
-### Code Splitting
+### `yarn start`
 
-This section has moved here: [https://facebook.github.io/create-react-app/docs/code-splitting](https://facebook.github.io/create-react-app/docs/code-splitting)
+Alternative command to start the development server using env-cmd:
 
-### Analyzing the Bundle Size
+```bash
+yarn start
+```
 
-This section has moved here: [https://facebook.github.io/create-react-app/docs/analyzing-the-bundle-size](https://facebook.github.io/create-react-app/docs/analyzing-the-bundle-size)
+### `yarn build`
 
-### Making a Progressive Web App
+Builds the app for production to the `dist` folder:
 
-This section has moved here: [https://facebook.github.io/create-react-app/docs/making-a-progressive-web-app](https://facebook.github.io/create-react-app/docs/making-a-progressive-web-app)
+```bash
+yarn build
+```
 
-### Advanced Configuration
+It correctly bundles React in production mode and optimizes the build for the best performance.
+The build is minified and the filenames include the hashes. Your app is ready to be deployed!
 
-This section has moved here: [https://facebook.github.io/create-react-app/docs/advanced-configuration](https://facebook.github.io/create-react-app/docs/advanced-configuration)
+## Technology Stack
 
-### Deployment
+- **React 18** - UI library
+- **Vite** - Build tool and dev server (fast HMR)
+- **Redux Toolkit** - State management
+- **Redux Persist** - Persist state to localStorage
+- **Axios** - HTTP client for API calls
+- **Keycloak** - Authentication and authorization
+- **Carbon Design System** - IBM's design system for UI components
+- **React Router** - Client-side routing
+- **Sass** - CSS preprocessor
+- **Yarn** - Package manager
 
-This section has moved here: [https://facebook.github.io/create-react-app/docs/deployment](https://facebook.github.io/create-react-app/docs/deployment)
+## Package Manager
 
-### `npm run build` fails to minify
+This project uses **Yarn** as its package manager. All commands should use `yarn` instead of `npm`:
 
-This section has moved here: [https://facebook.github.io/create-react-app/docs/troubleshooting#npm-run-build-fails-to-minify](https://facebook.github.io/create-react-app/docs/troubleshooting#npm-run-build-fails-to-minify)
+- Install dependencies: `yarn install` or just `yarn`
+- Add a package: `yarn add <package-name>`
+- Remove a package: `yarn remove <package-name>`
+- Run scripts: `yarn <script-name>`
 
+The project includes a `yarn.lock` file which ensures consistent dependency versions across all environments.
 
 ## How to use docker compose environment for local development