@bluealba/platform-cli 1.0.1 → 1.0.2

package/docs/architecture/bootstrap.mdx

@@ -0,0 +1,1442 @@
+---
+title: Platform Bootstrap
+description: How to bootstrap and configure the Blue Alba Platform with applications, modules, roles, operations, and catalog definitions
+---
+
+import { Card, CardGrid, Aside, Tabs, TabItem } from '@astrojs/starlight/components';
+
+The Blue Alba Platform uses a **bootstrap mechanism** to initialize and configure platform resources such as applications, modules, authorization definitions (roles and operations), and catalog entries. This enables declarative configuration management across environments.
+
+## Overview
+
+The Platform is a living, evolving system that supports dynamic changes:
+
+<CardGrid stagger>
+  <Card title="Add Applications" icon="seti:folder">
+    Register new business applications with the platform
+  </Card>
+
+  <Card title="Register Services" icon="puzzle">
+    Add microservices and micro-frontends to the catalog
+  </Card>
+
+  <Card title="Define Authorization" icon="shield">
+    Declare roles, operations, and permissions
+  </Card>
+
+  <Card title="Configure Modules" icon="setting">
+    Customize module behavior with configuration properties
+  </Card>
+
+  <Card title="Update Shared Libraries" icon="seti:npm">
+    Register shared libraries for UI modules
+  </Card>
+
+  <Card title="Schedule Jobs" icon="seti:clock">
+    Define scheduled jobs declaratively for recurring tasks
+  </Card>
+
+  <Card title="Environment Propagation" icon="random">
+    Synchronize configurations across development, staging, and production
+  </Card>
+</CardGrid>
+
+---
+
+## Platform Bootstrap Service
+
+Every PAE product includes a **platform-bootstrap-service** - a simple web service that contains all platform definitions as JSON data. When this service starts, it automatically synchronizes these definitions with the platform via REST APIs.
+
+### Architecture
+
+```
+┌─────────────────────────────────────────────────────────┐
+│         Platform Bootstrap Service                       │
+│                                                          │
+│  ┌────────────────────────────────────────────────┐    │
+│  │  data/                                          │    │
+│  │  ├── app1/                                      │    │
+│  │  │   ├── application.json                      │    │
+│  │  │   ├── modules.json                          │    │
+│  │  │   ├── operations.json                       │    │
+│  │  │   ├── roles.json                            │    │
+│  │  │   └── jobs.json                             │    │
+│  │  ├── app2/                                      │    │
+│  │  └── platform/                                  │    │
+│  └────────────────────────────────────────────────┘    │
+│                        │                                 │
+│                        ▼                                 │
+│  ┌────────────────────────────────────────────────┐    │
+│  │  Bootstrap Sync Engine                         │    │
+│  │  • Compare JSON with DB state                  │    │
+│  │  • Create/Update/Delete resources              │    │
+│  │  • Call Platform REST APIs                     │    │
+│  └────────────────────────────────────────────────┘    │
+└───────────────────────┬─────────────────────────────────┘
+                        │
+                        ▼
+┌─────────────────────────────────────────────────────────┐
+│         Blue Alba Platform                               │
+│                                                          │
+│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐  │
+│  │   Catalog    │  │ Authorization│  │   Tenants    │  │
+│  │   Service    │  │   Service    │  │   Service    │  │
+│  └──────────────┘  └──────────────┘  └──────────────┘  │
+└─────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Repository Structure
+
+The bootstrap service typically follows this structure:
+
+```
+platform-bootstrap-service/
+├── src/
+│   └── main.ts                 # Bootstrap application entry point
+├── data/
+│   ├── app1/                   # Business application 1
+│   │   ├── application.json    # Application metadata
+│   │   ├── modules.json        # Services and UIs
+│   │   ├── operations.json     # Authorization operations
+│   │   ├── roles.json          # Authorization roles
+│   │   ├── modules-config.json # Module customizations (optional)
+│   │   ├── jobs.json           # Scheduled jobs (optional)
+│   │   └── feature-flags.json  # Feature flags (optional)
+│   ├── app2/                   # Business application 2
+│   └── platform/               # Platform module overrides
+│       └── modules-config.json # Platform module customizations
+├── package.json
+└── README.md
+```
+
+### Folder Purpose
+
+<Tabs>
+  <TabItem label="Application Folders">
+    **Application-Specific Folders** (e.g., `app1/`, `app2/`)
+
+    Each folder represents a business application and contains:
+    - Application metadata
+    - Module definitions (services and UIs)
+    - Authorization definitions (operations and roles)
+    - Module configurations (optional)
+    - Scheduled job definitions (optional)
+
+    **Example**: `app1/` might represent a "CRM" application with customer management services and UIs.
+  </TabItem>
+
+  <TabItem label="Platform Folder">
+    **Platform Folder** (`platform/`)
+
+    Used to override or customize built-in Platform modules (Shell, Admin UI, etc.):
+    - Shell customizations (branding, layout)
+    - Admin UI configurations
+    - Platform service overrides
+
+    **Note**: You only need to include modules you want to customize, not all platform modules.
+  </TabItem>
+</Tabs>
+
+---
+
+## Using the Bootstrap Library
+
+The bootstrap service uses `@bluealba/pae-bootstrap-lib` to read JSON files and synchronize them with the platform. The library exposes a single function — `bootstrapPlatform` — that handles reading, validating, and sending all definitions to the gateway.
+
+### Installation
+
+```bash
+npm install @bluealba/pae-bootstrap-lib
+```
+
+### The `main.ts` Entry Point
+
+A minimal bootstrap service looks like this:
+
+```typescript
+import { bootstrapPlatform } from '@bluealba/pae-bootstrap-lib';
+import { join } from 'path';
+
+bootstrapPlatform({
+  path: join(__dirname, '../data'),
+  scopedTo: process.env.SERVICE_ACCESS_NAME!,
+  initialDelay: 5000,  // wait 5s for the gateway to be ready
+  retries: 10,         // retry up to 10 times with exponential backoff
+});
+```
+
+The function reads all JSON files from the specified `path`, resolves any `{{$ENV.X}}` expressions, validates the structure, and sends the full platform definition to the gateway via `POST /bootstrap/sync`.
+
+### Options
+
+| Option | Type | Required | Description |
+|---|---|---|---|
+| `scopedTo` | `string` | **Yes** | Identifies this bootstrap service as the author of all entities it creates or updates. Must be unique per product. Typically set via `SERVICE_ACCESS_NAME` env var. |
+| `path` | `string` | No | Path to the folder containing the `data/` structure. Defaults to `process.cwd()`. |
+| `exclude` | `string[]` | No | List of application folder names to skip during synchronization. |
+| `throwOnError` | `boolean` | No | If `true`, propagates errors to the caller. Defaults to `false` — errors are logged internally and the process stays alive. See note below. |
+| `retries` | `number` | No | Number of retry attempts after the initial failure. Uses exponential backoff starting at 5s, doubling each attempt, capped at 5 minutes. Default: `0`. |
+| `initialDelay` | `number` | No | Delay in ms before the first attempt. Useful to wait for the gateway to be ready before bootstrapping. Default: `0`. |
+
+<Aside type="note" title="throwOnError defaults to false">
+  In previous versions, `bootstrapPlatform()` always threw on failure, so callers would typically wrap it in `.catch()` or `try/catch`. The default is now `false` — errors are caught internally, logged, and the process continues running. This is the recommended behavior in containerized environments where the service must keep responding to health checks even if the initial bootstrap fails. If you need the previous behavior — for example in a one-shot init container that should exit non-zero on failure — pass `throwOnError: true` to restore it.
+</Aside>
+
+### Required Environment Variables
+
+The library reads two environment variables at runtime:
+
+| Variable | Description |
+|---|---|
+| `GATEWAY_SERVICE_URL` | Base URL of the platform gateway (e.g. `http://pae-gateway:8080`) |
+| `SERVICE_ACCESS_SECRET` | Bearer token used to authenticate the bootstrap request against the gateway |
+| `SERVICE_ACCESS_NAME` | Identifier used as the `scopedTo` value (conventionally passed into the options) |
+
+<Aside type="caution" title="scopedTo is critical">
+  The `scopedTo` value is used by the platform to track ownership of every entity created by bootstrap. All subsequent runs use it to decide which entities to update or delete. **Never change this value after the first deployment** — doing so will cause the platform to treat all previously bootstrapped entities as orphaned.
+</Aside>
+
+### Complete Example
+
+```typescript
+import { bootstrapPlatform } from '@bluealba/pae-bootstrap-lib';
+import { join } from 'path';
+
+bootstrapPlatform({
+  path: join(__dirname, '../data'),
+  scopedTo: process.env.SERVICE_ACCESS_NAME!,
+  exclude: ['experimental-app'],
+  initialDelay: 5000,
+  retries: 10,
+  // throwOnError defaults to false — errors are logged internally,
+  // the process stays alive and the service keeps responding to health checks
+});
+```
+
+---
+
+## Configuration Files
+
+### Application Definition
+
+Declare application metadata in `application.json`:
+
+```json
+{
+  "name": "crm",
+  "displayName": "Customer Relationship Management",
+  "description": "CRM application for managing customer relationships",
+  "allowedByDefault": false,
+  "allowedTenants": ["tenant-a", "tenant-b"]
+}
+```
+
+**Fields**:
+- **name**: Unique application identifier (kebab-case)
+- **displayName**: Human-readable name shown in the UI
+- **description**: Brief description of the application
+- **allowedByDefault**: If `true`, all users have access by default; if `false` (recommended), access must be explicitly granted
+- **allowedTenants**: Optional array of tenant names allowed to access this application. If omitted, existing tenant restrictions are not modified by bootstrap. If set to an empty array `[]`, all restrictions are cleared (application becomes available to all tenants). If populated, only the listed tenants will have access.
+
+<Aside type="tip" title="Security Best Practice">
+  Set `allowedByDefault` to `false` for business applications to ensure explicit access control. Only platform-wide utilities should default to `true`.
+</Aside>
+
+---
+
+### Tenant Application Restrictions
+
+The `allowedTenants` field in `application.json` lets bootstrap manage which tenants can access each application. This controls the `tenant_application_restrictions` table.
+
+**Semantics**:
+- **`allowedTenants` omitted** — bootstrap does not touch existing restrictions for this application (safe default, no regressions).
+- **`allowedTenants: []`** — all existing restrictions are removed; the application becomes available to all tenants.
+- **`allowedTenants: ["tenant-a", "tenant-b"]`** — restrictions are fully replaced; only the listed tenants have access.
+
+Each bootstrap run performs a full replace (delete + re-insert) when the field is present, so the table always reflects the latest declaration.
+
+```json
+{
+  "name": "crm",
+  "allowedByDefault": false,
+  "allowedTenants": ["acme-corp", "beta-company"]
+}
+```
+
+<Aside type="tip" title="Tenant Names">
+  Use the tenant `name` field (not display name or ID). Bootstrap resolves names to IDs at sync time and logs a warning for any unrecognized tenant names without failing the sync.
+</Aside>
+
+---
+
+### Module Definitions
+
+Define services and UIs in `modules.json`:
+
+<Tabs>
+  <TabItem label="Service Module">
+    **Backend Service (Microservice)**
+
+    ```json
+    [
+      {
+        "name": "@mycompany/crm-service",
+        "displayName": "CRM Service",
+        "type": "service",
+        "baseUrl": "/api/crm",
+        "service": {
+          "host": "crm-service",
+          "port": 4002
+        },
+        "dependsOn": []
+      }
+    ]
+    ```
+
+    **Fields**:
+    - **name**: Module name (matches package.json name)
+    - **displayName**: Human-readable name
+    - **type**: Set to `"service"` for backend services
+    - **baseUrl**: URL prefix for this service's endpoints
+    - **service.host**: Container/service hostname
+    - **service.port**: Service port number
+    - **dependsOn**: Array of module names this service depends on
+  </TabItem>
+
+  <TabItem label="UI Module">
+    **Frontend UI (Micro-frontend)**
+
+    ```json
+    [
+      {
+        "name": "@mycompany/crm-ui",
+        "displayName": "CRM Application",
+        "type": "app",
+        "baseUrl": "/crm-ui",
+        "service": {
+          "host": "crm-ui",
+          "port": 80
+        },
+        "ui": {
+          "route": "/crm",
+          "mountAtSelector": "#pae-shell-ui-content",
+          "bundleFile": "mycompany-crm-ui.js",
+          "customProps": {
+            "theme": "corporate",
+            "features": {
+              "darkMode": true
+            }
+          }
+        },
+        "dependsOn": [
+          "@bluealba/pae-shell-ui"
+        ]
+      }
+    ]
+    ```
+
+    **Fields**:
+    - **type**: Set to `"app"` for UI modules
+    - **ui.route**: Browser route where this UI is accessible
+    - **ui.mountAtSelector**: DOM selector where the UI mounts
+    - **ui.bundleFile**: JavaScript bundle filename
+    - **ui.customProps**: Configuration passed to the UI module as single-spa custom props. Supports an optional `tenantOverrides` key — see [Tenant-Specific customProps Overrides](#tenant-specific-customprops-overrides) for details.
+    - **dependsOn**: Typically depends on `pae-shell-ui`
+  </TabItem>
+</Tabs>
+
+<Aside type="note">
+  See the [Catalog](/architecture/catalog/) documentation for complete module specification reference.
+</Aside>
+
+<Aside type="tip">
+  If your service runs on a different host or port locally than it does inside Docker, use `serviceLocal` to declare the local-only values without touching the `service` field. See [Local Development Overrides](#local-development-overrides-servicelocal) for details.
+</Aside>
+
+---
+
+### Operations Definition
+
+Declare authorization operations in `operations.json`:
+
+```json
+[
+  {
+    "name": "crm.customers.read",
+    "description": "View customer information",
+    "roles": ["CRM User", "CRM Admin"]
+  },
+  {
+    "name": "crm.customers.write",
+    "description": "Create and update customers",
+    "roles": ["CRM Admin"]
+  },
+  {
+    "name": "crm.customers.delete",
+    "description": "Delete customer records",
+    "roles": ["CRM Admin"]
+  }
+]
+```
+
+**Fields**:
+- **name**: Unique operation identifier (use dot notation)
+- **description**: What this operation allows
+- **roles**: Array of role names that include this operation
+
+**Naming Convention**:
+```
+<application>.<resource>.<action>
+
+Examples:
+- crm.customers.read
+- crm.deals.write
+- inventory.products.delete
+- reports.sales.export
+```
+
+---
+
+### Roles Definition
+
+Declare roles in `roles.json`:
+
+```json
+[
+  {
+    "name": "CRM User",
+    "description": "Standard CRM user with read access"
+  },
+  {
+    "name": "CRM Admin",
+    "description": "CRM administrator with full access"
+  }
+]
+```
+
+**Fields**:
+- **name**: Unique role name
+- **description**: What this role represents
+
+**Roles vs Operations**:
+- **Operations**: Granular permissions (e.g., `crm.customers.read`)
+- **Roles**: Groups of operations assigned to users
+- Users are assigned **roles**, which grant them **operations**
+
+---
+
+### Module Configuration Overrides
+
+Override module configurations in `modules-config.json`:
+
+```json
+[
+  {
+    "name": "@bluealba/pae-shell-ui",
+    "config": {
+      "platformName": "My Company Platform",
+      "canToggleNavbarState": true,
+      "isMenuCollapsible": true,
+      "showOpenMenuButton": true,
+      "navbar": {
+        "menus": {
+          "applications": [
+            {
+              "type": "app",
+              "name": "crm",
+              "iconUrl": "/crm-ui/assets/icon.svg"
+            }
+          ]
+        }
+      }
+    }
+  },
+  {
+    "name": "@mycompany/crm-ui",
+    "config": {
+      "defaultView": "dashboard",
+      "enableExport": true
+    }
+  }
+]
+```
+
+**Purpose**:
+- Customize module behavior without modifying module code
+- Set product-specific branding and features
+- Configure UI layouts and behavior
+- Pass environment-specific settings
+
+<Aside type="tip">
+  You don't need to re-declare the entire module definition - only include the `name` and the `config` properties you want to override.
+</Aside>
+
+---
+
+### Tenant-Specific customProps Overrides
+
+The `ui.customProps` object supports an optional reserved key, `tenantOverrides`, that lets you vary the props delivered to a UI module on a per-tenant basis — all from a single module definition.
+
+#### How It Works
+
+When the gateway builds the catalog response for a tenant, it:
+
+1. Reads the module's `ui.customProps` object.
+2. Looks up the current tenant's **name** in the `tenantOverrides` map.
+3. Shallow-merges the matching tenant's overrides on top of the base `customProps`.
+4. Strips the `tenantOverrides` key from the response — clients never see it.
+
+If no entry exists for the current tenant in `tenantOverrides`, the base `customProps` values are returned unchanged (still without the `tenantOverrides` key).
+
+#### Example
+
+```json
+{
+  "name": "@mycompany/crm-ui",
+  "displayName": "CRM Application",
+  "type": "app",
+  "baseUrl": "/crm-ui",
+  "service": {
+    "host": "crm-ui",
+    "port": 80
+  },
+  "ui": {
+    "route": "/crm",
+    "mountAtSelector": "#pae-shell-ui-content",
+    "bundleFile": "mycompany-crm-ui.js",
+    "customProps": {
+      "platformName": "My Company Platform",
+      "canToggleNavbarState": true,
+      "isMenuCollapsible": true,
+      "tenantOverrides": {
+        "acme-corp": {
+          "isMenuCollapsible": false,
+          "platformName": "ACME Platform"
+        }
+      }
+    }
+  },
+  "dependsOn": ["@bluealba/pae-shell-ui"]
+}
+```
+
+When the requesting tenant is `acme-corp`, the gateway returns:
+
+```json
+{
+  "platformName": "ACME Platform",
+  "canToggleNavbarState": true,
+  "isMenuCollapsible": false
+}
+```
+
+When the requesting tenant is anything else, the gateway returns:
+
+```json
+{
+  "platformName": "My Company Platform",
+  "canToggleNavbarState": true,
+  "isMenuCollapsible": true
+}
+```
+
+<Aside type="note" title="Tenant name, not tenant ID">
+  The key inside `tenantOverrides` must match the tenant's **name** (the `name` field on the tenant record), not its numeric ID or its `code`. This is the same value that appears in the tenant list in the Admin UI.
+</Aside>
+
+<Aside type="tip">
+  `tenantOverrides` is most commonly used in `modules-config.json` overrides for platform-level modules such as `@bluealba/pae-shell-ui`, where you want shell behaviour (for example, collapsible menus or branding strings) to differ between tenants without duplicating module definitions.
+</Aside>
+
+---
+
+### Jobs Definition
+
+Declare scheduled jobs for the application in `jobs.json`:
+
+```json
+[
+  {
+    "name": "crm-health-check",
+    "description": "Periodic health check of the CRM service",
+    "enabled": true,
+    "pattern": "*/5 * * * *",
+    "taskType": "HttpInvokerTask",
+    "taskConfig": {
+      "url": "http://crm-service/health",
+      "method": "GET",
+      "timeout": 5000
+    }
+  },
+  {
+    "name": "crm-daily-sync",
+    "description": "Synchronizes CRM data with the external source every day at 2 AM",
+    "enabled": true,
+    "pattern": "0 2 * * *",
+    "taskType": "HttpInvokerTask",
+    "taskConfig": {
+      "url": "http://crm-service/api/sync",
+      "method": "POST",
+      "body": { "type": "full" },
+      "headers": { "Content-Type": "application/json" },
+      "timeout": 30000
+    }
+  }
+]
+```
+
+**Fields**:
+- **name**: Unique job name within the application
+- **description**: Optional human-readable description of the job's purpose
+- **enabled**: Whether the job should be active after synchronization (defaults to `true`)
+- **pattern**: Standard cron expression defining the execution schedule
+- **taskType**: The type of task to execute (currently `"HttpInvokerTask"` is supported)
+- **taskConfig**: Task-specific configuration object
+
+**`taskConfig` fields for `HttpInvokerTask`**:
+- **url**: Full URL of the endpoint to invoke
+- **method**: HTTP method (`GET`, `POST`, `PUT`, `DELETE`, `PATCH`, etc.)
+- **body**: Optional request body (objects are automatically serialized to JSON)
+- **headers**: Optional custom HTTP headers
+- **auth**: Optional authentication configuration (e.g., `{ "authMethod": "bearer", "token": "..." }`)
+- **timeout**: Optional request timeout in milliseconds
+
+**Ownership and Sync Behavior**:
+
+The bootstrap sync engine manages the full lifecycle of jobs it defines. Ownership is tracked via the `updatedBy` field — when bootstrap creates or updates a job it sets both `createdBy` and `updatedBy` to its own `scopedTo` value:
+
+- Jobs in `jobs.json` that do not yet exist are **created** automatically
+- Jobs that already exist and whose `updatedBy` still matches the bootstrap scope are **updated** to match the latest definition
+- Jobs that were previously created by bootstrap but are no longer present in `jobs.json` are **deleted**
+- Jobs that were originally created by bootstrap but have since been manually edited (i.e., `updatedBy` was changed to a user's username via the Admin UI) are **skipped** — a **WARNING** is logged indicating the record was manually modified
+- Jobs whose `createdBy` does not match the bootstrap scope at all are **skipped silently**
+
+<Aside type="note">
+  Editing a job in the Admin UI changes its `updatedBy` field to the editing user's username, which effectively transfers ownership away from bootstrap. Bootstrap will not overwrite those manual changes on subsequent runs. To hand ownership back to bootstrap, delete the job and let bootstrap recreate it from `jobs.json`.
+</Aside>
+
+This same ownership logic applies to all synchronized entities — not only jobs, but also applications, roles, operations, modules, feature flags, and shared libraries.
+
+<Aside type="note">
+  See the [Scheduler Module](/_/docs/architecture/scheduler/) documentation for full details on job types, cron syntax, and dynamic parameter support.
+</Aside>
+
+---
+
+### Feature Flags Definition
+
+Declare feature flags for the application in `feature-flags.json`:
+
+```json
+[
+  {
+    "name": "new-checkout-flow",
+    "description": "Enable the redesigned checkout experience",
+    "visible": true,
+    "defaultValue": false,
+    "valueRules": []
+  },
+  {
+    "name": "beta-reporting",
+    "description": "Enable advanced reporting for beta users",
+    "visible": true,
+    "defaultValue": false,
+    "valueRules": [
+      {
+        "name": "beta-user-access",
+        "condition": {
+          "attribute": "user",
+          "operator": "in",
+          "value": ["beta-user-1@example.com", "beta-user-2@example.com"]
+        },
+        "value": true
+      }
+    ]
+  },
+  {
+    "name": "new-search-experience",
+    "description": "Gradual rollout of the new search UI",
+    "visible": true,
+    "defaultValue": false,
+    "valueRules": [
+      {
+        "name": "acme-10pct-rollout",
+        "condition": {
+          "attribute": "tenant",
+          "operator": "eq",
+          "value": "acme-corp"
+        },
+        "value": true,
+        "rollout": {
+          "percentage": 10,
+          "attribute": "username"
+        }
+      }
+    ]
+  }
+]
+```
+
+**Fields**:
+- **name**: Unique flag identifier (kebab-case, immutable after creation)
+- **description**: Human-readable description of what the flag controls
+- **visible**: Master switch; set to `false` to disable the flag entirely without deleting it
+- **defaultValue**: Value returned when no value rule matches the evaluation context
+- **valueRules**: Ordered list of conditional rules; the first matching rule's value is returned
+
+**Application association**: The flag's application is inferred automatically from the folder that contains the `feature-flags.json` file. The bootstrap library reads the application name from the co-located `application.json` and attaches it to each flag at sync time. You do not include an `applicationName` field in the JSON.
+
+**Upsert semantics**:
+
+The bootstrap operation is idempotent and performs an **upsert** for each flag:
+
+- **Flag does not exist**: Creates the flag with the provided configuration.
+- **Flag already exists**: Updates the flag metadata (`description`, `visible`, `defaultValue`, `application_id` (derived from the enclosing application folder)) and **replaces all existing value rules** with the ones declared in the bootstrap configuration.
+
+All operations for a single bootstrap call run in a single database transaction (all-or-nothing). If any flag fails, the entire bootstrap call is rolled back.
+
+<Aside type="tip">
+Because bootstrap performs a full value rule replacement on existing flags, keep your bootstrap declarations up to date. Removing a value rule from the bootstrap configuration will remove it from the live flag on the next bootstrap run.
+</Aside>
+
+<Aside type="note">
+  See the [Feature Flags guide](/guides/using-feature-flags/) for the full reference on value rules, conditions, operators, and percentage rollouts.
+</Aside>
+
+---
+
+## Environment Variables in Configuration
+
+Bootstrap JSON files support the `{{$ENV.VARIABLE_NAME}}` syntax to inject environment variable values at startup. This lets you write a single set of JSON files that works across all environments — development, staging, and production — without hardcoding hostnames, ports, URLs, or any other value that changes per environment.
+
+### Syntax
+
+The expression language supports four variants:
+
+| Variant | Syntax | Behaviour when variable is missing |
+|---|---|---|
+| Required | `{{$ENV.VARIABLE_NAME}}` | Fails immediately with an error |
+| Optional | `{{$ENV.VARIABLE_NAME?}}` | Returns `undefined`; key is omitted from the parent object |
+| Default | `{{$ENV.VARIABLE_NAME?=default_value}}` | Falls back to the literal `default_value` |
+| Chain | `{{$ENV.VARIABLE_NAME?=$ENV.FALLBACK?=literal}}` | Tries each reference left to right; uses the first that resolves |
+
+The value is read from the environment variable at bootstrap startup time, before any validation occurs.
+
+**Example** — `modules.json` using environment variables for service host and port:
+
+```json
+[
+  {
+    "name": "@mycompany/crm-service",
+    "displayName": "CRM Service",
+    "type": "service",
+    "baseUrl": "/api/crm",
+    "service": {
+      "host": "{{$ENV.CRM_SERVICE_HOST}}",
+      "port": "{{$ENV.CRM_SERVICE_PORT}}"
+    },
+    "dependsOn": []
+  }
+]
+```
+
+When the bootstrap service starts with `CRM_SERVICE_HOST=crm-service` and `CRM_SERVICE_PORT=4002`, the resolved configuration becomes:
+
+```json
+{
+  "host": "crm-service",
+  "port": 4002
+}
+```
+
+### Optional and Default Values
+
+Use the `?` and `?=` suffixes to make expressions tolerant of missing environment variables.
+
+**Example** — `modules-config.json` with a mix of required, optional, default, and chained expressions:
+
+```json
+{
+  "host": "{{$ENV.CRM_HOST}}",
+  "port": "{{$ENV.CRM_PORT?=4002}}",
+  "debugPort": "{{$ENV.DEBUG_PORT?}}",
+  "logLevel": "{{$ENV.LOG_LEVEL?=$ENV.DEFAULT_LOG_LEVEL?=info}}"
+}
+```
+
+Given that only `CRM_HOST=crm-service` is set in the environment and none of the others are, the resolved configuration becomes:
+
+```json
+{
+  "host": "crm-service",
+  "port": 4002,
+  "logLevel": "info"
+}
+```
+
+What happened to each field:
+- **`host`** — resolved normally from the required `CRM_HOST` variable.
+- **`port`** — `CRM_PORT` was not set, so the literal default `4002` was used and coerced to a number.
+- **`debugPort`** — `DEBUG_PORT` was not set and the expression is optional (`?`), so the key is **omitted entirely** from the resolved object.
+- **`logLevel`** — `LOG_LEVEL` was not set, then `DEFAULT_LOG_LEVEL` was not set, so the chain fell through to the literal `"info"`.
+
+**Default value type coercion**
+
+Literal defaults go through the same coercion rules as regular env var values:
+
+| Expression | Default literal | Resolved as |
+|---|---|---|
+| `"{{$ENV.PORT?=8080}}"` | `8080` | `8080` (number) |
+| `"{{$ENV.ENABLED?=true}}"` | `true` | `true` (boolean) |
+| `"{{$ENV.HOST?=localhost}}"` | `localhost` | `"localhost"` (string) |
+
+**Fallback chain references**
+
+References inside a fallback chain can use any registered namespace, not just `ENV`. The engine tries each segment from left to right and uses the first one that resolves successfully.
+
+```json
+{
+  "serviceUrl": "{{$ENV.SERVICE_URL?=$ENV.LEGACY_SERVICE_URL?=http://default-service}}"
+}
+```
+
+---
+
+### Resolution Modes
+
+<Tabs>
+  <TabItem label="Full-value">
+    When the entire JSON string value is a single `{{$ENV.X}}` expression, the result is **automatically coerced to the correct type**:
+
+    | JSON value | Env var value | Resolved as |
+    |---|---|---|
+    | `"{{$ENV.PORT}}"` | `"4002"` | `4002` (number) |
+    | `"{{$ENV.ENABLED}}"` | `"true"` | `true` (boolean) |
+    | `"{{$ENV.ENABLED}}"` | `"false"` | `false` (boolean) |
+    | `"{{$ENV.HOST}}"` | `"crm-service"` | `"crm-service"` (string) |
+
+    This means you can use environment variables for numeric fields like `port` without any extra casting — just write the expression and the bootstrap system handles the type.
+  </TabItem>
+
+  <TabItem label="Inline (embedded in text)">
+    When the expression is embedded inside a larger string, it always resolves as a string:
+
+    ```json
+    {
+      "url": "http://{{$ENV.CRM_HOST}}:{{$ENV.CRM_PORT}}/api/v1"
+    }
+    ```
+
+    With `CRM_HOST=crm-service` and `CRM_PORT=4002`:
+
+    ```json
+    {
+      "url": "http://crm-service:4002/api/v1"
+    }
+    ```
+
+    Multiple expressions can appear in the same string value.
+
+    When an optional inline expression (`?`) resolves to `undefined`, it collapses to an empty string `""` rather than omitting the key (key omission only applies to full-value mode).
+  </TabItem>
+
+  <TabItem label="Optional and Default">
+    The `?` and `?=` suffixes control what happens when a variable is not set:
+
+    | JSON value | Env var value | Resolved as |
+    |---|---|---|
+    | `"{{$ENV.PORT?=4002}}"` | not set | `4002` (number, from default) |
+    | `"{{$ENV.ENABLED?=true}}"` | not set | `true` (boolean, from default) |
+    | `"{{$ENV.HOST?}}"` | not set | key omitted (optional, full-value mode) |
+    | `"{{$ENV.HOST?=fallback}}"` | `"my-host"` | `"my-host"` (env var wins over default) |
+
+    Default literals undergo the same type coercion as live env var values — a default of `4002` is returned as the number `4002`, not the string `"4002"`.
+
+    When the env var is present, it always takes precedence over any default or fallback in the chain.
+  </TabItem>
+</Tabs>
+
+### Practical Example: Multi-Environment Setup
+
+The same JSON files work in all environments by changing only the environment variables:
+
+<Tabs>
+  <TabItem label="modules.json">
+    ```json
+    [
+      {
+        "name": "@mycompany/crm-service",
+        "displayName": "CRM Service",
+        "type": "service",
+        "baseUrl": "/api/crm",
+        "service": {
+          "host": "{{$ENV.CRM_SERVICE_HOST}}",
+          "port": "{{$ENV.CRM_SERVICE_PORT}}"
+        },
+        "dependsOn": []
+      }
+    ]
+    ```
+  </TabItem>
+
+  <TabItem label="Development">
+    ```bash
+    # docker-compose.yml (dev)
+    CRM_SERVICE_HOST=crm-service
+    CRM_SERVICE_PORT=4002
+    ```
+  </TabItem>
+
+  <TabItem label="Staging">
+    ```bash
+    # docker-compose.yml (staging)
+    CRM_SERVICE_HOST=crm-staging.internal
+    CRM_SERVICE_PORT=443
+    ```
+  </TabItem>
+
+  <TabItem label="Production">
+    ```bash
+    # docker-compose.yml (production)
+    CRM_SERVICE_HOST=crm.internal.prod
+    CRM_SERVICE_PORT=443
+    ```
+  </TabItem>
+</Tabs>
+
+<Aside type="caution" title="Required variables must be defined">
+  This only applies to **required** expressions (no `?` or `?=` suffix). If the bootstrap service starts and a required environment variable is not set, the bootstrap process will **fail immediately** with an error like:
+
+  ```
+  Error reading modules.json file: Expression resolution failed: {{$ENV.CRM_SERVICE_HOST}} is not defined in environment variables
+  ```
+
+  Make sure every required `{{$ENV.X}}` expression has a corresponding environment variable configured in your Docker Compose file or container environment.
+
+  Optional expressions (`{{$ENV.X?}}`) and expressions with defaults (`{{$ENV.X?=value}}`) will **not** fail if the variable is missing — they either omit the key or fall back to the provided default.
+</Aside>
+
+<Aside type="tip" title="Supported in all configuration files">
+  The `{{$ENV.X}}` syntax works in every bootstrap JSON file:
+  `application.json`, `modules.json`, `operations.json`, `roles.json`, `modules-config.json`, `jobs.json`, and `shared-libraries.json`.
+</Aside>
+
+---
+
+## Local Development Overrides (serviceLocal)
+
+When running the platform locally, Docker service hostnames (such as `crm-service` or `habits-service`) do not resolve on the developer's machine. The gateway bootstrap sends those hostnames to the platform, so any request it proxies will fail because `crm-service` is not reachable from the host network.
+
+The usual workaround is to set `{{$ENV.*}}` expressions on every `service` field that differs between Docker and local development. The `serviceLocal` feature provides a simpler, more declarative alternative.
+
+### How It Works
+
+Each module in `modules.json` accepts an optional `serviceLocal` field. It has the same shape as the `service` field (`Partial<ServiceConfig>`), so you only need to include the properties that differ locally.
+
+When the bootstrap library starts:
+
+- If `LOCAL_MODE=true`, `serviceLocal` is **shallow-merged into `service`**, replacing any overlapping fields. The merged result is what gets sent to the gateway.
+- In all other cases (including when `LOCAL_MODE` is absent or set to any other value), `serviceLocal` is **silently stripped** and the original `service` definition is used unchanged.
+
+The gateway never receives the `serviceLocal` field regardless of mode.
+
+### Example
+
+```json
+[
+  {
+    "name": "@mycompany/crm-service",
+    "displayName": "CRM Service",
+    "type": "service",
+    "baseUrl": "/api/crm",
+    "service": {
+      "host": "crm-service",
+      "port": 80
+    },
+    "serviceLocal": {
+      "host": "host.docker.internal",
+      "port": 3001
+    },
+    "dependsOn": []
+  }
+]
+```
+
+With `LOCAL_MODE=true`, the resolved `service` sent to the gateway becomes:
+
+```json
+{
+  "host": "host.docker.internal",
+  "port": 3001
+}
+```
+
+Without `LOCAL_MODE` (or with any value other than `'true'`), the original `service` is used:
+
+```json
+{
+  "host": "crm-service",
+  "port": 80
+}
+```
+
+### ServiceConfig Fields
+
+Both `service` and `serviceLocal` accept the following fields:
+
+| Field | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `host` | `string` | Yes (in `service`) | — | Hostname or IP address the gateway uses to reach the service |
+| `port` | `number` | Yes (in `service`) | — | Port number the gateway connects to |
+| `protocol` | `string` | No | `"http"` | Transport protocol. Set to `"https"` if the service uses TLS |
+| `includeBaseURL` | `boolean` | No | `false` | When `true`, the module's `baseUrl` path is forwarded as-is to the service instead of being stripped |
+
+In `serviceLocal`, all fields are optional — only include the ones that differ from the Docker definition.
+
+### Behavior Summary
+
+| Condition | `serviceLocal` present | Result |
+|---|---|---|
+| `LOCAL_MODE=true` | Yes | `serviceLocal` shallow-merged into `service`; merged value sent to gateway |
+| `LOCAL_MODE=true` | No | `service` sent to gateway unchanged |
+| `LOCAL_MODE` not set or not `'true'` | Yes | `serviceLocal` stripped; original `service` sent to gateway |
+| `LOCAL_MODE` not set or not `'true'` | No | `service` sent to gateway unchanged |
+
+<Aside type="note">
+  `{{$ENV.*}}` expressions work inside `serviceLocal` values just as they do inside `service`. You can use expressions such as `"{{$ENV.CRM_LOCAL_PORT?=4002}}"` within `serviceLocal` to keep local port numbers out of version control.
+</Aside>
+
+<Aside type="caution" title="LOCAL_MODE is case-sensitive">
+  The bootstrap library checks for the exact string `'true'`. Values such as `TRUE`, `True`, or `1` will not activate local mode. Set the variable as `LOCAL_MODE=true` in your local environment or `.env` file.
+</Aside>
+
+---
+
+## Bootstrap Execution
+
+### Startup Sequence
+
+When the bootstrap service starts:
+
+```
+┌─────────────────────────────────────────────────────────┐
+│ 1. Bootstrap Service Starts                             │
+│    • Reads all JSON files from data/ directory          │
+│    • Parses and validates JSON structure                │
+└────────────────────┬────────────────────────────────────┘
+                     │
+                     ▼
+┌─────────────────────────────────────────────────────────┐
+│ 2. Synchronize Catalog                                  │
+│    • Compare modules.json with existing catalog         │
+│    • Create new modules, update existing ones           │
+│    • Apply module-config.json overrides                 │
+└────────────────────┬────────────────────────────────────┘
+                     │
+                     ▼
+┌─────────────────────────────────────────────────────────┐
+│ 3. Synchronize Shared Libraries                         │
+│    • Register UI shared libraries                       │
+│    • Update library versions                            │
+└────────────────────┬────────────────────────────────────┘
+                     │
+                     ▼
+┌─────────────────────────────────────────────────────────┐
+│ 4. Synchronize Applications                             │
+│    • Create/update application records                  │
+│    • Set application metadata                           │
+└────────────────────┬────────────────────────────────────┘
+                     │
+                     ▼
+┌─────────────────────────────────────────────────────────┐
+│ 5. Synchronize Roles                                    │
+│    • Create new roles                                   │
+│    • Update role descriptions                           │
+└────────────────────┬────────────────────────────────────┘
+                     │
+                     ▼
+┌─────────────────────────────────────────────────────────┐
+│ 6. Synchronize Operations                               │
+│    • Create new operations                              │
+│    • Bind operations to roles                           │
+│    • Update operation descriptions                      │
+└────────────────────┬────────────────────────────────────┘
+                     │
+                     ▼
+┌─────────────────────────────────────────────────────────┐
+│ 7. Synchronize Scheduled Jobs                           │
+│    • Create new jobs from bootstrap definitions         │
+│    • Update existing bootstrap-owned jobs               │
+│    • Delete bootstrap-owned jobs no longer defined      │
+│    • Skip jobs owned by other sources                   │
+└────────────────────┬────────────────────────────────────┘
+                     │
+                     ▼
+┌─────────────────────────────────────────────────────────┐
+│ 7.5. Synchronize Tenant Application Restrictions        │
+│    • For each app with allowedTenants defined:          │
+│      - Delete existing restrictions for the app         │
+│      - Re-insert rows for resolved tenant names         │
+│    • Apps without allowedTenants are skipped            │
+└────────────────────┬────────────────────────────────────┘
+                     │
+                     ▼
+┌─────────────────────────────────────────────────────────┐
+│ 8. Synchronize Feature Flags                            │
+│    • Create/update feature flags from feature-flags.json│
+│    • Replace value rules for existing flags             │
+│    • Delete bootstrap-owned flags no longer defined     │
+└────────────────────┬────────────────────────────────────┘
+                     │
+                     ▼
+┌─────────────────────────────────────────────────────────┐
+│ 9. Bootstrap Complete                                   │
+│    • Log summary of changes                             │
+│    • Service ready to handle requests                   │
+└─────────────────────────────────────────────────────────┘
+```
+
+### Example Output
+
+```log
+2025-01-09 09:54:08 > platform-bootstrap-service@1.0.0 start
+2025-01-09 09:54:10 [nodemon] starting `ts-node src/main.ts`
+2025-01-09 09:54:40 Server listening on Port 80
+2025-01-09 09:54:45 Synchronizing Catalog - START ...
+2025-01-09 09:54:47 Synchronizing Catalog - COMPLETED
+2025-01-09 09:54:47 Synchronizing shared-libraries - START ...
+2025-01-09 09:54:48 >>> shared-libraries to ADD []
+2025-01-09 09:54:48 >>> shared-libraries to UPDATE []
+2025-01-09 09:54:48 Synchronizing shared-libraries - COMPLETED
+2025-01-09 09:54:48 Synchronizing authorization-applications - START ...
+2025-01-09 09:54:52 >>> authorization-applications to ADD []
+2025-01-09 09:54:52 >>> authorization-applications to UPDATE ['crm', 'inventory']
+2025-01-09 09:54:53 Synchronizing authorization-applications - COMPLETED
+2025-01-09 09:54:53 Synchronizing authorization-roles - START ...
+2025-01-09 09:54:53 >>> authorization-roles to ADD ['CRM User']
+2025-01-09 09:54:53 >>> authorization-roles to UPDATE []
+2025-01-09 09:54:53 Synchronizing authorization-roles - COMPLETED
+2025-01-09 09:54:53 Synchronizing authorization-operations - START ...
+2025-01-09 09:54:53 >>> authorization-operations to ADD ['crm.customers.read']
+2025-01-09 09:54:53 >>> authorization-operations to UPDATE []
+2025-01-09 09:54:53 Synchronizing authorization-operations - COMPLETED
+2025-01-09 09:54:53 Synchronizing scheduled-jobs - START ...
+2025-01-09 09:54:53 [Bootstrap] Created job 'crm-daily-sync'
+2025-01-09 09:54:53 [Bootstrap] Updated job 'crm-health-check'
+2025-01-09 09:54:53 Synchronizing scheduled-jobs - COMPLETED
+```
+
+---
+
+## Development Workflow
+
+### Making Changes
+
+1. **Edit JSON Files**: Modify the appropriate JSON file in the `data/` directory
+
+   ```bash
+   # Example: Add a new operation
+   vim data/crm/operations.json
+   ```
+
+2. **Restart Bootstrap Service**: Changes are applied automatically on restart
+
+   ```bash
+   # Docker Compose
+   docker-compose restart platform-bootstrap-service
+
+   # Or with Turbo (for development)
+   npm run dev --workspace=platform-bootstrap-service
+   ```
+
+3. **Verify Changes**: Check the service logs to confirm synchronization
+
+4. **Commit to Version Control**: Push changes to share with the team
+
+   ```bash
+   git add data/
+   git commit -m "Add CRM customer operations"
+   git push
+   ```
+
+### Environment Propagation
+
+The same bootstrap configuration is used across all environments:
+
+```
+Development → Staging → Production
+     ↓            ↓          ↓
+  Same JSON   Same JSON  Same JSON
+     ↓            ↓          ↓
+Bootstrap service automatically synchronizes on startup
+```
+
+**Benefits**:
+- Consistent configuration across environments — the same JSON files deploy everywhere
+- Use `{{$ENV.VARIABLE_NAME}}` in any JSON value to inject environment-specific values (hostnames, ports, URLs) without duplicating files
+- Version-controlled platform state
+- Easy rollback via Git
+- No manual database updates needed
+
+---
+
+## Common Patterns
+
+### Adding a New Application
+
+<Tabs>
+  <TabItem label="1. Create Folder">
+    ```bash
+    mkdir -p data/my-new-app
+    cd data/my-new-app
+    ```
+  </TabItem>
+
+  <TabItem label="2. Define Application">
+    Create `application.json`:
+    ```json
+    {
+      "name": "my-new-app",
+      "displayName": "My New Application",
+      "description": "Description of the new application",
+      "allowedByDefault": false,
+      "allowedTenants": ["my-tenant"]
+    }
+    ```
+  </TabItem>
+
+  <TabItem label="3. Add Modules">
+    Create `modules.json`:
+    ```json
+    [
+      {
+        "name": "@mycompany/my-new-app-service",
+        "displayName": "My New App Service",
+        "type": "service",
+        "baseUrl": "/api/my-new-app",
+        "service": {
+          "host": "my-new-app-service",
+          "port": 4010
+        }
+      },
+      {
+        "name": "@mycompany/my-new-app-ui",
+        "displayName": "My New App UI",
+        "type": "app",
+        "baseUrl": "/my-new-app-ui",
+        "service": {
+          "host": "my-new-app-ui",
+          "port": 80
+        },
+        "ui": {
+          "route": "/my-app",
+          "mountAtSelector": "#pae-shell-ui-content",
+          "bundleFile": "mycompany-my-new-app-ui.js"
+        },
+        "dependsOn": ["@bluealba/pae-shell-ui"]
+      }
+    ]
+    ```
+  </TabItem>
+
+  <TabItem label="4. Add Authorization">
+    Create `operations.json`:
+    ```json
+    [
+      {
+        "name": "my-new-app.read",
+        "description": "View my new app",
+        "roles": ["User"]
+      },
+      {
+        "name": "my-new-app.write",
+        "description": "Edit my new app",
+        "roles": ["Admin"]
+      }
+    ]
+    ```
+
+    Create `roles.json`:
+    ```json
+    [
+      {
+        "name": "My App User",
+        "description": "Standard user of my new app"
+      }
+    ]
+    ```
+  </TabItem>
+
+  <TabItem label="5. Add Jobs (Optional)">
+    Create `jobs.json` to define recurring scheduled tasks for the application:
+    ```json
+    [
+      {
+        "name": "my-new-app-health-check",
+        "description": "Periodic health check of the my-new-app service",
+        "enabled": true,
+        "pattern": "*/5 * * * *",
+        "taskType": "HttpInvokerTask",
+        "taskConfig": {
+          "url": "http://my-new-app-service:4010/health",
+          "method": "GET",
+          "timeout": 5000
+        }
+      }
+    ]
+    ```
+
+    Jobs are owned by the bootstrap scope: they will be created, updated, or deleted automatically as the `jobs.json` file changes.
+  </TabItem>
+
+  <TabItem label="6. Restart Bootstrap">
+    ```bash
+    docker-compose restart platform-bootstrap-service
+
+    # Watch logs
+    docker-compose logs -f platform-bootstrap-service
+    ```
+  </TabItem>
+</Tabs>
+
+---
+
+## Best Practices
+
+<CardGrid>
+  <Card title="Use Version Control" icon="github">
+    Always commit bootstrap configurations to Git for history and collaboration
+  </Card>
+
+  <Card title="Follow Naming Conventions" icon="pencil">
+    Use consistent naming: kebab-case for names, dot notation for operations
+  </Card>
+
+  <Card title="Document Changes" icon="document">
+    Include clear descriptions for all operations, roles, and applications
+  </Card>
+
+  <Card title="Test Before Production" icon="approve-check">
+    Verify bootstrap changes in development before deploying to production
+  </Card>
+
+  <Card title="Minimal Permissions" icon="shield">
+    Set `allowedByDefault: false` and grant explicit access as needed
+  </Card>
+
+  <Card title="Organize by Application" icon="seti:folder">
+    Keep each application's definitions in its own folder for clarity
+  </Card>
+</CardGrid>
+
+---
+
+## Troubleshooting
+
+### Bootstrap Service Won't Start
+
+**Check logs for errors**:
+```bash
+docker-compose logs platform-bootstrap-service
+```
+
+**Common causes**:
+- Invalid JSON syntax
+- Missing required fields
+- Duplicate names
+- Network connectivity to Platform APIs
+
+### Changes Not Applied
+
+**Verify the bootstrap service restarted**:
+```bash
+docker-compose ps platform-bootstrap-service
+```
+
+**Check synchronization logs**:
+```bash
+docker-compose logs platform-bootstrap-service | grep "Synchronizing"
+```
+
+### Module Not Appearing in Catalog
+
+**Check module definition**:
+- Verify `name` is unique
+- Confirm `service.host` and `service.port` are correct
+- Ensure `dependsOn` modules exist
+
+**Verify module is accessible**:
+```bash
+# Test service endpoint
+curl http://my-new-app-service:4010/health
+```
+
+### Operations Not Working
+
+**Verify operation binding**:
+- Check operation name matches in `operations.json`
+- Confirm role is listed in operation's `roles` array
+- Verify users have the role assigned
+
+**Test authorization**:
+```bash
+# Get user's authorized resources
+curl https://platform.com/authz/users/{username}/resources
+```
+
+### Environment Variable Not Resolved
+
+**Error message**:
+```
+Error reading <file>.json file: Expression resolution failed: {{$ENV.VARIABLE_NAME}} is not defined in environment variables
+```
+
+**Check that the variable is set** in the bootstrap service container:
+```bash
+docker-compose exec platform-bootstrap-service env | grep VARIABLE_NAME
+```
+
+**Common causes**:
+- Variable not declared in the `environment:` or `env_file:` section of the bootstrap service in `docker-compose.yml`
+- Typo in the variable name in the JSON file
+- `.env` file not loaded or missing
+
+**Make expressions tolerant of missing variables**:
+
+If a variable is genuinely optional (e.g. a debug port that is only relevant in some environments), use the `?` or `?=` suffixes instead of requiring the variable to always be present:
+
+```json
+{
+  "port": "{{$ENV.CRM_PORT?=4002}}",
+  "debugPort": "{{$ENV.DEBUG_PORT?}}",
+  "logLevel": "{{$ENV.LOG_LEVEL?=$ENV.DEFAULT_LOG_LEVEL?=info}}"
+}
+```
+
+- `?=4002` — uses `4002` when `CRM_PORT` is not set (no error, no missing key)
+- `?` — omits the `debugPort` key entirely when `DEBUG_PORT` is not set
+- `?=$ENV.DEFAULT_LOG_LEVEL?=info` — tries a fallback variable, then a literal default
+
+---
+
+## Migration from Old Bootstrap
+
+If migrating from an older bootstrap structure:
+
+1. **Review Current Definitions**: Export existing catalog and authorization data
+2. **Create New Structure**: Organize by application following the new folder structure
+3. **Test Synchronization**: Run bootstrap in development environment
+4. **Validate Results**: Verify all modules and operations are correctly registered
+5. **Deploy**: Roll out to staging and production
+
+---
+
+## Next Steps
+
+- **[Catalog Architecture](/_/docs/architecture/catalog/)** - Understanding the application catalog
+- **[Authorization System](/_/docs/architecture/authorization-system/)** - Deep dive into roles and operations
+- **[Shell Customization](/_/docs/architecture/shell/)** - Customizing the Platform Shell via bootstrap
+- **[Scheduler Module](/_/docs/architecture/scheduler/)** - Full reference for job types, cron syntax, and dynamic parameters
+- **[Feature Flags](/guides/using-feature-flags/)** - Using feature flags in services and React applications