elsa-core/specs/001-shell-reload-api/plan.md

Implementation Plan: Shell Reload API Endpoints

Branch: 001-shell-reload-api | Date: 2026-03-08 | Spec: ./spec.md Input: Feature specification from /specs/001-shell-reload-api/spec.md

Summary

Add two administrative shell reload endpoints and a matching typed API client surface so operators can refresh shell-backed feature configuration without restarting the host. The implementation will use a dedicated shell reload orchestration service in Elsa.Workflows.Api to validate shell IDs, reject concurrent reloads, wrap the current full-reload fallback for targeted requests, and return detailed per-shell outcomes that satisfy the clarified spec.

Technical Context

Language/Version: C# latest on .NET 10.0 primary, with existing multi-target support for .NET 8.0 and .NET 9.0
Primary Dependencies: FastEndpoints, Elsa.Api.Common abstractions, CShells, CShells.FastEndpoints.Abstractions, Refit client contracts, xUnit component test infrastructure
Storage: No new persistent storage; uses the existing CShells shell settings provider and in-memory shell settings cache
Testing: xUnit component tests in Elsa.Workflows.ComponentTests; no existing dedicated Elsa.Workflows.Api unit test project
Target Platform: ASP.NET Core modular server host exposing Elsa REST APIs through shell-aware FastEndpoints
Project Type: Modular .NET library feature plus first-party API client contract
Performance Goals: Keep shell reload as a synchronous admin operation within the existing API client timeout budget of 1 minute; do not add background polling or queued work
Constraints: Preserve existing shell-aware endpoint discovery, keep the feature scoped to current modules, reject concurrent reload requests, return per-shell outcomes, and keep targeted reload on full-reload fallback semantics until upstream CShells adds a selective reload API
Scale/Scope: Two new endpoints, one shared response contract, one orchestration service, one API client resource, and focused component-test coverage in the existing server fixture

Constitution Check

GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.

Pre-Phase 0 Gate Review

• I. Modular Architecture: PASS. Changes stay inside existing bounded areas: Elsa.Workflows.Api, Elsa.Api.Client, and Elsa.Workflows.ComponentTests.
• II. Composition & Extensibility: PASS. A dedicated orchestration contract isolates current fallback behavior from future upstream targeted reload support.
• III. Convention-Driven Design: PASS. Endpoints will remain one-class-per-endpoint with collocated request/response models and standard permission configuration.
• IV. Async & Pipeline Execution: PASS. Endpoint and orchestration flows remain async-only and use existing middleware/endpoint infrastructure.
• V. Testing Discipline: PASS. Feature verification will use the existing component-test host and endpoint-style tests already used for REST APIs.
• VI. Trunk-Based Development: PASS. The change is one concern and includes API contract artifacts for downstream client work.
• VII. Simplicity & Focus: PASS. No new module is introduced; one orchestration service is the minimum additional abstraction needed to satisfy busy-state handling, fallback semantics, and detailed outcomes.

Post-Phase 1 Design Review

• PASS. The design keeps the concern localized, introduces no extra module boundary, uses collocated endpoint models, and adds only one new service abstraction because direct endpoint-to-IShellManager calls cannot satisfy partial-success reporting, busy rejection, and requested-shell strictness together.

Project Structure

Documentation (this feature)

specs/001-shell-reload-api/
├── plan.md
├── research.md
├── data-model.md
├── quickstart.md
├── contracts/
│   └── shell-reload-api.yaml
└── tasks.md

Source Code (repository root)

src/
├── modules/
│   └── Elsa.Workflows.Api/
│       ├── Contracts/
│       ├── Services/
│       └── Endpoints/
│           └── Shells/
│               ├── Reload/
│               └── ReloadAll/
└── clients/
  └── Elsa.Api.Client/
    └── Resources/
      └── Shells/
        ├── Contracts/
        ├── Requests/
        ├── Responses/
        └── Models/

test/
└── component/
  └── Elsa.Workflows.ComponentTests/
    └── Scenarios/
      └── RestApis/
        └── Endpoints/
          └── Shells/

Structure Decision: Extend the existing workflow API module and first-party API client instead of adding a new shell-management module. This aligns with the repository’s established pattern where administrative REST endpoints and typed client contracts evolve together while component tests validate behavior through the hosted server fixture.

Endpoint-specific request and response models remain collocated under Endpoints/Shells/Reload/ and Endpoints/Shells/ReloadAll/. Shared orchestration result types belong under Contracts/ so endpoint model colocation is preserved.

Complexity Tracking

No constitutional violations requiring justification.