slp-modular-cms/aidlc-docs/features/master-cms-module/construction/plans/documentation-code-generation-plan.md

Code Generation Plan — Unit 4: documentation

Unit Context

• Scope: Update README.md (root) with a Master CMS Module section covering the new module, migrations, and production env vars; replace the default Vite template frontend/README.md was never actually replaced by Unit 3 and still contains boilerplate — bring it in line with the rest of the documented feature set.
• Depends on: Units 1-3 (master-backend, slave-availability-extension, frontend-cms-page) — documents their final, built-and-tested patterns.
• No new code: Documentation only; no business logic, no NFRs, no tests. Functional Design / NFR Requirements / NFR Design were correctly skipped for this unit.

Steps

• Step 1 — Root README: Add "Master CMS Module" section Add a new ## Master CMS Module section to README.md after the existing "Nieuwe Module Toevoegen" section, covering:

  • What the module does (Owner registers/manages slave CMS instances; slaves enforce master-controlled availability)
  • Architecture summary: SlpModularCms.Modules.Master (per-module MasterDbContext), extended SlpModularCms.Modules.Availability (slave-side MasterRegistration + two-phase AvailabilityMiddleware)
  • Registration flow: Owner adds a slave URL via /cms → Master generates an API key → Master pushes registration to the slave's /api/v1/master/register (X-Master-Api-Key header)
  • Status flow: Owner toggles status on Master → Master pushes to slave synchronously → fail-open on push failure (DB change not rolled back) → IntegrityCheckBackgroundService retries/reconciles on IntegrityCheckIntervalMinutes (default 60)
  • Fail-open behavior: slave defaults _masterIsAvailable = true at startup; no TTL on cached status

• Step 2 — Root README: Extend "Database Migraties" section Add a subsection noting that SlpModularCms.Modules.Master and SlpModularCms.Modules.Availability are per-module DbContexts with their own migrations, applied automatically at startup via Database.Migrate(). Document the exact commands:

  dotnet ef migrations add <Naam> --project src\SlpModularCms.Modules.Master --startup-project src\SlpModularCms.Api
  dotnet ef migrations add <Naam> --project src\SlpModularCms.Modules.Availability --startup-project src\SlpModularCms.Api --context AvailabilityDbContext
  

  Note the --context requirement for the Availability project (it now hosts two logical concerns sharing one AvailabilityDbContext, but dotnet ef needs disambiguation because the API composes multiple DbContext types across modules).

• Step 3 — Root README: Extend "Productie Setup" section Add the new production-relevant configuration:

  • MasterModule options actually consumed by the code (bound from config section MasterModule): IntegrityCheckIntervalMinutes (default 60), HttpTimeoutSeconds (default 10), MasterUrl. Revised during execution: CacheMinutes and ApiKey are declared on MasterModuleOptions but never read anywhere in the codebase (verified via dotnet-appsettings skill pass) — they were superseded by Unit 2's actual design (per-instance encrypted keys, no-TTL cache). Left undocumented here per user decision; tracked as TD-001 in the new tech-debt-backlog feature instead of documenting dead config as if live.
  • Data Protection key ring warning (per NFR tech-stack-decisions.md): the API key encryption uses ASP.NET Core Data Protection with the default file-system key store. For containerized/multi-instance deployments, configure a persistent key ring (PersistKeysToDbContext, PersistKeysToAzureBlobStorage, etc.) — otherwise a container restart makes all stored ApiKey values undecryptable, breaking master↔slave communication until instances are re-added.
  • Added during execution: actual MasterModule config section added to appsettings.json and appsettings.Development.json (was completely missing before this unit, discovered via the dotnet-appsettings skill pass).

• Step 4 — Replace frontend/README.md Replace the default Vite/React template content with a short pointer document: describe the frontend briefly and redirect to the root README.md's "Frontend Development (CMS Admin UI)" section, which already documents setup, scripts, and configuration in full. Avoids duplicating content that already exists and stays in sync.

• Step 5 — Update feature state Mark Unit 4 (documentation) Code Generation complete in aidlc-docs/features/master-cms-module/aidlc-state.md; update aidlc-docs/active-features.md status.

Deviations From Plan (logged during execution)

• Missing EF migration found & fixed: SlpModularCms.Modules.Availability had no migration for MasterRegistration (Unit 2 gap). Generated during Build & Test, before this unit started — see aidlc-docs/features/master-cms-module/construction/build-and-test/build-and-test-summary.md.
• Lint baseline correction: the "all pre-existing" claim for frontend lint findings in the Build & Test summary was based on a contaminated comparison; corrected via a clean git worktree checkout. 2 of the 6 lint findings are new (Unit 3); all 6 moved to tech-debt-backlog (TD-002/TD-003) rather than fixed in-flight, per user decision.
• appsettings gap found & fixed: MasterModule config section was entirely absent from appsettings.json/appsettings.Development.json despite MasterModuleOptions.BindConfiguration("MasterModule") in code. Added both files during this unit's execution (see Step 3).