155 lines
6.7 KiB
Markdown
155 lines
6.7 KiB
Markdown
# 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
|
|
|
|
[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`
|