# SOR.Admin 12-Factor Refactor Plan Date: 2026-06-10 Scope reviewed: - `Server/src/SOR.Admin` - `Server/Dockerfile.admin` - Admin dependencies in `SOR.Ai`, `SOR.Cdn`, `SOR.Database`, `SOR.Networking.Nats`, and `SOR.Shared` - Admin Blazor pages under `Server/src/SOR.Admin/Components/Pages` Reference: https://12factor.net/ ## Executive Summary `SOR.Admin` is a separate deployable Blazor Server application, not a service module inside `SOR.Host`. It already has several 12-Factor-friendly traits: its own Dockerfile, port binding through ASP.NET Core, Keycloak OIDC authentication, Redis-backed DataProtection keys for multi-pod cookie compatibility, environment-overridable configuration, and explicit dependencies on PostgreSQL, Redis, NATS, CDN/S3-compatible storage, and Keycloak. The main gaps are structural and operational: - `Program.cs` is a large composition root that configures auth, SignalR, Identity, Redis, DataProtection, NATS, AI services, CDN, all DbContexts, forwarded headers, routes, migrations, and OIDC discovery. - The app runs all schema migrations during normal web startup. - Most Blazor pages inject `DbContext` directly and contain query, command, validation, and UI logic together. - Several admin pages are very large, especially `AbilityBuilder.razor`, `CardEditor.razor`, `BoardTemplateBuilderPage.razor`, `AccountDetail.razor`, `TileModelManagerPage.razor`, and `CdnBrowser.razor`. - Admin depends on every database schema, which is valid for an admin console but needs explicit readiness and operational boundaries. - CDN and file upload paths are mixed into UI components. - `FeatureFlags.razor` says Redis feature flag wiring is pending even though Redis is registered in `Program.cs`. - External browser assets are loaded from public CDNs at runtime. - Health is liveness-only; readiness does not account for PostgreSQL, Redis, NATS, CDN, or Keycloak. The plan is to keep `SOR.Admin` as a separate deployable admin web app, but split startup, move page logic behind application services, separate one-off maintenance tasks from runtime startup, and add typed config, readiness checks, and auditability. ## Current Structure Observations ### Strong Foundations - `SOR.Admin` is its own executable project and Docker image. - Keycloak OIDC protects the app with a fallback policy requiring the `sor-admin` role. - Redis-backed DataProtection keys allow multiple Admin pods to decrypt the same auth cookies. - The app supports TLS-terminating ingress through forwarded headers. - `Dockerfile.admin` uses separate build and runtime stages and runs as a non-root user. - Admin pages cover the expected operational domains: accounts, cards, collection, bazaar, chat, game, content, AI, support, versioning, website, and reports. - CDN operations are behind `ICdnClient` for uploads, even though some components also use S3 directly for browsing. ### Main Problems - Runtime startup applies migrations for all contexts. - `Program.cs` has too many responsibilities and no typed admin-specific options. - Redis connection defaults to `localhost:6379` if not configured. - NATS defaults to `nats://localhost:4222` if not configured. - SignalR maximum receive size is hardcoded to 100 MB. - Cookie lifetime and admin role name are hardcoded. - Identity password policy for admin account-management pages is hardcoded. - OIDC discovery is checked at startup but failure is logged rather than affecting readiness. - Data access is spread across Razor components through direct `DbContext` injection. - Some pages perform high-impact operations such as account banning, collection changes, chat moderation, content edits, and CDN uploads without a central audit boundary. - There is no visible `Server/tests/SOR.Admin.Tests` project. ## Target Admin Shape Keep `SOR.Admin` as the deployable web admin app, but split it into focused areas: ```text Server/src/SOR.Admin/ Program.cs Configuration/ AdminOptions.cs AdminAuthOptions.cs AdminUploadOptions.cs AdminDependencyOptions.cs AdminOptionsValidator.cs Bootstrap/ AdminAuthentication.cs AdminAuthorization.cs AdminDataProtection.cs AdminDatabases.cs AdminInfrastructure.cs AdminEndpoints.cs AdminHealthChecks.cs Application/ Accounts/ Cards/ Content/ Bazaar/ Game/ Chat/ Collection/ Support/ Website/ Ai/ FeatureFlags/ Components/ Pages/ Shared/ Audit/ IAdminAuditLog.cs AdminAuditEvent.cs Operations/ MigrationRunner.cs SeedRunner.cs ``` `Program.cs` should become startup orchestration only: ```csharp var builder = WebApplication.CreateBuilder(args); builder.Services.AddAdminOptions(builder.Configuration); builder.Services.AddAdminAuthentication(builder.Configuration); builder.Services.AddAdminAuthorization(builder.Configuration); builder.Services.AddAdminDataProtection(builder.Configuration); builder.Services.AddAdminInfrastructure(builder.Configuration); builder.Services.AddAdminApplicationServices(); builder.Services.AddAdminHealthChecks(builder.Configuration); var app = builder.Build(); app.UseAdminPipeline(); app.MapAdminEndpoints(); await app.RunAsync(); ``` ## 12-Factor Gap Map ### I. Codebase Status: Mostly aligned. Current state: - `SOR.Admin` is in the same monorepo but is a separate executable and Docker image. Plan: - Keep Admin in the monorepo. - Document Admin as its own deployable web process. - Avoid coupling Admin runtime startup to unrelated service runtime behavior. ### II. Dependencies Status: Mostly aligned, with frontend asset and layering gaps. Current state: - NuGet dependencies are centrally versioned. - Admin references `SOR.Ai`, `SOR.Cdn`, `SOR.Database`, `SOR.Networking.Nats`, and `SOR.Shared`. - Browser CSS/icons are loaded from jsDelivr at runtime. Plan: - Keep server dependencies explicit. - Vendor or package frontend assets through the build instead of relying on public CDN availability at runtime. - Move direct S3 browsing logic behind a CDN browser service. - Avoid adding service-module references unless Admin actually needs runtime behavior from them. ### III. Config Status: Partially aligned. Current state: - Keycloak values, connection strings, and CDN values can be overridden by env vars. - Several operational values are hardcoded. Plan: - Add typed options and startup validation for: - `Admin:RequiredRole` - `Admin:CookieHours` - `Admin:SignalRMaxMessageBytes` - `Admin:MaxUploadBytes` - `Admin:RunMigrationsOnStartup` - `Admin:TrustForwardedHeaders` - `Keycloak` - `ConnectionStrings` - `Redis` - `Nats` - `Cdn` - In production, fail fast when required backing-service config is absent instead of silently defaulting to localhost. ### IV. Backing Services Status: Mostly aligned, but readiness is incomplete. Current state: - Admin depends on PostgreSQL schemas, Redis, Keycloak, CDN/S3-compatible storage, and NATS. - DataProtection keys are stored in Redis. Plan: - Treat all backing services as attachable resources via config. - Add readiness checks for: - identity database - catalog database - collection database - bazaar database - chat database - game database - support database - Redis - Keycloak discovery - NATS when AI/admin messaging is enabled - CDN/S3 when content upload/browser features are enabled - Keep DataProtection key storage in Redis for multi-pod deployments. ### V. Build, Release, Run Status: Partially aligned. Current state: - Docker build and runtime stages are separate. - Runtime startup applies migrations for every context. Plan: - Keep Docker build/release separation. - Move migrations out of web runtime startup into a release/admin process. - Add a release checklist: - build image - run tests - run database migrations - seed roles if needed - deploy Admin runtime - Keep `RunMigrationsOnStartup` only as an explicit local-development escape hatch. ### VI. Processes Status: Partially aligned. Current state: - Admin is a stateful-feeling Blazor Server process because user interaction lives on SignalR circuits. - Correctness state lives in backing services, not process memory. - AI calibration and self-play jobs are registered inside the Admin web process. Plan: - Keep Admin web process focused on interactive admin UI. - Move long-running AI calibration/self-play operations to explicit job services or admin-triggered background jobs with durable status. - Avoid running expensive maintenance work inline on the Blazor circuit. - Ensure Admin can run multiple replicas without per-process correctness assumptions. ### VII. Port Binding Status: Aligned. Current state: - Admin binds through ASP.NET Core and Docker exposes `8080`. - It is designed to sit behind TLS-terminating ingress. Plan: - Keep port binding in Admin. - Keep forwarded-header behavior configurable and documented. - Add explicit ingress/OIDC redirect URI runbook entries. ### VIII. Concurrency Status: Partially aligned. Current state: - Blazor Server circuits can hold scoped services for a long time. - Pages inject EF Core DbContexts directly. - Some components already note stale DbContext/concurrency issues. Plan: - Prefer `IDbContextFactory` or short-lived application service scopes for page operations. - Move write operations into application services with transaction boundaries. - Add optimistic concurrency handling for content and catalog editors. - Add per-operation cancellation and timeout behavior for uploads and long queries. - Prevent large page components from retaining stale tracked entities for too long. ### IX. Disposability Status: Partially aligned. Current state: - Web startup can block on migrations and OIDC discovery. - Redis connection is eagerly created. - Long-running admin operations may execute inside the web process. Plan: - Keep startup fast by moving migrations to release/admin process. - Make readiness account for OIDC discovery instead of only logging failures. - Ensure long-running jobs can be cancelled or resumed. - Use bounded upload sizes and cancellation tokens for CDN uploads. ### X. Dev/Prod Parity Status: Partially aligned. Current state: - Local defaults exist in `appsettings.json`. - Production depends on Keycloak, Redis, PostgreSQL, CDN, and NATS. Plan: - Document local Admin dependencies and setup: - PostgreSQL - Redis - Keycloak or a local OIDC test realm - CDN/S3-compatible storage - NATS for AI-triggering features - Keep config keys identical across environments. - Use feature toggles to disable unavailable local backing services cleanly. ### XI. Logs Status: Partially aligned. Current state: - Admin uses ASP.NET Core logging. - Some high-impact admin actions are not centralized for audit logging. Plan: - Keep logs as stdout event streams. - Add structured audit logging for: - account creation - role changes - bans/unbans - session revocation - catalog/card edits - CDN uploads/deletions - bazaar/store edits - chat moderation - game/session interventions - feature flag changes - Avoid logging secrets, access tokens, raw cookies, or CDN credentials. ### XII. Admin Processes Status: Needs work. Current state: - Admin web startup currently runs migrations. - Admin also exposes interactive pages for operational actions. Plan: - Separate one-off admin processes from Admin web runtime: - migrate all databases - seed roles and initial admin users - repair content metadata - cleanup stale sessions/uploads - run AI calibration jobs - validate Keycloak/OIDC setup - Keep web Admin as a UI for invoking or monitoring operations, not the only executor of maintenance work. ## Refactor Phases ### Phase 0: Baseline and Tests Deliverables: - Add `Server/tests/SOR.Admin.Tests`. - Add tests for: - config validation - auth policy requiring `sor-admin` - route authorization defaults - health and readiness endpoint behavior - core application services after extraction - Add smoke tests for page-level critical flows where feasible. Acceptance: - Startup behavior and security defaults are covered before refactoring. ### Phase 1: Split Program Startup Deliverables: - Extract authentication/OIDC setup. - Extract authorization setup. - Extract Redis/DataProtection setup. - Extract database registration. - Extract NATS/CDN/AI service registration. - Extract HTTP pipeline and endpoints. Acceptance: - `Program.cs` is short and reads as orchestration. - Startup behavior is unchanged except for intentional validation. ### Phase 2: Typed Options and Validation Deliverables: - Add admin options classes. - Validate Keycloak authority/client/secret requirements. - Validate Redis, NATS, CDN, upload, SignalR, and cookie settings. - Remove localhost fallback behavior in production. Acceptance: - Bad production config fails before serving requests. ### Phase 3: Move Migrations to Admin Process Deliverables: - Extract `MigrateAllAsync` into a reusable migration runner. - Add explicit command/process for migrations. - Make startup migrations disabled by default in production. Acceptance: - Admin web startup does not mutate database schemas unless explicitly configured for local development. ### Phase 4: Application Services Per Domain Deliverables: - Add focused application services for: - accounts - cards/catalog - ability builder - content/CDN - bazaar - chat moderation - game operations - support - website content - AI operations - feature flags - Move page write logic into services. Acceptance: - Razor components no longer directly own persistence rules for high-impact mutations. ### Phase 5: Component Decomposition Deliverables: - Split large components: - `AbilityBuilder.razor` - `CardEditor.razor` - `BoardTemplateBuilderPage.razor` - `AccountDetail.razor` - `TileModelManagerPage.razor` - `CdnBrowser.razor` - Move repeated editor/picker/upload UI into shared components. - Move non-UI logic to services. Acceptance: - Large pages become composable views over testable services. ### Phase 6: Health, Readiness, and Observability Deliverables: - Keep `/health` as liveness. - Add `/ready` for dependency readiness. - Add readiness checks for required databases, Redis, Keycloak, NATS, and CDN where enabled. - Add admin audit event logging. Acceptance: - Kubernetes can keep Admin out of rotation when dependencies are unavailable. - High-impact admin actions have a traceable audit trail. ### Phase 7: Feature Flags and Operational Jobs Deliverables: - Wire `FeatureFlags.razor` to Redis through a service. - Add explicit job/operation services for AI calibration and maintenance actions. - Add durable job status if operations can outlive the circuit. Acceptance: - Admin can manage feature flags through the UI. - Long-running operations are not tied to a single Blazor circuit. ### Phase 8: Frontend Asset and Upload Hardening Deliverables: - Vendor Bootstrap and Bootstrap Icons or package them as static assets. - Make upload size limits configurable. - Add CDN upload validation for extension/content type/size. - Add cancellation and timeout handling for upload operations. Acceptance: - Admin runtime does not depend on public frontend CDNs. - Upload behavior is explicit and controlled. ## Suggested Milestone Order 1. Add Admin tests for startup/security defaults. 2. Split `Program.cs` into bootstrap modules. 3. Add typed options and production validation. 4. Move migrations to explicit release/admin process. 5. Add readiness endpoint and dependency checks. 6. Extract application services for high-impact domains. 7. Decompose the largest Razor components. 8. Add audit logging for admin mutations. 9. Wire feature flags to Redis through a service. 10. Harden frontend assets and uploads. ## Risk Register | Risk | Why It Matters | Mitigation | |---|---|---| | Migration behavior changes | Admin currently migrates all schemas on startup. | Add explicit migration command and local-only compatibility flag. | | Auth redirect loops | OIDC, cookies, DataProtection, and forwarded headers are sensitive. | Preserve current behavior with tests before refactoring. | | Stale EF tracking in Blazor circuits | Long-lived circuits can hold stale DbContexts/entities. | Use short-lived services or `IDbContextFactory`. | | Large component regressions | Admin editors contain complex workflows. | Extract services first, then split UI in small steps. | | Missing audit trail | Admin actions can alter production state. | Add centralized audit logging around write services. | | Upload overload | Blazor Server uploads flow through SignalR. | Configurable limits, validation, and cancellation. | | External CDN outage | Bootstrap/jsDelivr outage affects Admin UI. | Vendor frontend assets in the app build. | ## Definition of Done The Admin refactor is complete when: - `Program.cs` is only startup orchestration. - Admin config is typed, validated, and production-safe. - Runtime web startup does not apply migrations by default. - `/health` and `/ready` have distinct meanings. - Admin pages call application services for data access and mutations. - Large Razor components are decomposed into smaller components and services. - Admin operations have structured audit logging. - Redis-backed DataProtection remains configured for multi-pod deployments. - Keycloak/OIDC, Redis, PostgreSQL, NATS, and CDN dependencies are represented in readiness. - Long-running maintenance and AI calibration work runs as explicit jobs or admin processes, not hidden web startup behavior.