slp-modular-cms/aidlc-docs/features/gitea-deployment-workflow/construction/plans/u7-documentation-code-generation-plan.md

Code Generation Plan — U7 Repository Documentation

Unit Context

• Unit: U7 Repository Documentation (Documentation-only — no components, no code)
• Requirements: FR-09
• Depends on: U6 (settled host layout — unit-of-work-dependency.md: "U6 before U7 — documentation cannot precede the layout it documents")
• No Functional/NFR/Infrastructure Design, no test project: per the execution plan, this unit goes straight to Code Generation
• Scope split (Q8 of Requirements = A): repository documentation here; operational documents (host setup, rollback, FTPS switch) belong to the Operations phase, not this unit

Steps

• Step 1: Create WEBSITE_WORKSPACE.md at the repository root — the website workspace contract (FR-09): target path wwwroot/web/ and required structure (must include index.html), forbidden paths (wwwroot/admin/, the application root), reserved paths (/admin, /api/v1, /health), SPA-fallback behaviour (non-file paths fall back to the website's own index.html; paths with a file extension 404 if missing), calling /api/v1 same-origin with relative URLs (no CORS needed), which CSP policy applies to the public website (Relaxed, the default policy — /admin, /api/v1 and /health get Strict) and what that permits, and how to include the Umami tracking script

• Step 2: Update README.md

  • New wwwroot layout: / → wwwroot/web/ (customer website, deployed separately, persists across releases), /admin → wwwroot/admin/ (this repo's admin SPA), link to WEBSITE_WORKSPACE.md for the full contract
  • /health endpoint: what it proves (process liveness only) and what it explicitly does not mean (not the same as Availability/status or System/capabilities)
  • Production setup section rewritten for what U1–U6 actually built: CI/CD via Gitea Actions (continuous_integration.yaml → deploy-scp.yaml), atomic release switching, and the Data Protection key ring being automatic now (removing the old manual "you must configure a persistent key ring" instruction, since U2 already wires PersistKeysToDbContext by default)
  • New runtime configuration environment variables introduced by U3/U4: SecurityHeaders__*, Observability__SentryDsn, plus the frontend's VITE_SENTRY_DSN / VITE_UMAMI_SCRIPT_URL / VITE_UMAMI_WEBSITE_ID

• Step 3: Update frontend/.env.example

  • Document the same-origin default: an absent or empty VITE_API_BASE_URL now means same-origin (the production default, since the SPA and API are served by one process); explicit absolute URLs still work unchanged for local development
  • Add the new observability variables: VITE_SENTRY_DSN, VITE_APP_ENV, VITE_UMAMI_SCRIPT_URL, VITE_UMAMI_WEBSITE_ID, each documented as optional/absent-is-supported

• Step 4: Verify documentation accuracy against the code as built (Definition of Done)

  • Cross-checked every path, config key and behaviour claim against the actual U1–U6 source: Program.cs fallback/placeholder wiring, SlpModularCms.Api.csproj's BuildAndCopyAdminFrontend and embedded WebsitePlaceholder.html, AvailabilityMiddleware._bypassPrefixes, U2's MigrateCoreDatabase() fail-fast and PersistKeysToDbContext discriminator, U3's PathPolicies fail-at-startup and Relaxed/Strict split in appsettings.json, U4's Sentry/Umami absent-is-supported behaviour, U6's linux-arm64 framework-dependent publish and atomic release switch. No discrepancies found between the design record and what was actually built — all documentation claims verified directly against source

Story / Requirement Traceability

Step	Covers
1	FR-09
2	FR-07, FR-08, FR-10 (documented, not re-implemented), FR-12 (key ring note)
3	FR-13, FR-14, FR-15, FR-16 (documented, not re-implemented)
4	Definition of Done: "documentation is accurate against the code as built in U1–U6"