17 KiB
SOR.Admin 12-Factor Refactor Plan
Date: 2026-06-10
Scope reviewed:
Server/src/SOR.AdminServer/Dockerfile.admin- Admin dependencies in
SOR.Ai,SOR.Cdn,SOR.Database,SOR.Networking.Nats, andSOR.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.csis 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
DbContextdirectly 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, andCdnBrowser.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.razorsays Redis feature flag wiring is pending even though Redis is registered inProgram.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.Adminis its own executable project and Docker image.- Keycloak OIDC protects the app with a fallback policy requiring the
sor-adminrole. - Redis-backed DataProtection keys allow multiple Admin pods to decrypt the same auth cookies.
- The app supports TLS-terminating ingress through forwarded headers.
Dockerfile.adminuses 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
ICdnClientfor uploads, even though some components also use S3 directly for browsing.
Main Problems
- Runtime startup applies migrations for all contexts.
Program.cshas too many responsibilities and no typed admin-specific options.- Redis connection defaults to
localhost:6379if not configured. - NATS defaults to
nats://localhost:4222if 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
DbContextinjection. - 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.Testsproject.
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.Adminis 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, andSOR.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:RequiredRoleAdmin:CookieHoursAdmin:SignalRMaxMessageBytesAdmin:MaxUploadBytesAdmin:RunMigrationsOnStartupAdmin:TrustForwardedHeadersKeycloakConnectionStringsRedisNatsCdn
- 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
RunMigrationsOnStartuponly 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.csis 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
MigrateAllAsyncinto 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.razorCardEditor.razorBoardTemplateBuilderPage.razorAccountDetail.razorTileModelManagerPage.razorCdnBrowser.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
/healthas liveness. - Add
/readyfor 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.razorto 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
- Add Admin tests for startup/security defaults.
- Split
Program.csinto bootstrap modules. - Add typed options and production validation.
- Move migrations to explicit release/admin process.
- Add readiness endpoint and dependency checks.
- Extract application services for high-impact domains.
- Decompose the largest Razor components.
- Add audit logging for admin mutations.
- Wire feature flags to Redis through a service.
- 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.csis only startup orchestration.- Admin config is typed, validated, and production-safe.
- Runtime web startup does not apply migrations by default.
/healthand/readyhave 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.