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

Component Methods — Master CMS Module

Method signatures at the interface level. Detailed business rules and implementation logic are deferred to Functional Design (CONSTRUCTION phase).

⚠️ Partially superseded, found stale 2026-07-04: the IMasterAvailabilityService methods and /api/internal/master/* routes below describe an inception-stage pull design that construction did not build as-is (actual routes are /api/v1/master/*; the method set differs — see RegisterAsync/PushStatusAsync/GetRegisteredUrlAsync/GetMasterStatus in construction/slave-availability-extension/, plus 2026-07-04 additions GetPollTargetAsync/ApplyPolledStatusAsync/RecordPollFailureAsync). Treat the functional-design docs under construction/ as current truth for exact signatures.

---

Unit 1 — master-backend

ICmsInstanceRepository

Method	Signature	Purpose
GetAllAsync	Task<IReadOnlyList<CmsInstance>> GetAllAsync()	Returns all registered slave CMS instances
GetActiveAsync	Task<IReadOnlyList<CmsInstance>> GetActiveAsync()	Returns all non-Inactive instances (used by integrity check)
GetByIdAsync	Task<CmsInstance?> GetByIdAsync(Guid id)	Returns instance by primary key; null if not found
AddAsync	Task AddAsync(CmsInstance instance)	Adds new entity to the change tracker
UpdateAsync	Task UpdateAsync(CmsInstance instance)	Marks entity as modified in the change tracker
SaveChangesAsync	Task<int> SaveChangesAsync()	Persists pending changes via MasterDbContext

ICmsInstanceService

Method	Signature	Purpose
GetAllAsync	Task<IReadOnlyList<CmsInstanceDto>> GetAllAsync()	Returns all instances as DTOs; ApiKey excluded (NFR-MASTER-03)
AddAsync	Task<CmsInstanceDto> AddAsync(CreateCmsInstanceRequest request)	Creates entity, persists, triggers auto-registration with slave (FR-MASTER-03); returns DTO
UpdateStatusAsync	Task UpdateStatusAsync(Guid id, CmsInstanceStatus status, string? disableMessage)	Updates entity status, persists, pushes status to slave via HTTP (FR-MASTER-05); disableMessage required when status = NotAvailable (FR-MASTER-14)
VerifyIntegrityAsync	Task VerifyIntegrityAsync()	Called by IntegrityCheckBackgroundService; checks all active slaves have correct master URL; re-registers if mismatch (FR-MASTER-04)

ISlaveApiClient

Method	Signature	Purpose
RegisterMasterAsync	Task<bool> RegisterMasterAsync(string slaveUrl, string apiKey, string masterUrl)	POST /api/internal/master/register on slave; returns true on success (FR-MASTER-03)
PushStatusAsync	Task<bool> PushStatusAsync(string slaveUrl, string apiKey, CmsInstanceStatus status, string? disableMessage)	Pushes new status to slave's availability endpoint; returns true on success (FR-MASTER-05)
GetRegisteredMasterUrlAsync	Task<string?> GetRegisteredMasterUrlAsync(string slaveUrl, string apiKey)	GET slave's currently registered master URL; used for integrity check (FR-MASTER-04); null if no master registered

IntegrityCheckBackgroundService

Method	Signature	Purpose
ExecuteAsync	override Task ExecuteAsync(CancellationToken stoppingToken)	Main background loop; uses PeriodicTimer with interval from MasterModuleOptions.IntegrityCheckIntervalMinutes; creates IServiceScope per tick to resolve scoped services

CmsInstanceController

Method	HTTP	Route	Purpose
GetAll	GET	/api/v1/CmsInstances	Returns IReadOnlyList<CmsInstanceDto>
Add	POST	/api/v1/CmsInstances	Body: CreateCmsInstanceRequest; returns created CmsInstanceDto (201)
UpdateStatus	PUT	/api/v1/CmsInstances/{id}/status	Body: UpdateStatusRequest; returns 200 OK or 404 if not found

---

Unit 2 — slave-availability-extension

IMasterAvailabilityService

Method	Signature	Purpose
GetMasterStatusAsync	Task<MasterGateResult> GetMasterStatusAsync()	Checks DB for MasterRegistration; if no registration → returns HasMaster = false; if registration exists → returns cached or freshly-pulled status with fail-open fallback

MasterGateResult

Property	Type	Purpose
HasMaster	bool	Whether a master URL is registered on this slave
Status	CmsInstanceStatus?	Master-controlled status (null when HasMaster = false)
DisableMessage	string?	Message to include in 503 when Status = NotAvailable

AvailabilityController (new method)

Method	HTTP	Route	Purpose
RegisterMaster	POST	/api/internal/master/register	Header: X-Master-Api-Key; Body: RegisterMasterRequest; validates key, upserts MasterRegistration; returns 200 OK or 401 Unauthorized

RegisterMasterRequest

Property	Type	Notes
MasterUrl	string	Base URL of the Master CMS

AvailabilityMiddleware.InvokeAsync (extended signature)

public async Task InvokeAsync(
    HttpContext context,
    IAvailabilityService availabilityService,
    IMasterAvailabilityService masterAvailabilityService)

---

Unit 3 — frontend-cms-page

useCmsInstances

function useCmsInstances(): UseQueryResult<CmsInstance[], Error>

useAddCmsInstance

interface CreateCmsInstancePayload {
    name: string;
    url: string;
    apiKey: string;
}

function useAddCmsInstance(): UseMutationResult<CmsInstance, Error, CreateCmsInstancePayload>

useUpdateCmsInstanceStatus

interface UpdateStatusPayload {
    id: string;
    status: CmsInstanceStatus;
    disableMessage?: string;
}

function useUpdateCmsInstanceStatus(): UseMutationResult<void, Error, UpdateStatusPayload>

CmsInstance (TypeScript)

interface CmsInstance {
    id: string;
    name: string;
    url: string;
    status: CmsInstanceStatus;
    disableMessage?: string;
    lastContactedAt?: string;     // ISO 8601
    lastStatusPushedAt?: string;  // ISO 8601
}

enum CmsInstanceStatus {
    Available = 'Available',
    NotAvailable = 'NotAvailable',
    Inactive = 'Inactive',
}