6.7 KiB
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<ISlaveApiClient, SlaveApiClient>(). 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
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
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
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
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
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
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
Execution Steps
After all questions above are answered, the following artifacts will be generated:
- Step 1 — Analyze all answers; flag any ambiguities for follow-up
- Step 2 — Generate
components.mdwith component definitions and responsibilities - Step 3 — Generate
component-methods.mdwith method signatures and purpose - Step 4 — Generate
services.mdwith service definitions and orchestration patterns - Step 5 — Generate
component-dependency.mdwith dependency matrix and data flow diagrams - Step 6 — Generate
application-design.mdconsolidating all design artifacts - Step 7 — Validate all content (Mermaid diagrams, no ASCII trees, color styles present)
- Step 8 — Update
aidlc-state.mdto mark Application Design as In Progress → Complete - Step 9 — Present completion message for user approval
Artifact path: aidlc-docs/features/master-cms-module/inception/plans/application-design-plan.md