📚 How to Enable Scenario Creation and Editing on dca-dev

docs/general/how-to-enable-scenario-creation-and-editing-on-dca-dev.md

@@ -0,0 +1,153 @@
+# How to Enable Scenario Creation and Editing on `dca-dev`
+
+## Overview
+
+This guide outlines the proposed approach for enabling create, read, update, and delete (CRUD) operations on scenarios in the `dca-dev` environment. It summarizes the design direction discussed in Slack and identifies open questions that must be resolved before implementation.
+
+## Prerequisites
+
+The following are implied prerequisites for implementing scenario CRUD on `dca-dev`:
+
+- Access to the **Distillery** service (the system currently responsible for scenarios).
+- Ability to modify or extend the **Distillery** data model (e.g., adding new tables).
+- Access to and permission to modify the **`dca-dev` database**.
+- Front-end development capability to:
+  - Add user interfaces (UI) for creating and managing tools.
+  - Add UI for creating and managing scenario “stubs.”
+- Back-end development capability to:
+  - Define and expose APIs for scenario CRUD.
+  - Integrate with the database schema for tools and stubs.
+- Understanding of existing **routines** and their **raw JSON** representations, as scenarios are expected to follow a similar pattern.
+
+> Note: No specific commands, URLs, or file paths were provided in the Slack discussion. These will need to be defined during implementation.
+
+## Proposed Design and Implementation Approach
+
+### 1. Enable CRUD Operations in Distillery
+
+To create or edit scenarios on `dca-dev`, Distillery must support full CRUD operations for scenarios:
+
+- **Create**: Define new scenarios and persist them.
+- **Read**: Retrieve existing scenarios for viewing and execution.
+- **Update**: Modify existing scenarios (e.g., change associated tools, stubs, or behavior).
+- **Delete**: Remove scenarios that are no longer needed.
+
+This likely requires:
+
+- New or updated API endpoints in Distillery for scenario management.
+- Authentication/authorization rules for who can perform scenario CRUD.
+
+### 2. Store Scenarios and Stubs in the Database
+
+The current thinking is to move scenario-related configuration from static or ad-hoc storage into a structured database model:
+
+1. **Tool Table**
+   - Represents tools used in scenarios.
+   - Each tool record contains metadata and configuration required for the tool to be invoked in a scenario.
+
+2. **Stub Table**
+   - Represents mocked behavior or responses associated with tools.
+   - Each stub row is linked to a tool via a **foreign key**.
+   - A stub defines how a tool should respond under specific conditions (e.g., given certain arguments).
+
+3. **Scenario Representation**
+   - Scenarios should have a **raw JSON representation**, similar to how routines are currently stored.
+   - A scenario is expected to:
+     - Reference one or more tools.
+     - Reference one or more stubs (or stub configurations) to define expected behavior.
+   - Some scenarios are more complex and may require:
+     - Multiple tools per scenario.
+     - Conditional behavior based on input arguments (e.g., “for these arguments return A, for different arguments return B”).
+
+> Open question: The exact database schema for scenarios (e.g., `scenarios` table, join tables between `scenarios` and `tools`, and how to store conditional logic) is not yet defined.
+
+### 3. Front-End User Interface Requirements
+
+To make scenario creation and editing possible on `dca-dev`, the front end must provide:
+
+1. **Tool Management UI**
+   - Create new tools.
+   - View and edit existing tools.
+   - Delete tools (if allowed).
+
+2. **Stub Management UI**
+   - For a given tool, create one or more stub rows.
+   - Define conditions (e.g., input arguments) and expected responses.
+   - Edit and delete stubs.
+
+3. **Scenario Management UI**
+   - Create new scenarios by:
+     - Selecting one or more tools.
+     - Associating the relevant stubs.
+     - Defining scenario metadata and behavior as raw JSON (or via a structured form that generates JSON).
+   - Edit existing scenarios (including tool and stub associations).
+   - Delete scenarios.
+
+### 4. Support for Complex and Workflow Scenarios
+
+The design must account for:
+
+- **Complex scenarios**:
+  - Scenarios that involve multiple tools.
+  - Scenarios where behavior varies based on input arguments (e.g., “mock bill changed” behavior).
+- **Workflow scenarios**:
+  - Scenarios used specifically to test workflows.
+  - These should be **decoupled** from workflows themselves, meaning:
+    - Scenarios are defined independently.
+    - Workflows reference scenarios rather than embedding scenario logic directly.
+
+## Important Notes and Caveats
+
+- **Incomplete Specification**: The Slack discussion provides a conceptual direction but not a full specification. The following are not yet defined:
+  - Exact database schema (tables, columns, relationships).
+  - API contracts (endpoints, request/response formats).
+  - Authentication and authorization model for scenario editing.
+  - Any environment-specific configuration for `dca-dev` (e.g., database connection strings, feature flags).
+
+- **Behavioral Complexity**:
+  - Some scenarios require conditional mocking based on arguments. This may need:
+    - A structured way to define conditions (e.g., JSONPath, simple expression language).
+    - A clear precedence/override model when multiple stubs match.
+
+- **Parity with Routines**:
+  - Scenarios should follow the same pattern as routines with **raw JSON versions**, but the exact format and validation rules for scenario JSON are not yet specified.
+
+## Troubleshooting and Open Questions
+
+Because this is a design-level summary, troubleshooting is mostly about clarifying requirements and design before implementation:
+
+1. **Scenarios Not Editable on `dca-dev`**
+   - Confirm:
+     - Distillery has scenario CRUD endpoints implemented.
+     - The `dca-dev` environment is configured to use the new database tables.
+     - Front-end UI for tools, stubs, and scenarios is deployed and wired to the APIs.
+
+2. **Scenarios Not Behaving as Expected**
+   - Check:
+     - The scenario’s raw JSON is valid and conforms to the agreed schema.
+     - The correct tools and stubs are linked to the scenario.
+     - Stub conditions (arguments, matching rules) are correctly defined.
+
+3. **Data Model Ambiguities**
+   - Clarify:
+     - How many tools can be linked to a single scenario (one vs many).
+     - How to represent “for these args return A, for other args return B” in the database and JSON.
+     - Whether workflow-specific scenarios need additional metadata or types.
+
+4. **Additional Information Needed**
+   - A finalized **database schema** for:
+     - `tools`
+     - `stubs`
+     - `scenarios`
+     - Any join tables (e.g., `scenario_tools`, `scenario_stubs`).
+   - Detailed **API specifications** for:
+     - Creating, reading, updating, and deleting tools, stubs, and scenarios.
+   - **Front-end design** and UX flows for:
+     - Scenario creation/editing.
+     - Tool and stub management.
+   - Any **environment-specific details** for `dca-dev`:
+     - Base URLs for Distillery APIs.
+     - Feature flags or configuration toggles to enable scenario editing.
+
+---
+*Source: [Original Slack thread](https://distylai.slack.com/archives/impl-tower-think-tank/p1752207491518779)*