slp-modular-cms/aidlc-docs/features/gitea-deployment-workflow/inception/application-design/components.md

Components

Component definitions and high-level responsibilities. Detailed business logic is designed per unit in Functional Design.

Placement rule (Q1 = A): every new cross-cutting concern lives in SlpModularCms.Core and is exposed as an extension method. Both hosts therefore get identical behaviour with no duplicated implementation. Q2 = A: SlpModularCms.Api.Slave receives everything except the static-file mounts, because it serves as a reference for what a customer-facing API instance looks like — not merely as a local dev tool.

---

New Components

C-01 SecurityHeadersMiddleware

• Project: SlpModularCms.Core (Hosting/Security/)
• Purpose: Apply HTTP security headers that would normally come from nginx or IIS configuration, which NFR-01 forbids relying on.
• Responsibilities:
  • Attach headers at response start, so the response content type is known before deciding what applies
  • Apply per-header scoping (FU1 = A): X-Content-Type-Options and Strict-Transport-Security on all responses; Content-Security-Policy, X-Frame-Options and Referrer-Policy on HTML responses only
  • Select the CSP policy for the request path
  • Never overwrite a header another component has already set
• Interfaces: standard middleware — InvokeAsync(HttpContext). Registered via UseCmsSecurityHeaders().
• Requirements: FR-18, SECURITY-04

C-02 SecurityHeadersOptions

• Project: SlpModularCms.Core (Hosting/Security/)
• Purpose: Bind the SecurityHeaders configuration section (Options pattern, consistent with JwtSettings, MasterModule, MasterPolling).
• Responsibilities: Carry the path-to-policy assignment, the default policy, and the environment-specific allowed origins.
• Design rule (Q5 = B + Q6 = B, confirmed FU2 = A): policy definitions live in code; path assignment and origins live in configuration. Adding a path later needs no code change; inventing a new policy does.
• Requirements: FR-18

C-03 CspPolicyBuilder

• Project: SlpModularCms.Core (Hosting/Security/)
• Purpose: Compose a Content-Security-Policy string from a named policy plus the configured origins.
• Responsibilities:
  • Define the two named policies in code: Strict (for /admin and /api/v1) and Relaxed (for the public website)
  • Inject the configured Umami script origin and Sentry ingest origin into the relevant directives
  • Build each policy once at startup rather than per request
• Rationale for existing separately from C-01: keeps policy composition unit-testable without a request pipeline, and keeps the middleware free of string building.
• Requirements: FR-18, D-31

C-04 Health-check registration

• Project: SlpModularCms.Core (Hosting/Health/)
• Purpose: Expose infrastructure liveness, strictly separate from CMS domain state.
• Responsibilities:
  • Register the framework health-check services (no package required)
  • Map GET /health returning 200/Healthy or 503/Unhealthy
  • Liveness only — no database call, no dependency probing (D-21)
• Explicit non-responsibility: this component says nothing about availability or capabilities. Those are CMS domain functionality and are never to be used for monitoring.
• Requirements: FR-10

C-05 CmsDataProtection registration

• Project: SlpModularCms.Core (Hosting/)
• Purpose: Persist the Data Protection key ring in the database so redeploys and atomic release switches cannot render stored slave API keys unreadable.
• Responsibilities: Configure PersistKeysToDbContext<ApplicationDbContext> and set a stable application discriminator so both hosts and all replicas derive the same keys.
• Requirements: FR-12, D-17

C-06 ApplicationDbContext extension — IDataProtectionKeyContext

• Project: SlpModularCms.Core (Data/) — modification of an existing component
• Purpose: Host the Data Protection keys table (Q7 = A).
• Responsibilities: Add DbSet<DataProtectionKey> DataProtectionKeys and implement IDataProtectionKeyContext. Requires one new Core migration.
• Why here rather than a fourth context: keys are application-wide infrastructure, not module-owned, and ApplicationDbContext now migrates automatically (FR-11) so the table is created without manual steps.
• Requirements: FR-12

C-07 Startup migration runner

• Project: SlpModularCms.Core (Hosting/)
• Purpose: Apply ApplicationDbContext migrations at startup, removing the need for CLI access on the host.
• Responsibilities:
  • Run Database.Migrate() for ApplicationDbContext during startup, before the request pipeline accepts traffic
  • Fail fast (Q8 = A): on failure, let the exception propagate so the process does not start
• Design interaction worth stating: fail-fast is what makes the liveness-only health check meaningful. A process that cannot migrate never starts, /health stops answering, and UptimeRobot goes red. Had this logged-and-continued, the app would look healthy while being unusable.
• Requirements: FR-11, D-13

C-08 CmsLogging registration

• Project: SlpModularCms.Core (Hosting/Observability/)
• Purpose: Configure structured logging, independent of whether Sentry is enabled (Q10 = B).
• Responsibilities: Console logging with structured output and a correlation/request identifier on every entry; exclude secrets and PII.
• Open item: OPEN-01 — the correlation-ID mechanism (ASP.NET Core TraceIdentifier versus W3C traceparent) is decided in NFR Design for Unit 4.
• Requirements: D-20, SECURITY-03

C-09 CmsSentry registration

• Project: SlpModularCms.Core (Hosting/Observability/)
• Purpose: Report errors and structured logs to Sentry, tagged by environment.
• Responsibilities:
  • Initialise Sentry.AspNetCore when a DSN is configured, and skip silently when it is not, leaving console logging active
  • Tag events with environment and release
  • Emit security-relevant events for alerting (FR-19)
• Separate from C-08 (Q10 = B): structured logging must work without Sentry.
• Requirements: FR-14, FR-19, D-19

C-10 Static-file mount composition

• Project: SlpModularCms.Api only — host-specific, not in Core (Q2 = A: the Slave has no static content)
• Purpose: Serve two independent front-ends from one process.
• Responsibilities (Q3 = A):
  • Mount wwwroot/web/ at / with its own PhysicalFileProvider
  • Mount wwwroot/admin/ at /admin with its own PhysicalFileProvider
  • Provide default-file handling per mount
  • Map two SPA fallbacks, preserving the nonfile route constraint so missing assets still return 404
• Design consequence: two explicit registrations rather than one, so each mount can later carry its own headers or caching without disturbing the other.
• Requirements: FR-07, FR-08, D-06

C-11 Deploy transport workflows

• Project: .gitea/workflows/ — not C#
• Purpose: Transfer a published release to a target host.
• Responsibilities (Q11 = B): one reusable workflow per transport, sharing an identical input interface. deploy-scp.yaml is implemented now; deploy-ftps.yaml can be added later without changing callers.
• Requirements: FR-02, D-02, NFR-09

C-12 CI workflow

• Project: .gitea/workflows/continuous_integration.yaml
• Purpose: Validate every change and drive deployment.
• Responsibilities: Six blocking gates, two environment-specific builds, artifact publication, and the calls into C-11 for test and production.
• Requirements: FR-01, FR-03, FR-04, FR-05

---

Modified Existing Components

C-13 AvailabilityMiddleware

• Project: SlpModularCms.Modules.Availability (Middleware/)
• Changes:
  1. Add /health to _bypassPrefixes so the availability gate cannot mask infrastructure liveness (FR-10, D-22)
  2. Fix IsAdminBypass to stop trusting an unvalidated token (FR-24, Q12 = A) — currently ReadJwtToken parses without signature verification, so an unauthenticated caller can forge an Owner claim and bypass the gate
• Behaviour that must be preserved: an Owner or Administrator with a valid token still passes, so administrators can always reach a disabled instance to switch it back on.
• Requirements: FR-10, FR-24

C-14 Frontend application configuration (frontend/src/lib/config.ts)

• Changes: treat an absent or empty VITE_API_BASE_URL as same-origin while still accepting an explicit absolute URL for local development against https://localhost:7221 / :7222. Zod validation relaxed accordingly, without silently accepting malformed values.
• Requirements: FR-13, D-14

C-15 Frontend observability

• Project: frontend/src/
• Changes: initialise @sentry/react with environment and release tags, skipping gracefully without a DSN; add the Umami tracking script with a per-environment website ID, absent during local development.
• Requirements: FR-15, FR-16

C-16 Host composition (Program.cs, both hosts)

• Changes: call the new Core extension methods in the correct order. Q9 = A: the two files stay separate — with the implementation in Core, what remains duplicated is an explicit list of calls, which is intentional readability rather than accidental duplication.
• Requirements: FR-07, FR-10, FR-11, FR-12, FR-14, FR-18

---

Component Summary

ID	Component	Project	Type	Slave gets it?
C-01	SecurityHeadersMiddleware	Core	New	Yes
C-02	SecurityHeadersOptions	Core	New	Yes
C-03	CspPolicyBuilder	Core	New	Yes
C-04	Health-check registration	Core	New	Yes
C-05	CmsDataProtection registration	Core	New	Yes
C-06	ApplicationDbContext keys table	Core	Modified	Yes
C-07	Startup migration runner	Core	New	Yes
C-08	CmsLogging registration	Core	New	Yes
C-09	CmsSentry registration	Core	New	Yes
C-10	Static-file mount composition	Api	New	No
C-11	Deploy transport workflows	.gitea/	New	n/a
C-12	CI workflow	.gitea/	New	n/a
C-13	AvailabilityMiddleware	Modules.Availability	Modified	Yes
C-14	Frontend config	frontend	Modified	n/a
C-15	Frontend observability	frontend	New	n/a
C-16	Host composition	Both hosts	Modified	Yes

14 code components (9 new, 5 modified) plus 2 workflow components.