# Application Design Plan — Master CMS Module ## Overview This plan covers the high-level component identification and service layer design for the Master CMS Module. The feature spans four units: `master-backend`, `slave-availability-extension`, `frontend-cms-page`, and `documentation`. Before generating design artifacts, a set of design questions must be answered below. --- ## Design Questions Answer each question by filling in your choice after the `[Answer]:` tag. --- ### Q1 — HTTP Client for Master → Slave Communication The Master CMS needs to call slave CMS REST endpoints for: - Auto-registration (FR-MASTER-03) - Status push (FR-MASTER-05) - Integrity verification (FR-MASTER-04) How should the HTTP client be organized in `SlpModularCms.Modules.Master`? A) **Typed client** — define `ISlaveApiClient` interface + `SlaveApiClient` implementation; registered via `services.AddHttpClient()`. Clean, testable, injectable. B) **Named client** — register a named `HttpClient` ("slave") via `IHttpClientFactory` and inject `IHttpClientFactory` into the service that makes calls. Less abstraction, but familiar .NET pattern. C) **Direct `HttpClient` injection** — inject `IHttpClientFactory` directly in `CmsInstanceService` and create a client per call. Simplest approach; no separate client abstraction. D) Other [Answer]: A --- ### Q2 — Two-Phase Availability Gate: Middleware Strategy The slave must implement a two-phase gate: Master gate (outer) → Local gate (inner) (FR-MASTER-08). The existing `AvailabilityMiddleware` implements the local gate. Which approach should be used to add the Master gate on the slave? A) **New separate `MasterGateMiddleware`** — registered before the existing `AvailabilityMiddleware` in the pipeline. Clean separation; existing middleware is untouched; Master gate is skipped at registration if no Master URL is stored. B) **Extend `AvailabilityMiddleware`** — add the Master gate logic at the top of the existing middleware class. Single file; simpler pipeline registration; slightly more coupling between Master and Availability module. C) Other [Answer]: B --- ### Q3 — Slave-Side Master Status Caching The slave must cache the master-pulled availability status (FR-MASTER-06, FR-MASTER-07). The existing codebase uses a simple `static` field + timestamp in `PersistentAvailabilityService` for circuit breaker caching. Which caching mechanism should be used for the master status cache on the slave? A) **Static field with timestamp** (same pattern as existing circuit breaker) — a `static` field in `MasterAvailabilityService` holding the last known status and last-fetched timestamp. Zero dependencies; consistent with existing code style. B) **`IMemoryCache`** — inject `IMemoryCache` and use a keyed cache entry with a sliding/absolute expiry. Standard .NET caching abstraction; easier to test via mock; slightly more infrastructure. C) Other [Answer]: A --- ### Q4 — `CmsInstanceService` Responsibilities The master-side service needs to handle: CRUD on `CmsInstance`, status push to slave (HTTP), and auto-registration (HTTP). How should these responsibilities be organized? A) **Single unified `CmsInstanceService`** — one service handles CRUD (EF Core), HTTP status push, and auto-registration. Simple; consistent with the existing single-service pattern (e.g. `PersistentAvailabilityService`). B) **Split: `CmsInstanceRepository` + `CmsInstanceService`** — repository handles EF Core data access; service handles business orchestration (status push, registration). Cleaner separation; slightly more files. C) **Split: `CmsInstanceService` (CRUD) + `SlaveStatusService` (HTTP calls)** — data + business logic in one service; all HTTP slave interactions in a dedicated service. Best for unit testing HTTP logic separately. D) Other [Answer]: B --- ### Q5 — Master-Side Controller Granularity The Master module needs REST endpoints for: listing slaves, adding a slave, and setting slave status. Which controller structure is preferred? A) **Single `CmsInstanceController`** — all actions in one controller: `GET /api/cms-instances`, `POST /api/cms-instances`, `PUT /api/cms-instances/{id}/status`. Consistent with how `AvailabilityController` works. B) **Two controllers** — `CmsInstanceController` for CRUD (`GET`, `POST`) and `CmsInstanceStatusController` for the `PUT /status` action. Clearer separation of read vs. write-with-side-effect. C) Other [Answer]: A --- ### Q6 — Slave-Side Internal Endpoint Placement The slave needs an internal registration endpoint (`POST /api/internal/master/register`) (FR-MASTER-03). Where should this endpoint be defined? A) **New `MasterRegistrationController`** in `SlpModularCms.Modules.Availability` — a dedicated controller for internal master endpoints. Clean; extensible if more internal endpoints are needed. B) **Added to the existing `AvailabilityController`** — keeps all availability-related endpoints in one file. Simpler; no extra controller class. C) Other [Answer]: B --- ### Q7 — Frontend: CMS Page API Hooks Organization The frontend `/cms` page needs TanStack Query hooks for: listing CMS instances, adding an instance, and updating status. How should the API hooks be organized? A) **Single `useCmsInstances` hook file** — one file exports all hooks: `useCmsInstances()`, `useAddCmsInstance()`, `useUpdateCmsInstanceStatus()`. Consistent and simple. B) **Separate hook files per concern** — `useCmsInstances.ts`, `useAddCmsInstance.ts`, `useUpdateCmsInstanceStatus.ts`. More files, but each file is focused. C) **Follow existing pattern** — check how existing hooks (e.g. availability hooks) are organized and mirror that pattern. D) Other [Answer]: B --- ## Execution Steps After all questions above are answered, the following artifacts will be generated: - [x] **Step 1** — Analyze all answers; flag any ambiguities for follow-up - [x] **Step 2** — Generate `components.md` with component definitions and responsibilities - [x] **Step 3** — Generate `component-methods.md` with method signatures and purpose - [x] **Step 4** — Generate `services.md` with service definitions and orchestration patterns - [x] **Step 5** — Generate `component-dependency.md` with dependency matrix and data flow diagrams - [x] **Step 6** — Generate `application-design.md` consolidating all design artifacts - [x] **Step 7** — Validate all content (Mermaid diagrams, no ASCII trees, color styles present) - [x] **Step 8** — Update `aidlc-state.md` to mark Application Design as In Progress → Complete - [x] **Step 9** — Present completion message for user approval --- *Artifact path*: `aidlc-docs/features/master-cms-module/inception/plans/application-design-plan.md`