495 lines
17 KiB
Markdown
495 lines
17 KiB
Markdown
# 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<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.
|