slp-modular-cms/aidlc-docs/features/master-cms-module/inception/application-design/components.md

Components — Master CMS Module

⚠️ Partially superseded, found stale 2026-07-04: the slave-side IMasterAvailabilityService description below (static _cachedStatus/_lastFetchedAt, CacheMinutes-based staleness, /api/internal/master/* routes) describes an inception-stage design that construction did not build as-is — the actual implementation is push-based (/api/v1/master/*, _masterIsAvailable/_masterDisableMessage), plus a 2026-07-04 addition of a differently-shaped slave-pull (MasterStatusPollingBackgroundService + GET /api/v1/SlaveStatus, time-based fail-open). The Unit 1 (master-backend) component list above the slave-side section is accurate. See construction/master-backend/functional-design/*.md and construction/slave-availability-extension/functional-design/*.md for the as-built design. This gap predates 2026-07-04 and was found (not caused) during today's documentation audit.

Unit 1 — master-backend (SlpModularCms.Modules.Master)

MasterModule

• Type: Module registration (IModule)
• Responsibilities: Registers all master-side services (repository, service, typed HTTP client, background service, options); applies MasterDbContext migrations at startup via UseModule; does NOT register middleware (master instance has no availability gate)
• Interface: IModule (RegisterServices, UseModule)

MasterDbContext

• Type: EF Core DbContext
• Responsibilities: Per-module DbContext; owns the CmsInstances table and its migrations; migrations live in SlpModularCms.Modules.Master (NFR-MASTER-06)
• Entities owned: CmsInstance

CmsInstance

• Type: Domain Entity
• Responsibilities: Represents a registered slave CMS instance
• Fields:
  • Id — Guid, primary key
  • Name — string, friendly display name
  • Url — string, base URL of slave CMS API
  • ApiKey — string, secret used by Master to authenticate against slave; never returned in API responses (NFR-MASTER-03)
  • Status — CmsInstanceStatus enum (Available / NotAvailable / Inactive)
  • DisableMessage — string?, required when Status = NotAvailable
  • LastContactedAt — DateTimeOffset?
  • LastStatusPushedAt — DateTimeOffset?

CmsInstanceStatus

• Type: Enum
• Values: Available, NotAvailable, Inactive

ICmsInstanceRepository / CmsInstanceRepository

• Type: Repository (data access only)
• Responsibilities: CRUD operations on CmsInstance via MasterDbContext; no business logic
• Lifetime: Scoped

ICmsInstanceService / CmsInstanceService

• Type: Service (orchestration)
• Responsibilities: Business orchestration — calls repository for data access; calls ISlaveApiClient for HTTP side-effects (auto-registration, status push, integrity verification); enforces business rules (e.g., DisableMessage required when NotAvailable)
• Lifetime: Scoped

ISlaveApiClient / SlaveApiClient

• Type: Typed HTTP client
• Responsibilities: All Master → Slave HTTP communication (registration, status push, integrity check); adds X-Master-Api-Key header; handles HTTP errors and returns success flags
• Registration: services.AddHttpClient<ISlaveApiClient, SlaveApiClient>()
• Lifetime: Transient (managed by IHttpClientFactory)

CmsInstanceController

• Type: ASP.NET Core ControllerBase
• Responsibilities: REST API for slave CMS management; [Authorize(Policy = "OwnerOnly")]; delegates to ICmsInstanceService
• Route: /api/v1/CmsInstances
• Actions: GET list, POST add, PUT update status

IntegrityCheckBackgroundService

• Type: BackgroundService
• Responsibilities: Periodic background loop; verifies each non-Inactive slave still has the correct master URL registered; re-registers if mismatch found; interval configurable via MasterModuleOptions.IntegrityCheckIntervalMinutes (default 60)
• Pattern: Uses PeriodicTimer; injects IServiceScopeFactory to resolve scoped ICmsInstanceService per tick
• Lifetime: Singleton (as required by BackgroundService)

MasterModuleOptions

• Type: Configuration POCO
• Fields:
  • IntegrityCheckIntervalMinutes — int, default 60 (master-side)
  • CacheMinutes — int, default 60 (slave-side)
  • ApiKey — string (slave-side; key the slave uses to validate incoming master requests)
• Registration: services.Configure<MasterModuleOptions>(configuration.GetSection("MasterModule"))

DTOs and Request Models

Type	Fields	Notes
CmsInstanceDto	Id, Name, Url, Status, DisableMessage, LastContactedAt, LastStatusPushedAt	No ApiKey (NFR-MASTER-03)
CreateCmsInstanceRequest	Name, Url, ApiKey	API key stored securely, never returned
UpdateStatusRequest	Status, DisableMessage?	DisableMessage required when Status = NotAvailable

---

Unit 2 — slave-availability-extension (SlpModularCms.Modules.Availability)

MasterRegistration

• Type: Domain Entity
• Responsibilities: Stores the registered Master CMS URL on the slave side; zero or one records per slave (the slave knows at most one master)
• Fields:
  • Id — Guid, primary key
  • MasterUrl — string, base URL of the Master CMS
  • RegisteredAt — DateTimeOffset

AvailabilityDbContext

• Type: EF Core DbContext (new, per-module)
• Responsibilities: Per-module DbContext introduced in the Availability module for the slave-side entity; owns the MasterRegistrations table; migrations live in SlpModularCms.Modules.Availability
• Entities owned: MasterRegistration

IMasterAvailabilityService / MasterAvailabilityService

• Type: Service
• Responsibilities: Checks whether a master URL is registered (DB lookup); pulls master-controlled availability status via HTTP GET; caches last known status using static fields + timestamp (same pattern as PersistentAvailabilityService); implements fail-open fallback when master is unreachable; respects MasterModuleOptions.CacheMinutes
• Cache pattern: Static fields _cachedStatus (default Available) + _lastFetchedAt; stale check based on CacheMinutes
• Exemption (FR-MASTER-09): No special exemption logic needed — if no MasterRegistration record exists in DB (which is the case on a Master instance that never registered itself), the gate is skipped automatically
• Lifetime: Scoped (static fields provide cross-request caching)

AvailabilityMiddleware (extended)

• Type: ASP.NET Core Middleware
• Responsibilities: Extended with Master gate logic at the top of InvokeAsync; two-phase check:
  1. Master gate — calls IMasterAvailabilityService.GetMasterStatusAsync(); if no master registered → skip to local gate; if master says NotAvailable → 503 with DisableMessage; if unreachable → use cached/fallback value (fail-open)
  2. Local gate — existing IAvailabilityService check, unchanged
• Bypass prefixes: Extended to also bypass internal master endpoints (/api/internal/master/) so registration calls are never blocked

AvailabilityController (extended)

• Type: ASP.NET Core ControllerBase (existing class extended)
• Responsibilities: New action RegisterMaster added; validates X-Master-Api-Key header against configured MasterModuleOptions.ApiKey; upserts MasterRegistration in AvailabilityDbContext
• New route: POST /api/internal/master/register
• Authentication: API key validation (no JWT; the registration endpoint is called machine-to-machine)

RegisterMasterRequest

• Type: Request model
• Fields: MasterUrl — string

MasterGateResult

• Type: Result record
• Fields: HasMaster (bool), Status (CmsInstanceStatus?), DisableMessage (string?)

---

Unit 3 — frontend-cms-page (frontend/)

CmsPage

• Type: React page component
• Route: /cms
• Responsibilities: Owner-only route guard; fetches slave list via useCmsInstances; renders CmsInstanceList; manages dialog open state for Add and Set Status actions

CmsInstanceList

• Type: React component
• Responsibilities: Renders a table of CmsInstance items; shows Name, URL, Status badge, LastContactedAt, DisableMessage; Inactive rows are visually greyed out; provides action triggers (Add button, Set Status button per row)

AddCmsInstanceDialog

• Type: React component (modal dialog using shadcn/ui Dialog)
• Responsibilities: Form with fields Name, URL, ApiKey (all required); validates before submission; calls useAddCmsInstance mutation; closes on success

SetStatusDialog

• Type: React component (modal dialog using shadcn/ui Dialog)
• Responsibilities: Status dropdown (Available, NotAvailable, Inactive); DisableMessage text field rendered and required when status is NotAvailable; calls useUpdateCmsInstanceStatus mutation; closes on success

CmsInstanceStatus (TypeScript enum)

• Values: Available, NotAvailable, Inactive

CmsInstance (TypeScript type)

• Fields: id, name, url, status, disableMessage, lastContactedAt, lastStatusPushedAt

useCmsInstances

• Type: TanStack Query useQuery hook
• File: hooks/useCmsInstances.ts
• Responsibilities: GET /api/v1/CmsInstances; returns list of CmsInstance

useAddCmsInstance

• Type: TanStack Query useMutation hook
• File: hooks/useAddCmsInstance.ts
• Responsibilities: POST /api/v1/CmsInstances; invalidates useCmsInstances query on success

useUpdateCmsInstanceStatus

• Type: TanStack Query useMutation hook
• File: hooks/useUpdateCmsInstanceStatus.ts
• Responsibilities: PUT /api/v1/CmsInstances/{id}/status; invalidates useCmsInstances query on success

---

Unit 4 — documentation

No new components. Covers README updates only (FR-MASTER-15). See requirements for scope.