@fluentcommerce/fc-connect-sdk 0.1.48 → 0.1.52

package/docs/versori-apis/VERSORI-PLATFORM-ARCHITECTURE.md

@@ -1,880 +0,0 @@
-# Versori Platform Architecture & Data Model
-
-**Complete Guide to Understanding Versori Platform Entities and Their Relationships**
-
----
-
-## Table of Contents
-
-1. [Overview](#overview)
-2. [Entity Hierarchy](#entity-hierarchy)
-3. [Core Entities](#core-entities)
-4. [Relationships & Dependencies](#relationships--dependencies)
-5. [API Endpoints by Entity](#api-endpoints-by-entity)
-6. [Common Workflows](#common-workflows)
-7. [Data Flow Examples](#data-flow-examples)
-
----
-
-## Overview
-
-The Versori Platform is organized around **Organisations** that contain **Projects**, **Systems**, **Connections**, **Users**, **Activations**, **Automations**, **Schedulers**, **Issues**, **Notifications**, **Metrics**, and **KV Store**. Understanding how these entities relate is crucial for building integrations.
-
-### Key Concepts
-
-- **Organisation**: Top-level container (tenant)
-- **Project**: Code/workflows deployed to environments
-- **System**: External integration definition (Salesforce, S3, etc.)
-- **Connection**: Credentials linking a System to an Environment
-- **End User**: Your customer/user
-- **Activation**: Links a User to an Environment with user-specific config
-- **Environment**: Deployment target for a Project (production, staging, etc.)
-- **Automation**: Workflow automation with recording/transcription capabilities
-- **Scheduler**: Cron/timer-based scheduled workflow execution
-- **Issue**: Bug tracking and monitoring
-- **Notification**: Alert and notification channels
-- **Metrics**: Usage analytics and summaries
-- **KV Store**: Key-value state management and persistence
-
----
-
-## Entity Hierarchy
-
-```
-Organisation (Top Level)
-│
-├── Projects
-│   ├── Environments (created on deployment)
-│   ├── Variable Schema (defines allowed variables)
-│   ├── Files (TypeScript code/workflows)
-│   └── Connection Templates (predefined connection configs)
-│
-├── Systems
-│   ├── Actions (what you can do)
-│   └── Triggers (what can trigger workflows)
-│
-├── Connections
-│   └── Links: System + Environment
-│   └── Contains: Credentials + Configuration
-│
-├── End Users
-│   └── Identified by: externalId (immutable)
-│
-├── Activations
-│   └── Links: User + Environment
-│   └── Contains: Dynamic Variables (user-specific config)
-│   └── Requires: Connections for all environment systems
-│
-├── Automations
-│   ├── Runs (execution tracking)
-│   └── Recordings & Transcriptions
-│
-├── Schedulers
-│   └── Environment-scoped scheduled workflows
-│
-├── Issues
-│   └── Bug tracking and monitoring
-│
-├── Notifications
-│   ├── Notification Channels (organisation-scoped)
-│   └── Project Notifications (project-scoped)
-│
-├── Metrics
-│   └── Usage analytics and summaries
-│
-└── KV Store
-    └── Key-value state management
-```
-
----
-
-## Entity Distinctions: What's the Difference?
-
-Understanding the difference between these entities is critical. Here's a clear breakdown:
-
-### System vs Connection vs Project vs Activation
-
-| Entity | **What It Is** | **Analogy** | **Scope** | **Contains** |
-|--------|---------------|-------------|-----------|--------------|
-| **System** | Definition of an external service (Salesforce, S3, Shopify) | The "blueprint" or "specification" | Organisation-wide (shared) | Actions, Triggers, Auth schemes |
-| **Connection** | Credentials + config linking a System to an Environment | The "actual login credentials" | Organisation → Environment | OAuth tokens, API keys, baseUrl |
-| **Project** | Your integration code/workflows | The "application" you're building | Organisation → Project | TypeScript files, Variable Schema |
-| **Environment** | Deployment target (prod, staging) | Where your app runs | Project → Environment | Deployed files, status, config |
-| **Activation** | User-specific setup linking User to Environment | Per-customer configuration | User → Environment | Dynamic variables, user's connections |
-
-### Key Distinctions
-
-**System vs Connection:**
-- **System** = "What is Salesforce?" (the definition)
-- **Connection** = "Here are my Salesforce credentials" (the actual credentials)
-- One System can have many Connections (different credentials for different environments/users)
-
-**Project vs Environment:**
-- **Project** = Your code repository (the TypeScript files)
-- **Environment** = Where it's deployed (production, staging, dev)
-- One Project can have multiple Environments
-
-**Connection vs Activation:**
-- **Connection** = Credentials for a System in an Environment (can be shared)
-- **Activation** = User's specific setup (links User + Environment + Connections + Variables)
-- Connections are reusable; Activations are per-user
-
-**Example Flow:**
-```
-1. Create System "Salesforce" (defines what Salesforce is)
-2. Create Project "Order Sync" (your code)
-3. Deploy Project → Creates Environment "production"
-4. Create Connection "Salesforce-Prod" (your Salesforce credentials) → Links System(Salesforce) + Environment(production)
-5. Create User "customer-123"
-6. Create Activation → Links User(customer-123) + Environment(production) + Connection(Salesforce-Prod) + Variables
-```
-
----
-
-## Core Entities
-
-### 1. Organisation
-
-**What it is**: The top-level tenant/container for all resources.
-
-**API Path**: `/o/{organisation_id}/...`
-
-**Key Characteristics**:
-- All entities belong to an organisation
-- Organisation ID is required in all API calls
-- Acts as the security boundary
-
-**API Endpoints**:
-- No direct CRUD operations (managed by Versori)
-- All operations are scoped under `/o/{organisation_id}/`
-
----
-
-### 2. Projects
-
-**What it is**: A collection of code/workflows (TypeScript files) that define integration logic.
-
-**API Path**: `/o/{organisation_id}/projects`
-
-**Key Characteristics**:
-- Contains TypeScript files (workflows, functions, schedules)
-- Has a **Variable Schema** that defines what dynamic variables can be set
-- Contains **Environments** (created when deployed)
-- Can be cloned, validated, and deployed
-
-**Entity Structure**:
-```typescript
-Project {
-  id: string
-  name: string
-  environments: ProjectEnvironment[]  // Created on deployment
-  dynamicVariablesSchema: DynamicVariablesSchema
-  currentFiles: Files
-  settings: ProjectSettings
-  metadata: ProjectMetadata
-}
-```
-
-**API Endpoints**:
-- `GET /o/{organisation_id}/projects` - List all projects
-- `POST /o/{organisation_id}/projects` - Create project
-- `GET /o/{organisation_id}/projects/{project_id}` - Get project details
-- `PUT /o/{organisation_id}/projects/{project_id}` - Update project
-- `DELETE /o/{organisation_id}/projects/{project_id}` - Delete project
-- `POST /o/{organisation_id}/projects/{project_id}/clone` - Clone project
-- `GET /o/{organisation_id}/projects/{project_id}/variables` - Get variable schema
-- `PUT /o/{organisation_id}/projects/{project_id}/variables` - Set variable schema
-- `PATCH /o/{organisation_id}/projects/{project_id}/variables` - Patch variable schema
-- `GET /o/{organisation_id}/projects/{project_id}/files` - Get project files
-- `PUT /o/{organisation_id}/projects/{project_id}/files` - Update project files
-- `PUT /o/{organisation_id}/projects/{project_id}/deploy` - Deploy to environment
-- `PUT /o/{organisation_id}/projects/{project_id}/versions/{version_id}/deploy` - Deploy specific version
-- `POST /o/{organisation_id}/projects/{project_id}/suspend` - Suspend project
-- `POST /o/{organisation_id}/projects/{project_id}/sentiment` - Add project sentiment
-- `POST /o/{organisation_id}/projects/{project_id}/testing/start` - Start test container
-- `POST /o/{organisation_id}/projects/{project_id}/testing/trigger/{trigger_name}` - Trigger workflow
-- `PUT /o/{organisation_id}/projects/{project_id}/validate` - Validate files
-- `GET /o/{organisation_id}/projects/{project_id}/logs` - Get logs
-- `GET /o/{organisation_id}/projects/{project_id}/traces` - List traces
-- `GET /o/{organisation_id}/projects/{project_id}/traces/{trace_id}` - Get trace
-- `GET /o/{organisation_id}/projects/{project_id}/workflows` - List integration flows
-- `GET /o/{organisation_id}/projects/{project_id}/workflows/{flow_name}` - Get flow
-- `PUT /o/{organisation_id}/projects/{project_id}/workflows/{flow_name}` - Update flow
-- `DELETE /o/{organisation_id}/projects/{project_id}/workflows/{flow_name}` - Delete flow
-- `GET /o/{organisation_id}/projects/{project_id}/connection-templates` - List connection templates
-- `POST /o/{organisation_id}/projects/{project_id}/connection-templates` - Create connection template
-- `PUT /o/{organisation_id}/projects/{project_id}/connection-templates/{template_id}` - Update template
-- `DELETE /o/{organisation_id}/projects/{project_id}/connection-templates/{template_id}` - Delete template
-
----
-
-### 3. Environments
-
-**What it is**: A deployment target for a project (e.g., "production", "staging", "development").
-
-**API Path**: `/o/{organisation_id}/environments/{environment_id}`
-
-**Key Characteristics**:
-- Belongs to a Project (returned as part of Project object)
-- Has a status: `running`, `suspended`, `error`, or `draft`
-- Contains deployed files
-- Has configuration (infrastructure settings)
-- Has `lastDeployedAt` timestamp
-
-**Note**: The API documentation doesn't explicitly state that environments are created on deployment, but environments are returned as part of the Project object and deployment endpoints reference environments by name/ID.
-
-**Entity Structure**:
-```typescript
-ProjectEnvironment {
-  id: string
-  name: string
-  status: "running" | "suspended" | "error" | "draft"
-  publicUrl: string
-  files?: File[]  // Optional array
-  labels?: Labels
-  config: EnvironmentConfig
-  createdAt: string
-  updatedAt: string
-  lastDeployedAt: string  // Required field
-}
-```
-
-**API Endpoints**:
-- Environments are managed through Project endpoints
-- `PATCH /o/{organisation_id}/environments/{environment_id}/config` - Update environment config
-- `GET /o/{organisation_id}/environments/{environment_id}/activations` - List activations
-- `GET /o/{organisation_id}/environments/{environment_id}/schedulers` - List schedulers
-- `GET /o/{organisation_id}/environments/{environment_id}/schedulers/{scheduler_id}` - Get scheduler
-- `POST /o/{organisation_id}/environments/{environment_id}/schedulers/{scheduler_id}` - Trigger scheduler
-
----
-
-### 4. Systems
-
-**What it is**: A definition of an external integration (e.g., Salesforce, S3, SFTP, Shopify).
-
-**API Path**: `/o/{organisation_id}/systems`
-
-**Key Characteristics**:
-- Organisation-scoped (shared across projects)
-- Defines **Actions** (what you can do with the system)
-- Defines **Triggers** (what can trigger workflows)
-- Can be linked to projects via actions/triggers
-
-**Note**: Connection Templates are managed under Projects, not Systems (see Projects section).
-
-**Entity Structure**:
-```typescript
-System {
-  id: string
-  name: string
-  domain: string
-  templateBaseUrl: string
-  authSchemeConfigs: AuthSchemeConfig[]
-}
-```
-
-**Note**: Actions, Triggers, and Connection Templates are managed separately via their own endpoints - they are not direct properties of the System object.
-
-**API Endpoints**:
-- `GET /o/{organisation_id}/systems` - List systems
-- `POST /o/{organisation_id}/systems` - Create system
-- `GET /o/{organisation_id}/systems/{system_id}` - Get system
-- `PUT /o/{organisation_id}/systems/{system_id}` - Update system
-- `GET /o/{organisation_id}/systems/{system_id}/actions` - List actions
-- `POST /o/{organisation_id}/systems/{system_id}/actions` - Create actions
-- `GET /o/{organisation_id}/systems/{system_id}/actions/{action_id}` - Get action
-- `PUT /o/{organisation_id}/systems/{system_id}/actions/{action_id}` - Update action
-- `DELETE /o/{organisation_id}/systems/{system_id}/actions/{action_id}` - Delete action
-- `GET /o/{organisation_id}/systems/{system_id}/triggers` - List triggers
-- `POST /o/{organisation_id}/systems/{system_id}/triggers` - Create triggers
-- `POST /o/{organisation_id}/systems/{system_id}/projects/{project_id}/actions-link` - Link actions to project
-- `POST /o/{organisation_id}/systems/{system_id}/projects/{project_id}/triggers-link` - Link triggers to project
-- `POST /o/{organisation_id}/systems/{system_id}/oauth2/initialise` - Initialize OAuth2 connection
-- `POST /o/{organisation_id}/systems/{system_id}/oauth1/initialise` - Initialize OAuth1 connection
-- `PUT /o/{organisation_id}/systems/{system_id}/auth-scheme-configs/{auth_scheme_config_id}` - Upsert auth config
-- `DELETE /o/{organisation_id}/systems/{system_id}/auth-scheme-configs/{auth_scheme_config_id}` - Delete auth config
-
----
-
-### 5. Connections
-
-**What it is**: Credentials and configuration that link a System to an Environment.
-
-**API Path**: `/o/{organisation_id}/connections`
-
-**Key Characteristics**:
-- Contains credentials (OAuth tokens, API keys, etc.)
-- Has a `systemId` reference to a System
-- Can be linked to environments via `LinkConnectionToEnvironment` endpoint
-- Required for activations (all environment systems must have connections)
-- Connections are created at organisation level, then linked to environments
-- **Important**: Connection creation requires `connectionTemplateId` (project-scoped) and `connection` object (both required fields)
-
-**Entity Structure**:
-```typescript
-Connection {
-  id: string
-  name: string
-  systemId?: string  // Optional reference to System
-  connectionTemplateId?: string  // Optional reference to Connection Template
-  credentials: ConnectionCredentials
-  baseUrl?: string  // Optional override
-  createdAt: string
-  updatedAt: string
-}
-```
-
-**Note**: Connections are linked to environments via the `LinkConnectionToEnvironment` endpoint, but the Connection object itself doesn't contain an `environment` field - the relationship is managed separately.
-
-**API Endpoints**:
-- `GET /o/{organisation_id}/connections` - List connections (filterable by system_id, end_user_id)
-- `POST /o/{organisation_id}/connections` - Create connection
-- `GET /o/{organisation_id}/connections/{connection_id}` - Get connection
-- `PUT /o/{organisation_id}/connections/{connection_id}` - Update connection
-- **Note**: There is NO DELETE endpoint for connections in the API spec
-- `POST /o/{organisation_id}/connections/{connection_id}/link` - Link connection to environment
-- `GET /o/{organisation_id}/projects/{project_id}/connections` - List environment connections (requires env_id query parameter)
-
----
-
-### 6. End Users
-
-**What it is**: Your customers/users who will use the integration.
-
-**API Path**: `/o/{organisation_id}/users`
-
-**Key Characteristics**:
-- Organisation-scoped
-- Identified by `externalId` (immutable, unique)
-- Can have multiple activations (one per environment)
-- `externalId` should NOT be an email (use a stable identifier)
-
-**Entity Structure**:
-```typescript
-EndUser {
-  id: string
-  externalId: string  // Immutable, unique identifier (required)
-  displayName: string  // Optional in creation, defaults to empty string if not set
-  organisationId: string
-  createdAt: string
-  updatedAt: string
-}
-```
-
-**API Endpoints**:
-- `GET /o/{organisation_id}/users` - List users (filterable by environment_id, activation status)
-- `POST /o/{organisation_id}/users` - Create user
-- `GET /o/{organisation_id}/users/{user_id}` - Get user (by id or externalId)
-- `PUT /o/{organisation_id}/users/{user_id}` - Update user
-- `DELETE /o/{organisation_id}/users/{user_id}` - Delete user
-- `GET /o/{organisation_id}/environment/{environment_id}/users/{external_user_id}/activations` - List user activations
-
----
-
-### 7. Activations
-
-**What it is**: The "glue" that links a User to an Environment with user-specific configuration.
-
-**API Path**: `/o/{organisation_id}/environments/{environment_id}/activations`
-
-**Key Characteristics**:
-- Links a **User** to an **Environment**
-- Contains **Dynamic Variables** (user-specific config)
-- **Requires Connections** for all systems in the environment
-- Variables are validated against Project's Variable Schema
-- Can have **Static Variables** (environment-level defaults)
-
-**Entity Structure**:
-```typescript
-Activation {
-  id: string
-  user: EndUser
-  environment: ProjectEnvironment
-  connections: Connection[]  // All required connections
-  dynamicVariables: DynamicVariables  // User-specific config
-}
-```
-
-**API Endpoints**:
-- `POST /o/{organisation_id}/activations` - Activate user (create activation)
-- `GET /o/{organisation_id}/environments/{environment_id}/activations` - List activations for environment
-- `GET /o/{organisation_id}/environments/{environment_id}/activations/{activation_id}` - Get activation
-- `DELETE /o/{organisation_id}/environments/{environment_id}/activations/{activation_id}` - Delete activation
-- `PATCH /o/{organisation_id}/environments/{environment_id}/activations/{activation_id}/variables` - Set dynamic variables
-- `PUT /o/{organisation_id}/environments/{environment_id}/activations/{activation_id}/variables/{variable_name}` - Set single variable
-- `PATCH /o/{organisation_id}/environments/{environment_id}/variables` - Set static variables (environment defaults)
-- `GET /o/{organisation_id}/environment/{environment_id}/users/{external_user_id}/activations` - List user activations
-- `GET /o/{organisation_id}/environment-systems/{env_system_id}/activations/{activation_id}` - Get activation connection
-
----
-
-## Relationships & Dependencies
-
-### Critical Relationships
-
-1. **Organisation → Projects**
-   - One-to-many
-   - Projects belong to an organisation
-
-2. **Project → Environments**
-   - One-to-many
-   - Environments belong to a Project (returned in Project.environments array)
-   - Each environment has its own deployment status
-
-3. **Organisation → Systems**
-   - One-to-many
-   - Systems are shared across all projects in an organisation
-
-4. **System → Connection → Environment**
-   - Many-to-many via Connection
-   - A Connection references a System via `systemId`
-   - Connections are linked to Environments via `LinkConnectionToEnvironment` endpoint
-   - One System can have multiple Connections
-
-5. **User → Activation → Environment**
-   - Many-to-many via Activation
-   - An Activation links a User to an Environment
-   - One User can have multiple Activations (one per Environment)
-
-6. **Activation → Connections**
-   - Many-to-many
-   - An Activation requires Connections for ALL systems in the environment
-   - Connections are shared across activations in the same environment
-
-7. **Project → Variable Schema**
-   - One-to-one
-   - Project defines what variables can be set
-   - Activations store the actual values
-
-### Dependency Rules
-
-1. **Activation Creation Requires**:
-   - User exists
-   - Environment exists (project must be deployed)
-   - Connections exist for ALL systems in the environment
-   - Dynamic variables match Project's Variable Schema
-
-2. **Connection Creation Requires**:
-   - Connection Template exists (project-scoped, which references a System)
-   - **Both `connectionTemplateId` and `connection` object are REQUIRED fields** for creation
-   - Note: The relationship chain is: Connection Template (references systemId) → System → Connection
-   - Connections are created at organisation level, then linked to environments separately
-
-3. **Project Deployment**:
-   - Deploys files to the specified environment
-   - Updates the environment's deployed files
-   - Note: Environment creation/management is not explicitly documented in the API spec
-
-4. **Variable Validation**:
-   - All dynamic variables must match Project's Variable Schema
-   - Required variables must be provided
-   - Partial updates must result in valid final state
-
----
-
-## API Endpoints by Entity
-
-### Quick Reference
-
-| Entity | List | Create | Get | Update | Delete |
-|--------|------|--------|-----|--------|--------|
-| **Projects** | ✅ | ✅ | ✅ | ✅ | ✅ |
-| **Environments** | ✅* | ✅* | ✅* | ✅* | ❌ |
-| **Systems** | ✅ | ✅ | ✅ | ✅ | ❌ |
-| **Connections** | ✅ | ✅ | ✅ | ✅ | ❌ |
-| **End Users** | ✅ | ✅ | ✅ | ✅ | ✅ |
-| **Activations** | ✅ | ✅ | ✅ | ❌ | ✅ |
-| **Automations** | ✅ | ✅ | ✅ | ✅ | ❌ |
-| **Schedulers** | ✅ | ❌ | ✅ | ❌ | ❌ |
-| **Issues** | ✅ | ✅ | ❌ | ✅ | ❌ |
-| **Notifications** | ✅ | ✅ | ❌ | ❌ | ✅ |
-| **Metrics** | ✅ | ❌ | ❌ | ❌ | ❌ |
-| **KV Store** | ✅ | ✅ | ✅ | ✅ | ✅ |
-
-*Environments are managed through Project endpoints (created on deployment)
-*Schedulers are read-only (created/managed elsewhere, can only trigger)
-*Metrics are read-only (no create/update/delete)
-*Issues have no GET by ID endpoint (only list)
-*Notifications: Channels are org-scoped, Project Notifications are project-scoped
-
----
-
-## Common Workflows
-
-### 1. Setting Up a New Integration
-
-**Step-by-step**:
-
-1. **Create Project**
-   ```http
-   POST /o/{org_id}/projects
-   {
-     "name": "My Integration"
-   }
-   ```
-
-2. **Set Variable Schema**
-   ```http
-   PUT /o/{org_id}/projects/{project_id}/variables
-   {
-     "properties": {
-       "apiKey": { "type": "string" },
-       "region": { "type": "string" }
-     },
-     "required": ["apiKey"]
-   }
-   ```
-
-3. **Upload Files**
-   ```http
-   PUT /o/{org_id}/projects/{project_id}/files
-   {
-     "files": [
-       { "filename": "workflow.ts", "content": "..." }
-     ]
-   }
-   ```
-
-4. **Deploy Project** (deploys to environment)
-   ```http
-   PUT /o/{org_id}/projects/{project_id}/deploy?environment=production
-   {
-     "environment": "production"
-   }
-   ```
-
-   **Note**: The environment must already exist. The API doesn't explicitly document environment creation.
-
-5. **Create/Use System** (if needed)
-   ```http
-   POST /o/{org_id}/systems
-   {
-     "name": "My External System"
-   }
-   ```
-
-6. **Create Connection** (requires connectionTemplateId from step 1)
-   ```http
-   POST /o/{org_id}/connections
-   {
-     "connectionTemplateId": "...",  // REQUIRED - from project's connection templates
-     "connection": {                  // REQUIRED
-       "name": "Production Connection",
-       "credentials": { ... }
-     }
-   }
-   ```
-
-   **Note**: Both `connectionTemplateId` and `connection` are required fields. Connection templates are project-scoped, so you need a project first.
-
-7. **Link Connection to Environment**
-   ```http
-   POST /o/{org_id}/connections/{connection_id}/link
-   {
-     "connectionTemplateId": "..."
-   }
-   ```
-
-### 2. Activating a User
-
-**Step-by-step**:
-
-1. **Create End User**
-   ```http
-   POST /o/{org_id}/users
-   {
-     "externalId": "customer-123",
-     "displayName": "Customer ABC"
-   }
-   ```
-
-2. **Activate User** (creates activation)
-   ```http
-   POST /o/{org_id}/activations
-   {
-     "userId": "customer-123",
-     "environmentId": "{environment_id}",
-     "connections": [
-       {
-         "connectionTemplateId": "...",
-         "existingConnectionId": "{connection_id}"
-       }
-     ],
-     "dynamicVariables": {
-       "apiKey": "xyz123",
-       "region": "us-east-1"
-     }
-   }
-   ```
-
-**Important**: All systems in the environment must have connections provided.
-
-### 3. Updating Activation Variables
-
-**Partial Update** (must include all required variables):
-
-```http
-PATCH /o/{org_id}/environments/{env_id}/activations/{activation_id}/variables
-{
-  "apiKey": "new-key",  // Updating this
-  "region": "us-west-1"  // Must include required variables even if not changing
-}
-```
-
-**Single Variable Update**:
-
-```http
-PUT /o/{org_id}/environments/{env_id}/activations/{activation_id}/variables/apiKey
-"new-api-key-value"
-```
-
-### 4. Finding a User's Activation
-
-1. **List Users** (find by externalId)
-   ```http
-   GET /o/{org_id}/users?search=customer-123
-   ```
-
-2. **List User Activations** (by external_user_id)
-   ```http
-   GET /o/{org_id}/environment/{env_id}/users/{external_user_id}/activations
-   ```
-
-   **OR** List all activations for an environment and filter:
-   ```http
-   GET /o/{org_id}/environments/{env_id}/activations
-   ```
-   Then filter response by `userId` or `externalId`
-
----
-
-## Data Flow Examples
-
-### Example 1: Multi-Tenant SaaS Integration
-
-**Scenario**: You're building a SaaS that integrates with Salesforce for each customer.
-
-```
-Organisation: "Your SaaS Company"
-│
-├── Project: "Salesforce Integration"
-│   ├── Environment: "production"
-│   └── Variable Schema: { salesforceOrgId: string, apiVersion: string }
-│
-├── System: "Salesforce"
-│
-├── Connections (one per customer's Salesforce org):
-│   ├── Connection 1: "Customer A Salesforce" → System(Salesforce) + Environment(production)
-│   ├── Connection 2: "Customer B Salesforce" → System(Salesforce) + Environment(production)
-│   └── Connection 3: "Customer C Salesforce" → System(Salesforce) + Environment(production)
-│
-├── End Users (your customers):
-│   ├── User 1: externalId="customer-a"
-│   ├── User 2: externalId="customer-b"
-│   └── User 3: externalId="customer-c"
-│
-└── Activations (one per customer):
-    ├── Activation 1: User(customer-a) + Environment(production) + Connection(Customer A Salesforce)
-    │   └── Variables: { salesforceOrgId: "00D...", apiVersion: "v58" }
-    ├── Activation 2: User(customer-b) + Environment(production) + Connection(Customer B Salesforce)
-    │   └── Variables: { salesforceOrgId: "00E...", apiVersion: "v58" }
-    └── Activation 3: User(customer-c) + Environment(production) + Connection(Customer C Salesforce)
-        └── Variables: { salesforceOrgId: "00F...", apiVersion: "v58" }
-```
-
-### Example 2: E-commerce Platform Integration
-
-**Scenario**: Integrating with Shopify, S3, and Fluent Commerce.
-
-```
-Organisation: "E-commerce Platform"
-│
-├── Project: "Order Processing"
-│   ├── Environment: "production"
-│   └── Variable Schema: { shopifyStore: string, s3Bucket: string }
-│
-├── Systems:
-│   ├── System 1: "Shopify"
-│   ├── System 2: "AWS S3"
-│   └── System 3: "Fluent Commerce"
-│
-├── Connections (one per system per environment):
-│   ├── Connection 1: "Shopify-Prod" → System(Shopify) + Environment(production)
-│   ├── Connection 2: "S3-Prod" → System(AWS S3) + Environment(production)
-│   └── Connection 3: "Fluent-Prod" → System(Fluent Commerce) + Environment(production)
-│
-├── End Users (merchants):
-│   └── User 1: externalId="merchant-123"
-│
-└── Activation:
-    └── Activation 1: User(merchant-123) + Environment(production)
-        ├── Connections: [Shopify-Prod, S3-Prod, Fluent-Prod]  // All required!
-        └── Variables: { shopifyStore: "mystore.myshopify.com", s3Bucket: "orders-prod" }
-```
-
----
-
-## Key Takeaways
-
-1. **Organisation** is the top-level container
-2. **Projects** contain code and define variable schemas
-3. **Environments** belong to Projects (returned in Project.environments array)
-4. **Systems** are shared across projects (organisation-scoped)
-5. **Connections** link Systems to Environments (credentials)
-6. **Activations** link Users to Environments (user-specific config)
-7. **Activations require Connections** for all systems in the environment
-8. **Variables** are schema-driven (Project defines schema, Activation stores values)
-
----
-
-### 8. Automations
-
-**What it is**: Workflow automation system with recording and transcription capabilities for RPA/automation workflows.
-
-**API Path**: `/o/{organisation_id}/automations`
-
-**Key Characteristics**:
-- Organisation-scoped
-- Supports automation runs (execution tracking)
-- Includes recording and transcription features
-- Can be run on-demand or scheduled
-
-**API Endpoints**:
-- `GET /o/{organisation_id}/automations` - List automations
-- `POST /o/{organisation_id}/automations` - Create automation
-- `GET /o/{organisation_id}/automations/{automation_id}` - Get automation
-- `PUT /o/{organisation_id}/automations/{automation_id}` - Update automation
-- `POST /o/{organisation_id}/automations/{automation_id}/run` - Run automation
-- `GET /o/{organisation_id}/automations/{automation_id}/run` - List automation runs
-- `GET /o/{organisation_id}/automations/{automation_id}/runs/{run_id}` - Get automation run
-- `GET /o/{organisation_id}/automations/{automation_id}/recordings` - List recordings
-- `POST /o/{organisation_id}/automations/{automation_id}/recordings` - Create recording
-- `GET /o/{organisation_id}/automations/{automation_id}/recordings/{recording_id}` - Get recording
-- `POST /o/{organisation_id}/automations/{automation_id}/recordings/{recording_id}` - Create transcription
-
----
-
-### 9. Schedulers
-
-**What it is**: Cron/timer-based scheduled workflow execution system.
-
-**API Path**: `/o/{organisation_id}/environments/{environment_id}/schedulers`
-
-**Key Characteristics**:
-- Environment-scoped
-- Can be triggered manually for testing
-- Used for scheduled/cron-based workflows
-
-**API Endpoints**:
-- `GET /o/{organisation_id}/environments/{environment_id}/schedulers` - List schedulers
-- `GET /o/{organisation_id}/environments/{environment_id}/schedulers/{scheduler_id}` - Get scheduler
-- `POST /o/{organisation_id}/environments/{environment_id}/schedulers/{scheduler_id}` - Trigger scheduler (manual execution)
-
----
-
-### 10. Issues
-
-**What it is**: Bug tracking and issue management system for monitoring integration problems.
-
-**API Path**: `/o/{organisation_id}/issues`
-
-**Key Characteristics**:
-- Organisation-scoped
-- Can be filtered by status (`open`, `closed`, `acked`, `resolved`)
-- Can be filtered by project, environment, severity
-- Supports pagination with `first`, `after`, `before` parameters
-
-**API Endpoints**:
-- `GET /o/{organisation_id}/issues` - List issues (filterable by status, project_id, environment_id, severity)
-- `POST /o/{organisation_id}/issues` - Create issue
-- `PATCH /o/{organisation_id}/issues/{issue_id}` - Update issue
-
----
-
-### 11. Notifications
-
-**What it is**: Alert and notification channel management system.
-
-**API Path**: `/o/{organisation_id}/notification_channels` and `/o/{organisation_id}/projects/{project_id}/notifications`
-
-**Key Characteristics**:
-- Notification Channels are organisation-scoped
-- Project Notifications link channels to projects
-- Supports multiple notification channels per organisation
-
-**API Endpoints**:
-- `GET /o/{organisation_id}/notification_channels` - List notification channels
-- `POST /o/{organisation_id}/notification_channels` - Create notification channel
-- `DELETE /o/{organisation_id}/notification_channels/{channel_id}` - Delete notification channel
-- `GET /o/{organisation_id}/projects/{project_id}/notifications` - List project notifications (requires env_id query parameter)
-- `POST /o/{organisation_id}/projects/{project_id}/notifications` - Create project notification
-- `DELETE /o/{organisation_id}/projects/{project_id}/notifications/{notification_id}` - Delete project notification
-
-**Note**: The YAML spec shows `/projects/{project_id}/notifications` without the `/o/{organisation_id}/` prefix, but the actual API requires the full path with organisation prefix.
-
----
-
-### 12. Metrics
-
-**What it is**: Usage analytics and metrics summaries for organisations and projects.
-
-**API Path**: `/o/{organisation_id}/metricssummary` and `/o/{organisation_id}/projects/metricssummary`
-
-**Key Characteristics**:
-- Organisation-level metrics summary
-- Project-level metrics summary (aggregated across all projects)
-- Read-only (no create/update/delete operations)
-
-**API Endpoints**:
-- `GET /o/{organisation_id}/metricssummary` - Get organisation metrics summary
-- `GET /o/{organisation_id}/projects/metricssummary` - Get project metrics summary
-
----
-
-### 13. KV Store
-
-**What it is**: Key-value state management and persistence system for storing integration state.
-
-**API Path**: `/o/{organisation_id}/store` (for store management) and `/store/{store}/kv` (for KV operations)
-
-**Key Characteristics**:
-- Organisation-scoped stores
-- Keys are arrays of strings (e.g., `["products", "123"]`)
-- Supports batch operations (get, set, delete) - all use same `/kv/batch` path with different HTTP methods
-- Supports listing and counting with filtering
-- **Important**: KV operations use `/store/{store}/kv/{key}` path pattern (no `/o/{org_id}/` prefix)
-
-**API Endpoints**:
-- `GET /o/{organisation_id}/store` - List stores
-- `POST /o/{organisation_id}/store` - Create store
-- `GET /store/{store}/kv/{key}` - Get KV value
-- `PUT /store/{store}/kv/{key}` - Set KV value
-- `DELETE /store/{store}/kv/{key}` - Delete KV value
-- `POST /store/{store}/kv/batch` - Batch get KV (multiple keys)
-- `PUT /store/{store}/kv/batch` - Batch set KV (multiple key-value pairs)
-- `DELETE /store/{store}/kv/batch` - Batch delete KV (multiple keys)
-- `POST /store/{store}/kv/list` - List KV entries with filtering
-- `POST /store/{store}/kv/count` - Count KV entries matching selector
-
----
-
-## API Verification
-
-✅ **All relationships match the API structure**:
-
-- Projects are scoped under `/o/{org_id}/projects`
-- Environments are accessed via `/o/{org_id}/environments/{env_id}` (created on deployment)
-- Systems are scoped under `/o/{org_id}/systems`
-- Connections are scoped under `/o/{org_id}/connections`
-- Users are scoped under `/o/{org_id}/users`
-- Activations are scoped under `/o/{org_id}/environments/{env_id}/activations`
-- Activation schema includes: `user`, `environment`, `connections`, `dynamicVariables`
-
-The API structure confirms the model described above.
-
----
-
-**Last Updated**: 2025-01-19
-**API Version**: 0.0.1
-**Base URL**: https://platform.versori.com/api/v2