Files
sor/SOR.Admin.12FactorPlan.md
T
2026-07-02 13:09:05 -04:00

17 KiB

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:

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:

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<TContext> 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.