### Set Up Local Development with Kind Cluster Configuration

Source: https://github.com/openchoreo/backstage-plugins/blob/main/README.md

Copies the pre-configured local development template and starts the Backstage development server. This setup enables connection to a local Kind cluster running OpenChoreo services at *.openchoreo.localhost. The development server will be accessible at http://localhost:3000.

```bash
# Copy the pre-configured local development template
cp app-config.local.yaml.example app-config.local.yaml

# Start Backstage
yarn start

# Access at http://localhost:3000
```

--------------------------------

### Initialize and Start Backstage Backend with OpenChoreo Modules

Source: https://context7.com/openchoreo/backstage-plugins/llms.txt

Initializes and starts the Backstage backend application, including the OpenChoreo catalog entity provider. This TypeScript code demonstrates the basic setup for a Backstage backend, adding essential core plugins and the specific OpenChoreo catalog backend module.

```typescript
// packages/backend/src/index.ts
import { createBackend } from '@backstage/backend-defaults';

const backend = createBackend();

// Register catalog plugin
backend.add(import('@backstage/plugin-catalog-backend/alpha'));

// Add OpenChoreo catalog entity provider
backend.add(import('@openchoreo/backstage-plugin-catalog-backend-module'));

backend.start();

```

--------------------------------

### Setup Local Development Environment for Backstage with Kind

Source: https://context7.com/openchoreo/backstage-plugins/llms.txt

This Bash script outlines the steps to set up a local development environment for Backstage with Kind cluster integration. It includes prerequisites, DNS configuration, cloning the repository, installing dependencies, setting up local configuration files, and running development servers and tests.

```bash
# Prerequisites: Node.js 22, Yarn 4.4.1, Docker, Kind cluster with OpenChoreo

# Configure DNS resolution for local development
sudo bash -c 'cat >> /etc/hosts <<EOF
127.0.0.1       openchoreo.localhost
127.0.0.1       api.openchoreo.localhost
127.0.0.1       sts.openchoreo.localhost
EOF'

# Clone and install dependencies
git clone https://github.com/openchoreo/backstage-plugins.git
cd backstage-plugins
yarn install

# Setup local configuration
cp app-config.local.yaml.example app-config.local.yaml

# app-config.local.yaml content:
# app:
#   baseUrl: http://localhost:3000
# backend:
#   baseUrl: http://localhost:7007
# openchoreo:
#   baseUrl: http://api.openchoreo.localhost
# thunder:
#   baseUrl: http://sts.openchoreo.localhost
# auth:
#   providers:
#     default-idp:
#       development:
#         clientId: openchoreo-backstage-client
#         clientSecret: backstage-portal-secret

# Start development server (frontend on :3000, backend on :7007)
yarn start

# Run tests
yarn test

# Lint code
yarn lint

# Build all packages
yarn build:all

# Run end-to-end tests
yarn test:e2e

```

--------------------------------

### Install Platform Engineer Core Backend Plugin

Source: https://github.com/openchoreo/backstage-plugins/blob/main/plugins/platform-engineer-core-backend/README.md

Installs the necessary package for the platform engineer core backend plugin using yarn.

```bash
yarn add @openchoreo/backstage-plugin-platform-engineer-core-backend
```

--------------------------------

### Install Project Dependencies Using Yarn Package Manager

Source: https://github.com/openchoreo/backstage-plugins/blob/main/README.md

Installs Node.js dependencies using Yarn package manager. This command reads the project's package.json and yarn.lock files to ensure consistent dependency versions. Requires Node.js 22 and Yarn 4.4.1 to be installed as prerequisites.

```bash
yarn install
```

--------------------------------

### Install Choreo Backend Plugin

Source: https://github.com/openchoreo/backstage-plugins/blob/main/plugins/openchoreo-backend/README.md

Installs the `@internal/plugin-choreo-backend` package to your backend. This is the first step to integrating the Choreo plugin into your Backstage instance.

```bash
# From your root directory
yarn --cwd packages/backend add @internal/plugin-choreo-backend
```

--------------------------------

### Install Platform Engineer Core Plugin

Source: https://github.com/openchoreo/backstage-plugins/blob/main/plugins/platform-engineer-core/README.md

Installs the necessary package for the Platform Engineer Core plugin using Yarn. This is the first step in integrating the plugin into a Backstage application.

```bash
yarn add @openchoreo/backstage-plugin-platform-engineer-core
```

--------------------------------

### Development Commands

Source: https://github.com/openchoreo/backstage-plugins/blob/main/plugins/platform-engineer-core-backend/README.md

Common commands for developing and testing the platform engineer core backend plugin, including starting, testing, and building.

```bash
yarn start
yarn test
yarn build
```

--------------------------------

### Install OpenChoreo Backstage Module

Source: https://github.com/openchoreo/backstage-plugins/blob/main/plugins/catalog-backend-module-openchoreo/README.md

Installs the OpenChoreo backend module for the Backstage catalog plugin using Yarn. This command adds the necessary package to your project's dependencies.

```bash
yarn add @internal/plugin-catalog-backend-module-openchoreo
```

--------------------------------

### Development Commands for OpenChoreo Module

Source: https://github.com/openchoreo/backstage-plugins/blob/main/plugins/catalog-backend-module-openchoreo/README.md

Provides essential development commands for the OpenChoreo backstage module, including starting in development mode, running tests, and building for production.

```bash
# Start in development mode
yarn start

# Run tests
yarn test

# Build for production
yarn build

```

--------------------------------

### GET /api/platform-engineer-core/environments

Source: https://github.com/openchoreo/backstage-plugins/blob/main/plugins/platform-engineer-core-backend/README.md

Retrieves a list of all environments across the platform.

```APIDOC
## GET /api/platform-engineer-core/environments

### Description
Retrieves a list of all environments across the platform.

### Method
GET

### Endpoint
/api/platform-engineer-core/environments

### Parameters

#### Query Parameters

#### Request Body

### Request Example

### Response
#### Success Response (200)
- **environments** (array) - A list of environment objects.
  - **id** (string) - The unique identifier for the environment.
  - **name** (string) - The name of the environment.
  - **organization** (string) - The organization the environment belongs to.
  - **status** (string) - The current deployment status of the environment.
  - **endpoints** (object) - A map of service names to their endpoint URLs.

#### Response Example
```json
{
  "environments": [
    {
      "id": "env-123",
      "name": "production",
      "organization": "example-org",
      "status": "deployed",
      "endpoints": {
        "service-a": "https://service-a.example.com"
      }
    }
  ]
}
```
```

--------------------------------

### Start Platform Engineer Plugin in Development Mode

Source: https://github.com/openchoreo/backstage-plugins/blob/main/plugins/platform-engineer-core/README.md

Initiates the development server for the Platform Engineer Core plugin using Yarn. This command allows for live reloading and testing during development.

```bash
yarn start
```

--------------------------------

### Build and Deploy Backstage Application with Docker and Helm

Source: https://context7.com/openchoreo/backstage-plugins/llms.txt

This Bash script details the process of building the Backstage backend Docker image and deploying the application to Kubernetes using Helm. It includes commands for building the image and a Helm install command with various configuration options for environment variables and integration points.

```bash
# Build backend Docker image
yarn workspace backend build-image

# Docker image includes production configuration
# Uses app-config.production.yaml with environment variable placeholders

# Kubernetes deployment (via Helm)
helm install openchoreo-backstage ./helm/backstage \
  --set image.repository=openchoreo/backstage \
  --set image.tag=latest \
  --set env.BACKSTAGE_BASE_URL=https://backstage.example.com \
  --set env.OPENCHOREO_API_URL=https://api.openchoreo.example.com \
  --set env.THUNDER_BASE_URL=https://idp.openchoreo.example.com \
  --set env.OPENCHOREO_AUTH_CLIENT_ID=backstage-client \
  --set env.OPENCHOREO_AUTH_CLIENT_SECRET=secret123 \
  --set env.GITHUB_TOKEN=ghp_token123

# Environment variables injected by Helm chart:
# - BACKSTAGE_BASE_URL: External URL for Backstage
# - OPENCHOREO_API_URL: OpenChoreo API endpoint
# - THUNDER_BASE_URL: Identity provider base URL
# - OPENCHOREO_AUTH_CLIENT_ID: OAuth client ID
# - OPENCHOREO_AUTH_CLIENT_SECRET: OAuth client secret
# - GITHUB_TOKEN: GitHub integration token
# - BACKEND_SECRET: Backend authentication secret

```

--------------------------------

### Type-Safe API Request Example

Source: https://github.com/openchoreo/backstage-plugins/blob/main/plugins/thunder-idp-client-node/README.md

Demonstrates a type-safe API GET request using the Thunder client. TypeScript validates API paths, query parameters, and response structures, preventing common errors.

```typescript
const { data } = await userClient.GET('/users', {
  params: {
    query: {
      limit: 10,
      offset: 0,
      filter: 'username eq "john.doe"',
    },
  },
});
```

--------------------------------

### GET /api/openchoreo/build-templates

Source: https://context7.com/openchoreo/backstage-plugins/llms.txt

Lists all build templates available for the specified organization, enabling selection of appropriate build pipelines for components.

```APIDOC
## GET /api/openchoreo/build-templates

### Description
Returns the collection of build templates that an organization can use when creating components.

### Method
GET

### Endpoint
/api/openchoreo/build-templates

### Parameters
#### Path Parameters
_None_

#### Query Parameters
- **organizationName** (string) - Required - Name of the organization.

#### Request Body
_None_

### Request Example
GET http://localhost:7007/api/openchoreo/build-templates?organizationName=my-org

### Response
#### Success Response (200)
- **ModelsBuildTemplate[]** (array) - Array of build template objects (e.g., java-maven, nodejs-npm, python-poetry).

### Response Example
[
  {
    "name": "java-maven",
    "description": "Maven build for Java applications",
    "parameters": [
      { "name": "javaVersion", "type": "string", "default": "17" }
    ]
  },
  {
    "name": "nodejs-npm",
    "description": "NPM build for Node.js applications",
    "parameters": []
  }
]
```

--------------------------------

### Configure GitHub Integration for Catalog and Templates

Source: https://github.com/openchoreo/backstage-plugins/blob/main/README.md

Configures GitHub integration by adding a personal access token to the local configuration. This enables Backstage to access GitHub repositories for catalog ingestion and scaffolding templates. The token should have repo and workflow permissions as needed.

```yaml
integrations:
  github:
    - host: github.com
      token: YOUR_GITHUB_TOKEN_HERE
```

--------------------------------

### GET /api/openchoreo/deploy

Source: https://context7.com/openchoreo/backstage-plugins/llms.txt

Retrieves deployment information for a specific component within a project and organization. Returns details about environments and bindings associated with the component.

```APIDOC
## GET /api/openchoreo/deploy

### Description
Retrieves deployment information for a specific component, including its environments and bindings.

### Method
GET

### Endpoint
/api/openchoreo/deploy

### Parameters
#### Path Parameters
_None_

#### Query Parameters
- **componentName** (string) - Required - Name of the component.
- **projectName** (string) - Required - Name of the project containing the component.
- **organizationName** (string) - Required - Name of the organization.

#### Request Body
_None_

### Request Example
GET http://localhost:7007/api/openchoreo/deploy?componentName=my-service&projectName=my-project&organizationName=my-org

### Response
#### Success Response (200)
- **environments** (array of environment objects.
- **bindings** (array) - List of binding objects for the component.

### Response Example
{
  "environments": [
    {
      "name": "development",
      "status": "active"
    }
  ],
  "bindings": [
    {
      "bindingName": "my-service-dev-binding",
      "releaseState": "Active"
    }
  ]
}
```

--------------------------------

### GET /api/platform-engineer-core/environments/:orgName

Source: https://github.com/openchoreo/backstage-plugins/blob/main/plugins/platform-engineer-core-backend/README.md

Retrieves environments for a specific organization.

```APIDOC
## GET /api/platform-engineer-core/environments/:orgName

### Description
Retrieves a list of environments for a specific organization.

### Method
GET

### Endpoint
/api/platform-engineer-core/environments/:orgName

### Parameters
#### Path Parameters
- **orgName** (string) - Required - The name of the organization.

#### Query Parameters

#### Request Body

### Request Example

### Response
#### Success Response (200)
- **environments** (array) - A list of environment objects for the specified organization.
  - **id** (string) - The unique identifier for the environment.
  - **name** (string) - The name of the environment.
  - **organization** (string) - The organization the environment belongs to.
  - **status** (string) - The current deployment status of the environment.
  - **endpoints** (object) - A map of service names to their endpoint URLs.

#### Response Example
```json
{
  "environments": [
    {
      "id": "env-456",
      "name": "staging",
      "organization": "example-org",
      "status": "deploying",
      "endpoints": {
        "service-b": "https://staging-service-b.example.com"
      }
    }
  ]
}
```
```

--------------------------------

### Get OpenChoreo Workload Specification

Source: https://context7.com/openchoreo/backstage-plugins/llms.txt

Fetches the current workload specification for a given component, including replica count, resource requests/limits, and probes. Requires component, project, and organization names.

```bash
curl -X GET "http://localhost:7007/api/openchoreo/workload?componentName=my-service&projectName=my-project&organizationName=my-org"
```

--------------------------------

### Configure Local DNS Resolution for OpenChoreo Development

Source: https://github.com/openchoreo/backstage-plugins/blob/main/README.md

Adds three DNS entries to /etc/hosts for local OpenChoreo service resolution. This ensures Node.js and other tools can resolve .localhost subdomains that browsers handle automatically. Requires sudo privileges and works on Linux and macOS systems.

```hosts
127.0.0.1       openchoreo.localhost
127.0.0.1       api.openchoreo.localhost
127.0.0.1       sts.openchoreo.localhost
```

--------------------------------

### GET /api/openchoreo/cell-diagram

Source: https://context7.com/openchoreo/backstage-plugins/llms.txt

Fetches a cell diagram representing the architecture of a project, including components, connections, and cells. Useful for visualizing system topology in Backstage.

```APIDOC
## GET /api/openchoreo/cell-diagram

### Description
Retrieves a cell diagram that visualizes the architecture of the specified project.

### Method
GET

### Endpoint
/api/openchoreo/cell-diagram

### Parameters
#### Path Parameters
_None_

#### Query Parameters
- **projectName** (string) - Required - Name of the project to visualize.
- **organizationName** (string) - Required - Organization containing the project.

#### Request Body
_None_

### Request Example
GET http://localhost:7007/api/openchoreo/cell-diagram?projectName=my-project&organizationName=my-org
### Response
#### Success Response (200)
- **components** (array) - List of component descriptors.
- **connections** (array) - List of connections between components.
- **cells** (array) - Cell representations for diagram rendering.

### Response Example
{
  "components": [
    { "name": "my-service", "type": "Service" }
  ],
  "connections": [
    { "source": "my-service", "target": "database" }
  ],
  "cells": [
    { "id": "cell-1", "label": "my-service" }
  ]
}
```

--------------------------------

### GET /api/openchoreo/workload

Source: https://context7.com/openchoreo/backstage-plugins/llms.txt

Retrieves the workload specification for a given component.

```APIDOC
## GET /api/openchoreo/workload

### Description
Retrieves the workload specification (replicas, resources, probes) for a specific component.

### Method
GET

### Endpoint
/api/openchoreo/workload

### Parameters
#### Query Parameters
- **componentName** (string) - Required - The name of the component.
- **projectName** (string) - Required - The name of the project.
- **organizationName** (string) - Required - The name of the organization.

#### Request Body
None

### Request Example
```
GET /api/openchoreo/workload?componentName=my-service&projectName=my-project&organizationName=my-org
```

### Response
#### Success Response (200)
- **replicas** (integer) - The number of replicas for the workload.
- **resources** (object) - CPU and memory resource limits and requests.
  - **requests** (object)
    - **cpu** (string)
    - **memory** (string)
  - **limits** (object)
    - **cpu** (string)
    - **memory** (string)
- **livenessProbe** (object) - Configuration for the liveness probe.
- **readinessProbe** (object) - Configuration for the readiness probe.

#### Response Example
```json
{
  "replicas": 1,
  "resources": {
    "requests": {"cpu": "250m", "memory": "256Mi"},
    "limits": {"cpu": "500m", "memory": "512Mi"}
  },
  "livenessProbe": {
    "httpGet": {"path": "/health", "port": 8080},
    "initialDelaySeconds": 15,
    "periodSeconds": 20
  }
}
```
```

--------------------------------

### GET /api/openchoreo/builds

Source: https://context7.com/openchoreo/backstage-plugins/llms.txt

Retrieves the build history for a given component, including status, timestamps, and commit information.

```APIDOC
## GET /api/openchoreo/builds

### Description
Fetches all builds associated with a specific component, providing details such as build ID, status, creation time, and source commit.

### Method
GET

### Endpoint
/api/openchoreo/builds

### Parameters
#### Path Parameters
_None_

#### Query Parameters
- **componentName** (string) - Required - Name of the component.
- **projectName** (string) - Required - Project containing the component.
- **organizationName** (string) - Required - Organization name.

#### Request Body
_None_

### Request Example
GET http://localhost:7007/api/openchoreo/builds?componentName=my-service&projectName=my-project&organizationName=my-org

### Response
#### Success Response (200)
- **ModelsBuild[]** (array) - List of build objects.

### Response Example
[
  {
    "id": "build-123",
    "status": "SUCCESS",
    "createdAt": "2024-10-01T12:34:56Z",
    "commit": "a1b2c3d4"
  },
  {
    "id": "build-124",
    "status": "FAILED",
    "createdAt": "2024-10-02T08:15:30Z",
    "commit": "d4c3b2a1"
  }
]
```

--------------------------------

### Calling OpenChoreo REST API Endpoints with Bash

Source: https://context7.com/openchoreo/backstage-plugins/llms.txt

These Bash curl commands illustrate how to interact with the OpenChoreo backend REST API endpoints for managing deployments, bindings, cell diagrams, build templates, and builds. It assumes a running Backstage instance with the plugins installed and accessible on localhost:7007. Inputs are JSON payloads or query parameters; outputs are JSON responses with model data. Limitations include requiring HTTP access to the backend and proper authentication headers for secured endpoints.

```bash
# Fetch deployment information for a component
curl -X GET "http://localhost:7007/api/openchoreo/deploy?componentName=my-service&projectName=my-project&organizationName=my-org"
# Returns: { environments: [...], bindings: [...] }

# Promote a component between environments
curl -X POST "http://localhost:7007/api/openchoreo/promote-deployment" \
  -H "Content-Type: application/json" \
  -d '{
    "sourceEnv": "development",
    "targetEnv": "staging",
    "componentName": "my-service",
    "projectName": "my-project",
    "orgName": "my-org"
  }'
# Returns: BindingResponse[]

# Update component binding state (Active, Suspend, Undeploy)
curl -X PATCH "http://localhost:7007/api/openchoreo/update-binding" \
  -H "Content-Type: application/json" \
  -d '{
    "componentName": "my-service",
    "projectName": "my-project",
    "orgName": "my-org",
    "bindingName": "my-service-dev-binding",
    "releaseState": "Active"
  }'
# Returns: { binding: {...} }

# Fetch cell diagram for project architecture visualization
curl -X GET "http://localhost:7007/api/openchoreo/cell-diagram?projectName=my-project&organizationName=my-org"
# Returns: { components: [...], connections: [...], cells: [...] }

# Get build templates available for the organization
curl -X GET "http://localhost:7007/api/openchoreo/build-templates?organizationName=my-org"
# Returns: ModelsBuildTemplate[] with java-maven, nodejs-npm, python-poetry, etc.

# Fetch all builds for a component
curl -X GET "http://localhost:7007/api/openchoreo/builds?componentName=my-service&projectName=my-project&organizationName=my-org"
# Returns: ModelsBuild[] with id, status, createdAt, commit
```

--------------------------------

### User Management API Operations (TypeScript)

Source: https://github.com/openchoreo/backstage-plugins/blob/main/plugins/thunder-idp-client-node/README.md

Provides examples of common User Management API operations using the Thunder IdP client. This includes listing, retrieving, creating, updating, and deleting users, as well as fetching a user's groups.

```typescript
// List users
await userClient.GET('/users', { params: { query: { limit: 10 } } });

// Get user by ID
await userClient.GET('/users/{id}', { params: { path: { id: 'user-uuid' } } });

// Create user
await userClient.POST('/users', {
  body: {
    organizationUnit: 'org-uuid',
    type: 'customer',
    attributes: {
      email: 'user@example.com',
      username: 'john.doe',
    },
  },
});

// Update user
await userClient.PUT('/users/{id}', {
  params: { path: { id: 'user-uuid' } },
  body: {
    /* updated attributes */
  },
});

// Delete user
await userClient.DELETE('/users/{id}', {
  params: { path: { id: 'user-uuid' } },
});

// Get user's groups
await userClient.GET('/users/{id}/groups', {
  params: { path: { id: 'user-uuid' } },
});
```

--------------------------------

### GET /groups

Source: https://github.com/openchoreo/backstage-plugins/blob/main/plugins/thunder-idp-client-node/README.md

Retrieves a list of groups from the Thunder IdP system. This endpoint supports pagination. Use for fetching multiple groups efficiently.

```APIDOC
## GET /groups

### Description
Retrieves a paginated list of groups.

### Method
GET

### Endpoint
/groups

### Parameters
#### Query Parameters
- **limit** (number) - Optional - Number of groups to return

### Request Example
No request body required.

### Response
#### Success Response (200)
- **data** (array) - List of group objects
- **error** (object) - Error details if any

#### Response Example
{
  "data": [
    {
      "id": "group-uuid",
      "name": "Engineering",
      "description": "Engineering team"
    }
  ],
  "error": null
}
```

--------------------------------

### GET /users

Source: https://github.com/openchoreo/backstage-plugins/blob/main/plugins/thunder-idp-client-node/README.md

Retrieves a list of users from the Thunder IdP system. This endpoint supports filtering and pagination to efficiently query user data. Use this for fetching multiple users with optional search criteria.

```APIDOC
## GET /users

### Description
Retrieves a paginated list of users with optional filtering.

### Method
GET

### Endpoint
/users

### Parameters
#### Query Parameters
- **limit** (number) - Optional - Number of users to return
- **offset** (number) - Optional - Number of users to skip
- **filter** (string) - Optional - SCIM filter for searching users

### Request Example
No request body required.

### Response
#### Success Response (200)
- **data** (array) - List of user objects
- **error** (object) - Error details if any

#### Response Example
{
  "data": [
    {
      "id": "user-uuid",
      "username": "john.doe",
      "email": "user@example.com"
    }
  ],
  "error": null
}
```

--------------------------------

### Register OpenChoreo Module in Backstage Backend

Source: https://github.com/openchoreo/backstage-plugins/blob/main/plugins/catalog-backend-module-openchoreo/README.md

Registers the OpenChoreo catalog module within the Backstage backend application. This involves importing the module and adding it to the backend instance before starting it.

```typescript
// packages/backend/src/index.ts
import { createBackend } from '@backstage/backend-defaults';

const backend = createBackend();

// ... other plugins

// Add the OpenChoreo catalog module
backend.add(import('@internal/plugin-catalog-backend-module-openchoreo'));

backend.start();

```

--------------------------------

### GET /groups/{id}

Source: https://github.com/openchoreo/backstage-plugins/blob/main/plugins/thunder-idp-client-node/README.md

Fetches details of a specific group by its ID. This endpoint retrieves group information including name and description. It requires the group ID in the path.

```APIDOC
## GET /groups/{id}

### Description
Retrieves a specific group by ID.

### Method
GET

### Endpoint
/groups/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - Unique group identifier

### Request Example
No request body required.

### Response
#### Success Response (200)
- **data** (object) - Group details
- **error** (object) - Error details if any

#### Response Example
{
  "data": {
    "id": "group-uuid",
    "name": "Engineering",
    "description": "Engineering team"
  },
  "error": null
}
```

--------------------------------

### GET /users/{id}/groups

Source: https://github.com/openchoreo/backstage-plugins/blob/main/plugins/thunder-idp-client-node/README.md

Retrieves the groups associated with a specific user. This endpoint lists the groups a user belongs to. It requires the user ID in the path.

```APIDOC
## GET /users/{id}/groups

### Description
Retrieves groups associated with a user.

### Method
GET

### Endpoint
/users/{id}/groups

### Parameters
#### Path Parameters
- **id** (string) - Required - Unique user identifier

### Request Example
No request body required.

### Response
#### Success Response (200)
- **data** (array) - List of group objects
- **error** (object) - Error details if any

#### Response Example
{
  "data": [
    {
      "id": "group-uuid",
      "name": "Engineering"
    }
  ],
  "error": null
}
```

--------------------------------

### GET /users/{id}

Source: https://github.com/openchoreo/backstage-plugins/blob/main/plugins/thunder-idp-client-node/README.md

Fetches details of a specific user by their unique ID. This endpoint is useful for retrieving individual user information without listing all users. It requires the user ID in the path.

```APIDOC
## GET /users/{id}

### Description
Retrieves a specific user by ID.

### Method
GET

### Endpoint
/users/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - Unique user identifier

### Request Example
No request body required.

### Response
#### Success Response (200)
- **data** (object) - User details
- **error** (object) - Error details if any

#### Response Example
{
  "data": {
    "id": "user-uuid",
    "username": "john.doe",
    "attributes": {
      "email": "user@example.com"
    }
  },
  "error": null
}
```

--------------------------------

### Backstage Scaffolder Template for OpenChoreo Project Creation

Source: https://context7.com/openchoreo/backstage-plugins/llms.txt

Defines a Backstage scaffolder template for creating new OpenChoreo projects. It specifies parameters for organization, project name, display name, and description, and uses the 'openchoreo:project:create' action. The output includes a link to the created project.

```yaml
apiVersion: scaffolder.backstage.io/v1beta3
kind: Template
metadata:
  name: openchoreo-project-template
  title: Create OpenChoreo Project
spec:
  owner: platform-team
  type: project
  parameters:
    - title: Project Details
      required:
        - orgName
        - projectName
      properties:
        orgName:
          title: Organization
          type: string
          description: Organization to create the project in
        projectName:
          title: Project Name
          type: string
          description: Unique project identifier
        displayName:
          title: Display Name
          type: string
        description:
          title: Description
          type: string
  steps:
    - id: create-project
      name: Create OpenChoreo Project
      action: openchoreo:project:create
      input:
        orgName: ${{ parameters.orgName }}
        projectName: ${{ parameters.projectName }}
        displayName: ${{ parameters.displayName }}
        description: ${{ parameters.description }}
        deploymentPipeline: 'standard-pipeline'

  output:
    links:
      - title: Project in OpenChoreo
        url: 'http://openchoreo.localhost/projects/${{ steps["create-project"].output.projectName }}'
```

--------------------------------

### POST /api/openchoreo/promote-deployment

Source: https://context7.com/openchoreo/backstage-plugins/llms.txt

Promotes a component's deployment from a source environment to a target environment. Returns the updated binding information after promotion.

```APIDOC
## POST /api/openchoreo/promote-deployment

### Description
Promotes a component's deployment between environments (e.g., development to staging) and returns the resulting binding responses.

### Method
POST

### Endpoint
/api/openchoreo/promote-deployment

### Parameters
#### Path Parameters
_None_

#### Query Parameters
_None_

#### Request Body
- **sourceEnv** (string) - Required - Name of the source environment.
- **targetEnv** (string) - Required - Name of the target environment.
- **componentName** (string) - Required Name of the component to promote.
- **projectName** (string) - Required - Project containing the component.
- **orgName** (string) - Required - Organization name.

### Request Example
POST http://localhost:7007/api/openchoreo/promote-deployment
Content-Type: application/json

{
  "sourceEnv": "development",
  "targetEnv": "staging",
  "componentName": "my-service",
  "projectName": "my-project",
  "orgName": "my-org"
}

### Response
#### Success Response (200)
- **BindingResponse[]** (array) - List of binding response objects reflecting the promotion.

### Response Example[
  {
    "bindingName": "my-service-staging-binding",
    "releaseState": "Active",
    "environment": "staging"
  }
]
```

--------------------------------

### Apply OpenChoreo Workload Specification

Source: https://context7.com/openchoreo/backstage-plugins/llms.txt

Applies a new workload specification for a component, defining replica count, resource usage, and liveness probes. Requires component, project, and organization names, along with the desired workload configuration. Returns the updated workload specification.

```bash
curl -X POST "http://localhost:7007/api/openchoreo/workload?componentName=my-service&projectName=my-project&organizationName=my-org" \
  -H "Content-Type: application/json" \
  -d '{
    "replicas": 3,
    "resources": {
      "requests": { "cpu": "500m", "memory": "512Mi" },
      "limits": { "cpu": "1000m", "memory": "1Gi" }
    },
    "livenessProbe": {
      "httpGet": { "path": "/health", "port": 8080 },
      "initialDelaySeconds": 30,
      "periodSeconds": 10
    }
  }'
```

--------------------------------

### Build Platform Engineer Plugin for Production

Source: https://github.com/openchoreo/backstage-plugins/blob/main/plugins/platform-engineer-core/README.md

Compiles and bundles the Platform Engineer Core plugin for production deployment using Yarn. This command generates the optimized build artifacts.

```bash
yarn build
```

--------------------------------

### Scaffolder Action: openchoreo:project:create

Source: https://context7.com/openchoreo/backstage-plugins/llms.txt

Scaffolder action for creating OpenChoreo projects from Backstage templates.

```APIDOC
## Scaffolder Action: openchoreo:project:create

### Description
Scaffolder action for creating OpenChoreo projects from Backstage templates. This action configures the project with specified details and a standard deployment pipeline.

### Method
N/A (Scaffolder Action)

### Endpoint
N/A

### Parameters
#### Input Parameters (from template)
- **orgName** (string) - Required - Organization to create the project in.
- **projectName** (string) - Required - Unique project identifier.
- **displayName** (string) - Optional - Display name for the project.
- **description** (string) - Optional - Description for the project.

### Request Example (within template.yaml)
```yaml
steps:
  - id: create-project
    name: Create OpenChoreo Project
    action: openchoreo:project:create
    input:
      orgName: ${{ parameters.orgName }}
      projectName: ${{ parameters.projectName }}
      displayName: ${{ parameters.displayName }}
      description: ${{ parameters.description }}
      deploymentPipeline: 'standard-pipeline'
```

### Response (Output from action)
- **projectName** (string) - The name of the created project.

### Output Example (from template)
```yaml
output:
  links:
    - title: Project in OpenChoreo
      url: 'http://openchoreo.localhost/projects/${{ steps["create-project"].output.projectName }}'
```
```

--------------------------------

### Create OpenChoreo Component Backstage Template

Source: https://context7.com/openchoreo/backstage-plugins/llms.txt

A Backstage scaffolder template for creating new OpenChoreo components. It defines parameters for component details, build configurations, and repository settings, and uses the 'openchoreo:component:create' action to provision the component.

```yaml
apiVersion: scaffolder.backstage.io/v1beta3
kind: Template
metadata:
  name: openchoreo-component-template
  title: Create OpenChoreo Component
spec:
  owner: platform-team
  type: component
  parameters:
    - title: Component Details
      required:
        - orgName
        - projectName
        - componentName
        - componentType
      properties:
        orgName:
          title: Organization
          type: string
        projectName:
          title: Project
          type: string
        componentName:
          title: Component Name
          type: string
        componentType:
          title: Component Type
          type: string
          enum:
            - Service
            - WebApp
            - ScheduledTask
            - APIProxy
        useBuiltInCI:
          title: Use OpenChoreo CI
          type: boolean
          default: true
        repoUrl:
          title: Repository URL
          type: string
        branch:
          title: Branch
          type: string
          default: main
        componentPath:
          title: Component Path
          type: string
        buildTemplateName:
          title: Build Template
          type: string
          enum:
            - java-maven
            - nodejs-npm
            - python-poetry
            - go-modules
        buildParameters:
          title: Build Parameters
          type: object
          properties:
            javaVersion:
              type: string
              default: '17'

  steps:
    - id: create-component
      name: Create OpenChoreo Component
      action: openchoreo:component:create
      input:
        orgName: ${{ parameters.orgName }}
        projectName: ${{ parameters.projectName }}
        componentName: ${{ parameters.componentName }}
        displayName: ${{ parameters.componentName }}
        componentType: ${{ parameters.componentType }}
        useBuiltInCI: ${{ parameters.useBuiltInCI }}
        repoUrl: ${{ parameters.repoUrl }}
        branch: ${{ parameters.branch }}
        componentPath: ${{ parameters.componentPath }}
        buildTemplateName: ${{ parameters.buildTemplateName }}
        buildParameters: ${{ parameters.buildParameters }}

  output:
    links:
      - title: Component in OpenChoreo
        url: 'http://openchoreo.localhost/projects/${{ steps["create-component"].output.projectName }}/components/${{ steps["create-component"].output.componentName }}'

```

--------------------------------

### Configure OpenChoreo Instance URL and Token

Source: https://github.com/openchoreo/backstage-plugins/blob/main/plugins/platform-engineer-core/README.md

Sets up the OpenChoreo configuration for the plugin, specifying the base URL of the OpenChoreo instance and an optional API token. This is typically done in a YAML configuration file.

```yaml
openchoreo:
  baseUrl: 'https://your-openchoreo-instance.com'
  token: 'your-api-token' # optional
```

--------------------------------

### GET /groups/{id}/members

Source: https://github.com/openchoreo/backstage-plugins/blob/main/plugins/thunder-idp-client-node/README.md

Retrieves the members of a specific group. This endpoint lists users or other entities belonging to the group. It requires the group ID in the path.

```APIDOC
## GET /groups/{id}/members

### Description
Retrieves members of a group.

### Method
GET

### Endpoint
/groups/{id}/members

### Parameters
#### Path Parameters
- **id** (string) - Required - Unique group identifier

### Request Example
No request body required.

### Response
#### Success Response (200)
- **data** (array) - List of member objects
- **error** (object) - Error details if any

#### Response Example
{
  "data": [
    { "id": "user-uuid-1", "type": "user" },
    { "id": "user-uuid-2", "type": "user" }
  ],
  "error": null
}
```

--------------------------------

### Backstage Integration for Thunder IdP Clients (TypeScript)

Source: https://github.com/openchoreo/backstage-plugins/blob/main/plugins/thunder-idp-client-node/README.md

Shows how to integrate Thunder IdP clients into a Backstage backend using configuration. It utilizes a factory function that reads settings from `app-config.yaml` and uses a logger service.

```typescript
import { createThunderClientsFromConfig } from '@openchoreo/backstage-plugin-thunder-idp-client-node';
import { LoggerService } from '@backstage/backend-plugin-api';
import { Config } from '@backstage/config';

export function createMyService(config: Config, logger: LoggerService) {
  const { userClient, groupClient } = createThunderClientsFromConfig(
    config,
    logger,
  );

  // Use the clients
  const { data: users } = await userClient.GET('/users');
  const { data: groups } = await groupClient.GET('/groups');

  return { users, groups };
}
```

--------------------------------

### Upgrade Thunder Version in package.json

Source: https://github.com/openchoreo/backstage-plugins/blob/main/plugins/thunder-idp-client-node/README.md

Illustrates the process of upgrading the Thunder version by modifying the `thunderVersion` field in `package.json`, followed by cleaning, regenerating clients, building, and testing.

```json
{
  "thunderVersion": "v0.11.0"
}
```

--------------------------------

### Run Tests for Platform Engineer Plugin

Source: https://github.com/openchoreo/backstage-plugins/blob/main/plugins/platform-engineer-core/README.md

Executes the test suite for the Platform Engineer Core plugin using Yarn. This command ensures the plugin's components and logic are functioning as expected.

```bash
yarn test
```

--------------------------------

### Trigger OpenChoreo Build

Source: https://context7.com/openchoreo/backstage-plugins/llms.txt

Initiates a new build process for a specified component within an organization and project. Requires component, project, organization names, and a commit hash. Returns build status and ID.

```bash
curl -X POST "http://localhost:7007/api/openchoreo/builds" \
  -H "Content-Type: application/json" \
  -d '{
    "componentName": "my-service",
    "projectName": "my-project",
    "organizationName": "my-org",
    "commit": "abc123"
  }'
```

--------------------------------

### Initialize Thunder IdP API Clients (TypeScript)

Source: https://github.com/openchoreo/backstage-plugins/blob/main/plugins/thunder-idp-client-node/README.md

Demonstrates how to create and use type-safe API clients for Thunder IdP's User and Group Management. It requires a base URL and an authentication token. The clients support listing users and groups with type-safe parameters.

```typescript
import {
  createThunderUserClient,
  createThunderGroupClient,
} from '@openchoreo/backstage-plugin-thunder-idp-client-node';

// Create API clients
const userClient = createThunderUserClient({
  baseUrl: 'https://thunder.example.com:8090',
  token: 'your-bearer-token',
});

const groupClient = createThunderGroupClient({
  baseUrl: 'https://thunder.example.com:8090',
  token: 'your-bearer-token',
});

// List users with type-safe parameters
const { data: users, error: userError } = await userClient.GET('/users', {
  params: {
    query: {
      limit: 10,
      offset: 0,
      filter: 'username eq "john.doe"',
    },
  },
});

if (userError) {
  console.error('Error fetching users:', userError);
} else {
  console.log('Users:', users);
}

// List groups
const { data: groups, error: groupError } = await groupClient.GET('/groups', {
  params: {
    query: { limit: 10 },
  },
});
```

--------------------------------

### Configure OpenChoreo Backend Module

Source: https://github.com/openchoreo/backstage-plugins/blob/main/plugins/catalog-backend-module-openchoreo/README.md

Configures the OpenChoreo module by adding its settings to the `app-config.yaml` file. This includes the base URL for the OpenChoreo API and an optional authentication token.

```yaml
openchoreo:
  baseUrl: http://localhost:8080/api/v1
  token: ${OPENCHOREO_TOKEN} # optional: for authentication
```

--------------------------------

### Using OpenChoreoApiClient in TypeScript

Source: https://context7.com/openchoreo/backstage-plugins/llms.txt

This TypeScript code demonstrates how to initialize and use the OpenChoreoApiClient to interact with the OpenChoreo platform APIs. It depends on the @openchoreo/backstage-plugin-api package and requires a logger service from Backstage. Inputs include API URL and optional token; outputs are model objects like organizations, projects, and components. Limitations include requiring valid authentication and network access to the API.

```typescript
import { OpenChoreoApiClient } from '@openchoreo/backstage-plugin-api';
import { LoggerService } from '@backstage/backend-plugin-api';

// Initialize the client
const client = new OpenChoreoApiClient(
  'http://api.openchoreo.localhost',
  'optional-token',
  logger
);

// Fetch all organizations
const organizations = await client.getAllOrganizations();
// Returns: ModelsOrganization[]

// Fetch projects for an organization
const projects = await client.getAllProjects('my-org');
// Returns: ModelsProject[]

// Create a new project
const project = await client.createProject('my-org', {
  name: 'my-project',
  displayName: 'My Project',
  description: 'A sample project',
  deploymentPipeline: 'standard-pipeline'
});
// Returns: ModelsProject with id, name, displayName, description

// Fetch components in a project
const components = await client.getAllComponents('my-org', 'my-project');
// Returns: ModelsComponent[]

// Create a component with build configuration
const component = await client.createComponent('my-org', 'my-project', {
  name: 'my-service',
  displayName: 'My Service',
  description: 'REST API service',
  type: 'Service',
  buildConfig: {
    repoUrl: 'https://github.com/org/repo',
    repoBranch: 'main',
    componentPath: '/services/api',
    buildTemplateRef: 'java-maven',
    buildTemplateParams: [
      { name: 'javaVersion', value: '17' }
    ]
  }
});
// Returns: ModelsComponent
```

--------------------------------

### Fetch OpenChoreo Runtime Logs

Source: https://context7.com/openchoreo/backstage-plugins/llms.txt

Retrieves runtime logs for a specific component, with options for filtering by log level, time range, and pagination. Requires environment ID and project/organization details. Returns a list of logs and the total count.

```bash
curl -X POST "http://localhost:7007/api/openchoreo/logs/component/component-123?orgName=my-org&projectName=my-project" \
  -H "Content-Type: application/json" \
  -d '{
    "environmentId": "env-456",
    "logLevels": ["ERROR", "WARN"],
    "startTime": "2025-11-07T00:00:00Z",
    "endTime": "2025-11-07T23:59:59Z",
    "limit": 100,
    "offset": 0
  }'
```

--------------------------------

### ThunderClientConfig Interface

Source: https://github.com/openchoreo/backstage-plugins/blob/main/plugins/thunder-idp-client-node/README.md

Defines the TypeScript interface for configuring the Thunder client. It includes options for the base URL, authentication token, custom fetch API, and a Backstage logger.

```typescript
interface ThunderClientConfig {
  baseUrl: string; // Thunder API base URL
  token?: string; // Bearer token for authentication
  fetchApi?: typeof fetch; // Custom fetch implementation (optional)
  logger?: LoggerService; // Backstage logger (optional)
}
```

--------------------------------

### Test Thunder Version with Script

Source: https://github.com/openchoreo/backstage-plugins/blob/main/plugins/thunder-idp-client-node/README.md

Demonstrates how to test against a specific Thunder version using a bash script without altering the package.json file. This allows for isolated testing of different Thunder releases.

```bash
bash scripts/generate-clients.sh --thunder-version v0.11.0
```

--------------------------------

### POST /users

Source: https://github.com/openchoreo/backstage-plugins/blob/main/plugins/thunder-idp-client-node/README.md

Creates a new user in the Thunder IdP system. This endpoint requires user attributes like email and username. It's used for adding new users to the identity provider.

```APIDOC
## POST /users

### Description
Creates a new user in the system.

### Method
POST

### Endpoint
/users

### Parameters
#### Request Body
- **organizationUnit** (string) - Required - Organization unit UUID
- **type** (string) - Required - User type (e.g., customer)
- **attributes** (object) - Required - User attributes including email and username

### Request Example
{
  "organizationUnit": "org-uuid",
  "type": "customer",
  "attributes": {
    "email": "user@example.com",
    "username": "john.doe"
  }
}

### Response
#### Success Response (201)
- **data** (object) - Created user details
- **error** (object) - Error details if any

#### Response Example
{
  "data": {
    "id": "new-user-uuid",
    "username": "john.doe"
  },
  "error": null
}
```

--------------------------------

### Generate and Clean API Clients (Yarn)

Source: https://github.com/openchoreo/backstage-plugins/blob/main/plugins/thunder-idp-client-node/README.md

Provides yarn commands to generate API clients from OpenAPI specifications and clean previously generated files. Useful for maintaining up-to-date client code based on API definitions.

```bash
yarn generate:clients
yarn clean:generated
yarn clean:generated && yarn generate:clients
```