slp-modular-cms/aidlc-docs/features/local-dev-master-slave-setup/inception/requirements/requirements.md

Requirements — Local Dev Master/Slave Setup

Intent Analysis

• User Request: Enable running two local instances of the CMS backend simultaneously — one with SlpModularCms.Modules.Master loaded (the existing full CMS, acting as master) and one without it (acting purely as a slave/target) — on two different ports, so the master↔slave connection can be tested end-to-end locally.
• Request Type: New Feature (developer tooling / local run configuration)
• Scope Estimate: Multiple components — new host project (SlpModularCms.Api.Slave), solution/build changes, appsettings/launchSettings for both instances, frontend dev-server configuration for pointing at either instance.
• Complexity Estimate: Moderate — no new business logic; the master/slave protocol itself (Modules.Master's CmsInstanceService/SlaveApiClient and Modules.Availability's MasterController/MasterAvailabilityService) already exists and is unchanged. Complexity comes from correctly separating build/run configuration for two instances without duplicating orchestration logic.

Background (from codebase investigation)

• SlpModularCms.Api's Program.cs does not directly reference Modules.Master. Instead, Infrastructure/ModuleOrchestrator.cs discovers modules at startup by scanning its own build output directory for SlpModularCms.Modules.*.dll and instantiating any IModule implementation found — currently every module the API project references (Core, Availability, Identity, Master) always ends up in that output folder via ProjectReferences in SlpModularCms.Api.csproj.
• The master/slave connection mechanism already exists and needs no changes:
  • Slave side (present in every instance, since Modules.Availability is always loaded): MasterController + MasterAvailabilityService + MasterApiKeyProtector accept and validate a per-instance API key pushed by a master.
  • Master side (only in Modules.Master): CmsInstanceService + SlaveApiClient + ApiKeyProtector manage registered CMS instances and talk to them.
  • The existing frontend "Add CMS Instance" dialog (from master-cms-module) is the existing UI flow for registering a slave under a master.
• Frontend reads its backend URL from VITE_API_BASE_URL (frontend/src/lib/config.ts), sourced from a Vite env file (.env.local, .env.example), evaluated once per dev server process. Vite dev server currently runs on a fixed port (5173, vite.config.ts).
• Backend CORS allowed origins are configured per-instance under Cors:AllowedOrigins in appsettings.Development.json / appsettings.local.json.

Decisions from Clarification

1. Instance separation mechanism: A new host project, SlpModularCms.Api.Slave, with its own .csproj referencing SlpModularCms.Core, SlpModularCms.Modules.Identity, and SlpModularCms.Modules.Availability — but not SlpModularCms.Modules.Master. Because ModuleOrchestrator discovers modules purely by scanning its own build output, omitting the Master project reference is sufficient to produce a slave-only instance; no config-driven module toggle is needed for this feature.
2. Production plugin-loading model is explicitly out of scope: the user separately wants a future production model where the API is built once without module project references and modules are dropped in as standalone DLLs post-build. That is a distinct, larger architectural change (build/packaging/CI, not local dev tooling) and is not part of this feature. Capture it as a follow-up idea (see "Out of Scope" below).
3. Database isolation: Master and slave instances use separate local databases (separate connection strings/database names), same local SQL Server.
4. Ports: Master keeps existing ports (http://localhost:5284, https://localhost:7221). Slave gets a new pair (http://localhost:5285, https://localhost:7222).
5. Launch method: Two dotnet run --launch-profile <name> invocations (one per terminal/process) — no background helper script required.
6. Frontend: The frontend must also be runnable against the slave instance (its own dev server / env configuration), not just the master — so the slave's admin UI is separately reachable for manual testing.
7. Establishing the connection: No scripted/seeded auto-registration. The user will manually register the slave under the master using the existing "Add CMS Instance" UI flow, specifically to exercise/validate that flow end-to-end.

Functional Requirements

FR-1: Slave-only backend host project

• Add SlpModularCms.Api.Slave, a new ASP.NET Core Web API project in src/, added to the solution.
• Bootstraps the same way as SlpModularCms.Api (core infrastructure, CORS, rate limiting, controllers, module discovery/orchestration, exception handling, Scalar in Development) — but its .csproj references Core, Modules.Identity, and Modules.Availability only (no Modules.Master reference), so ModuleOrchestrator never discovers/loads the Master module for this instance.
• Avoid duplicating the bootstrap/orchestration code (ModuleOrchestrator, ServiceCollectionExtensions, ApiPrefixConvention) between SlpModularCms.Api and SlpModularCms.Api.Slave — extract shared pieces into a location both projects can reference without pulling in Modules.Master (see NFR-1).

FR-2: Distinct local run configuration per instance

• SlpModularCms.Api (master) keeps its existing launchSettings.json profiles and ports (5284 / 7221).
• SlpModularCms.Api.Slave gets its own launchSettings.json with profiles on ports 5285 (HTTP) and 7222 (HTTPS).
• Each project has its own appsettings.json / appsettings.Development.json / appsettings.local.json (gitignored) with:
  • A distinct ConnectionStrings:DefaultConnection (separate database name/catalog) so master and slave don't share data.
  • Cors:AllowedOrigins covering whichever frontend origin(s) will point at that instance.
  • The slave instance does not need MasterModule configuration (that section is only meaningful where Modules.Master is loaded).
• Both instances can be started independently via dotnet run --launch-profile <name> from their respective project directories.

FR-3: Frontend configurable against either instance

• Add a way to run the existing frontend against the slave instance in addition to the master, without needing two separate frontend codebases:
  • A second Vite env file (e.g. .env.slave.local, gitignored like .env.local) setting VITE_API_BASE_URL to the slave's HTTPS URL (https://localhost:7222).
  • A second npm script (e.g. dev:slave) that runs Vite with that env mode on a different dev-server port (e.g. 5174), so both frontend instances can run side by side if needed.
  • Update .env.example and/or frontend/README.md to document both modes.

FR-4: Documentation for the local master/slave workflow

• Add a short runbook (e.g. frontend/README.md and/or a root-level docs/README section, or a dedicated markdown file referenced from the main README) describing:
  1. How to start the master backend + master frontend.
  2. How to start the slave backend (+ optionally slave frontend) on the alternate ports.
  3. How to use the master frontend's existing "Add CMS Instance" dialog to register the local slave (what URL/API key to use) and confirm the connection works (e.g. status shows as connected/healthy).

Non-Functional Requirements

NFR-1: No logic duplication between host projects

• The master and slave host projects must share bootstrap/orchestration code (module discovery, DI wiring for core infrastructure, controller conventions) rather than maintaining two copies that can drift. Exact extraction mechanism (e.g. a small shared class library, or a shared partial/extension file linked into both projects) is a Functional/Application Design decision, not fixed here.

NFR-2: Isolation

• Master and slave instances must not share a database, so testing against one cannot corrupt or interfere with the other's data.

NFR-3: Local-only scope

• No changes to the actual master/slave communication protocol, production deployment, or CI/CD pipeline. This is strictly a local development convenience.

NFR-4: Secrets hygiene

• Slave's appsettings.local.json (and any new gitignored env files) must follow the existing pattern — never committed, following dotnet-appsettings conventions already used by SlpModularCms.Api.

Out of Scope

• Production drop-in module DLL loading: Building the API once without module project references and loading modules from an external "Modules" folder dropped in post-build/at-deploy. This is a distinct future initiative (build/packaging/CI concern) explicitly deferred by the user during clarification — to be captured as a new backlog/feature item when picked up, not designed as part of this feature.
• Automated/scripted slave registration: The user explicitly wants to exercise the existing "Add CMS Instance" UI flow manually; no seed data or dev-only registration endpoint will be added.
• Any change to Modules.Master, Modules.Availability, or the master/slave communication protocol itself.

Summary

This feature adds a second, Master-less ASP.NET Core host project (SlpModularCms.Api.Slave) plus per-instance run configuration (ports, databases, CORS) and frontend tooling, so the developer can run a master CMS instance (full stack, port 5284/7221) and a slave-only instance (no Master module, port 5285/7222) side by side locally, and manually connect them via the existing "Add CMS Instance" UI flow to validate the master/slave integration end-to-end. The production "plugin-style" module loading idea raised during clarification is explicitly out of scope and noted for future consideration.