19 KiB
SOR Game 12-Factor Refactor Plan
Date: 2026-06-08
Scope reviewed:
Server/src/SOR.Game- Runtime wiring in
Server/src/SOR.Host - Shared infrastructure in
Server/src/SOR.Database,SOR.Shared, networking abstractions, Dockerfile, and server architecture docs
Reference: https://12factor.net/
Executive Summary
SOR.Game already has a useful service-module boundary and dependency injection entry point, and the host already supports process-level service selection through ENABLED_SERVICES. Those are strong foundations for a 12-Factor-compatible backend.
The main issues are inside the game module shape and runtime behavior:
GameEngine.cs,AbilitySystem.cs,GameMessages.cs, andGameHandlerBase.cscarry too many responsibilities.- Several handlers contain orchestration, persistence, serialization, and push logic that should live behind services.
- Some runtime state is process-local (
VoteSessionService,RuleSuggestionService,GameActivityRegistry) or exposed through static singleton references. - Startup cleanup is embedded in app boot instead of being available as an explicit one-off operational process.
- Config is mostly environment-ready, but defaults and service-specific options are not consistently typed or validated.
- Health checks are liveness-only and do not yet reflect Redis, NATS, or database readiness.
- There is no visible test project under
Server/tests, even though the architecture doc expects service tests.
The plan below breaks the work into phases that improve structure first, then operational conformance.
Current Structure Observations
Strong Foundations
- One repository contains the server codebase and service modules.
Directory.Packages.propscentralizes NuGet versions.Directory.Build.propssets deterministic builds, nullable references, warnings as errors, and common target framework.SOR.Hostis the single deployable runtime and usesENABLED_SERVICESto select modules.SOR.Gameregisters itself throughAddGameService.- Redis, NATS, EF Core, and client push are represented as injected infrastructure.
Dockerfile.hostuses a build stage and runtime stage, exposes port8080, and runs as a non-root user.- Game spectators are already backed by Redis, which supports horizontal scale better than in-process memory.
Main Structural Problems
GameEngine.csis a large static rules engine mixing serialization, initialization, draw/play/move/attack/sacrifice/end-turn flow, DTO projection, deck validation, ELO calculation, and helper parsing.AbilitySystem.csis extremely large and likely combines parsing, validation, target resolution, execution, triggers, animations, pending prompts, and state mutation.GameHandlerBase.cscontains static helpers for pushing state, finalizing games, spectator handling, activity broadcasting, and ranking updates.- Handler classes often directly use EF Core, JSON serialization, push delivery, and game state mutation instead of delegating to focused application services.
GameMessages.csis a large message contract file; DTOs and request/response contracts are not grouped by workflow.- Static singleton references (
GameActivityRegistry.Instance,SpectatorRegistryService.Instance) make the code harder to test and reduce process-model clarity. VoteSessionService,RuleSuggestionService, andGameActivityRegistryare process-local. That means behavior can diverge across pods if game traffic is handled by more than onegameprocess.GameStartupCleanupServiceperforms operational repair during process startup. The behavior is useful, but 12-Factor admin-process guidance points toward a one-off task that can be run independently from normal web/process boot.
Target Architecture
Keep SOR.Game as the service module, but make its internal shape closer to this:
Server/src/SOR.Game/
ServiceRegistration.cs
Configuration/
GameOptions.cs
GameTimerOptions.cs
GameCleanupOptions.cs
Contracts/
Commands/
Responses/
Pushes/
Dtos/
Application/
Lobbies/
Sessions/
Turns/
Actions/
Spectating/
Activity/
Ranking/
Domain/
State/
Rules/
Abilities/
Combat/
Board/
Randomness/
Persistence/
IGameSessionRepository.cs
ICustomLobbyRepository.cs
IGamePresetRepository.cs
EfGameSessionRepository.cs
EfCustomLobbyRepository.cs
EfGamePresetRepository.cs
RuntimeState/
IVoteSessionStore.cs
RedisVoteSessionStore.cs
IRuleSuggestionStore.cs
RedisRuleSuggestionStore.cs
IGameActivitySubscriptionStore.cs
RedisGameActivitySubscriptionStore.cs
Operations/
GameStartupCleanupJob.cs
GameSessionRepairJob.cs
Handlers/
GameReadyHandler.cs
...
The goal is not to add layers for their own sake. The goal is to make handlers thin, make game rules testable without the host, and move horizontally shared runtime state into attached services.
12-Factor Gap Map
I. Codebase
Status: Mostly aligned.
Current state:
- One repo contains server projects.
- Deploy behavior is selected by config (
ENABLED_SERVICES), not by code forks.
Plan:
- Keep one repo and one
SOR.Hostdeployable for now. - Document each deploy type as a process formation:
gateway,game,ai,auth,content,allfor local development. - Add a clear ownership map for
SOR.Gamesubdomains after the refactor.
II. Dependencies
Status: Mostly aligned.
Current state:
- NuGet versions are centrally declared.
- Docker restore is explicit.
Plan:
- Keep central package management.
- Add a dependency audit task for game: identify direct dependencies from
SOR.Gameto concrete infrastructure and move them behind interfaces where they are not pure domain concerns. - Avoid adding new cross-module references from
SOR.Game; preferSOR.Networking.Abstractions,SOR.Shared, and explicit service contracts.
III. Config
Status: Partially aligned.
Current state:
- Connection strings and service URLs can be overridden via environment variables.
appsettings.jsoncontains local defaults and placeholder secrets.- Game-specific constants are scattered in services and handlers.
Plan:
- Add typed options for game configuration:
Game:TimersGame:CleanupGame:RulesDefaultsGame:RuntimeStateGame:Activity
- Validate options at startup with
ValidateOnStart. - Move hardcoded operational values into config where appropriate:
- startup cleanup stale threshold
- spectator TTL
- inactivity thresholds
- turn timer settings
- activity subscription TTL
- Keep secrets and production values out of committed JSON; use environment variables or secret providers.
IV. Backing Services
Status: Partially aligned.
Current state:
- PostgreSQL, Redis, NATS, CDN, and Keycloak are treated as configurable resources.
- Some game runtime state is still in memory.
Plan:
- Replace process-local runtime state with Redis-backed stores where behavior must survive pod changes:
- preset votes
- rule suggestions
- game activity subscribers
- Keep only truly per-process concerns in memory.
- Define Redis keys in
SOR.Shared.Redis.RedisKeys. - Define NATS subjects in
SOR.Shared.Nats.NatsSubjects. - Add readiness checks for required attached resources per enabled service.
V. Build, Release, Run
Status: Mostly aligned, with release gaps.
Current state:
- Docker build and runtime stages are separate.
- Runtime config is injected at run time.
- Database migrations are present, but operational application of migrations is not clearly separated from runtime.
Plan:
- Preserve Docker build/release separation.
- Define a release checklist:
- restore/build/test
- publish container
- run migrations as a one-off process
- start runtime process formation
- Avoid doing schema migration or repair work as implicit web process startup behavior.
VI. Processes
Status: Needs work.
Current state:
- Game process can run independently via
ENABLED_SERVICES=game. - Some mutable state is process-local or static.
Plan:
- Make game handlers and domain logic stateless between requests.
- Move shared ephemeral state into Redis.
- Remove static service lookups by converting static helper flows into injected services.
- Keep game state persistence in PostgreSQL, with Redis only for fast ephemeral coordination and push fanout.
VII. Port Binding
Status: Mostly aligned.
Current state:
- Host binds via ASP.NET Core/Kestrel.
- Docker exposes
8080. - Auth gRPC loopback binding is configured when co-located.
Plan:
- Keep HTTP/WebSocket port binding in
SOR.Host. - Ensure process-specific deploys have clear ports and health endpoints.
- Avoid hidden runtime dependencies on external web servers.
VIII. Concurrency
Status: Partially aligned.
Current state:
- Service selection supports multiple process types.
- NATS and Redis are available for cross-process coordination.
- In-process vote/suggestion/activity state makes multi-pod game scaling risky.
Plan:
- Define process types explicitly:
web/gatewaygame-workerai-workermatchmaking-workeradminmaintenance
- Add a concurrency model for game sessions:
- one command per session at a time
- optimistic concurrency or distributed lock for session state mutation
- idempotent command handling where clients may retry
- Move timers and inactivity monitors to a model that can run safely with multiple game workers.
IX. Disposability
Status: Partially aligned.
Current state:
- Hosted services use ASP.NET Core lifetime hooks.
- Startup cleanup handles some previous-process failure modes.
- Graceful shutdown behavior for game timers and in-flight game commands is not clearly isolated.
Plan:
- Ensure hosted services honor cancellation tokens consistently.
- Make session mutation operations transactionally safe so termination between state save and finalize can be repaired.
- Move cleanup/repair into idempotent jobs callable as admin processes.
- Keep startup fast; avoid large database scans during normal app boot.
X. Dev/Prod Parity
Status: Partially aligned.
Current state:
- Local defaults exist for Redis, NATS, PostgreSQL, Keycloak, CDN, and WebSocket settings.
ENABLED_SERVICES=allis convenient for development but differs from scaled production process formation.
Plan:
- Add a local compose/dev profile that runs Redis, NATS, PostgreSQL, and host process formations similarly to production.
- Document local development modes:
- single-process
all - production-like split process formation
- single-process
- Keep config names identical across dev/staging/prod; only values should differ.
XI. Logs
Status: Partially aligned.
Current state:
- Serilog writes to console, which is correct for event streams.
GameEngine.Attackstill writes directly withConsole.WriteLine.- Ability logging uses a static logger initializer.
Plan:
- Replace direct console writes with injected or passed logging abstractions.
- Remove static logger initialization from domain code over time.
- Keep all logs structured.
- Audit noisy
Debuglogs, especially ability/game action logs, so production can tune volume through config.
XII. Admin Processes
Status: Needs work.
Current state:
SOR.Toolsexists and can be the home for one-off tasks.GameStartupCleanupServicedoes repair work during process startup.- EF migrations exist but the production execution path is not fully documented here.
Plan:
- Move game cleanup/repair operations into explicit one-off tasks under
SOR.Toolsor a dedicatedSOR.Operationsproject. - Add commands:
game cleanup-stale-initializinggame repair-ghost-activedb migrate --context GameDbContextgame reconcile-session --session-id ...
- Keep runtime startup focused on starting the service, not performing maintenance.
Refactor Phases
Phase 0: Baseline and Safety Net
Deliverables:
- Add
Server/tests/SOR.Game.Tests. - Add unit tests around current behavior before moving code:
- deck validation
- turn-limit winner calculation
- ELO delta calculation
- board generation edge cases
- attack/sacrifice/end-turn golden scenarios
- ability trigger and pending-prompt scenarios
- Add serialization round-trip tests for
GameStateand key game DTOs. - Add a small integration test harness for handler-to-DbContext flows using test configuration.
Acceptance:
- Tests cover the high-risk behaviors before large file movement.
- No behavior changes are required in this phase.
Phase 1: Split Contracts and DTOs
Deliverables:
- Split
GameMessages.csinto workflow-focused files underContracts/. - Keep public type names stable to avoid client or handler churn.
- Group by domain:
- session messages
- lobby messages
- action messages
- ability prompt messages
- spectator messages
- activity messages
- ranking/outcome messages
Acceptance:
- Build passes.
- Existing message type names and serialized shapes remain compatible.
Phase 2: Introduce Application Services
Deliverables:
- Create focused application services:
GameSessionServiceGameLobbyServiceGameActionServiceGameStatePushServiceGameFinalizationServiceGameRankingServiceGameActivityService
- Move static helper logic out of
GameHandlerBase. - Handlers become thin command adapters:
- parse request
- call application service
- return response
Acceptance:
- Handler classes no longer directly coordinate game finalization, ranking updates, spectator lookup, and state fanout.
- Static singleton service references are removed from new paths.
Phase 3: Introduce Persistence Interfaces
Deliverables:
- Add repositories for game persistence:
- sessions
- lobbies
- presets
- board templates
- player decks/read models needed by game start
- Centralize JSON field serialization/deserialization for lobby/session extra-player data and rules snapshots.
- Keep EF Core implementations internal.
Acceptance:
- Application services can be unit tested without EF Core.
- Repeated JSON option setup and ad hoc parsing are reduced.
Phase 4: Split Domain Rules
Deliverables:
- Split
GameEngineinto smaller pure domain components:GameStateSerializerGameInitializerDeckValidatorTurnServiceCardPlayRulesMovementRulesCombatResolverGameOutcomeResolverEloCalculatorGameStateProjector
- Introduce an injectable randomness abstraction for shuffling and random tile selection.
- Keep pure rule methods free of EF Core, Redis, NATS, client push, and host dependencies.
Acceptance:
- Domain classes can be tested directly.
- Game command behavior remains compatible with current persisted
GameStateJSON.
Phase 5: Split Ability System
Deliverables:
- Split
AbilitySystemby responsibility:- model parsing and polymorphic conversion
- trigger matching
- condition evaluation
- target resolution
- cost resolution
- effect execution
- pending prompt creation
- animation/event projection
- Create golden tests for representative ability cards before and after the split.
Acceptance:
- Ability behavior remains compatible.
- New ability logic can be changed without editing one giant file.
Phase 6: Externalize Runtime State
Deliverables:
- Replace process-local stores with interfaces:
IVoteSessionStoreIRuleSuggestionStoreIGameActivitySubscriptionStore
- Implement Redis-backed stores with TTLs.
- Keep in-memory implementations only for tests or single-process local development if needed.
Acceptance:
- Multiple
gamepods can observe the same vote/suggestion/activity state. - Runtime state expires without requiring process cleanup.
Phase 7: Operational Jobs and Admin Processes
Deliverables:
- Move startup cleanup logic into reusable job classes.
- Add one-off commands in
SOR.Tools:- cleanup stale initializing sessions
- repair ghost active sessions
- migrate database contexts
- Make
GameStartupCleanupServiceoptional via config, then phase it down once operational jobs are in place.
Acceptance:
- Maintenance tasks can be run independently of normal service startup.
- Jobs are idempotent and safe to retry.
Phase 8: Config, Health, and Release Hardening
Deliverables:
- Add typed options and startup validation.
- Add per-service health checks:
- Redis
- NATS
- relevant database contexts
- optional external services per enabled module
- Define readiness vs liveness behavior.
- Document process formations and release steps.
Acceptance:
- A missing required config value fails fast.
/healthremains cheap liveness.- Readiness endpoint reflects backing service availability.
Suggested Milestone Order
- Create test project and golden tests for existing game behavior.
- Split
GameMessages.csinto contract groups. - Extract push/finalization/ranking from
GameHandlerBase. - Introduce application services and repositories.
- Split
GameEngine. - Split
AbilitySystem. - Redis-back runtime state currently held in singleton dictionaries.
- Move startup cleanup into one-off admin jobs.
- Add typed config, validation, and readiness checks.
- Update architecture docs after implementation stabilizes.
Risk Register
| Risk | Why It Matters | Mitigation |
|---|---|---|
| Ability regressions | AbilitySystem is large and likely encodes many card-specific edge cases. |
Golden tests before splitting, small mechanical moves first. |
| Game state compatibility | Persisted StateJson must keep loading existing active sessions. |
Serialization round-trip tests and version-tolerant DTO changes. |
| Multi-pod races | Multiple game workers can process commands for one session. | Add per-session command serialization or optimistic concurrency. |
| In-memory vote/suggestion loss | Current process-local state disappears on restart or cross-pod routing. | Move to Redis with TTL. |
| Startup repair side effects | Large cleanup during app boot can slow or destabilize deploys. | Move to idempotent admin jobs. |
| Static service references | Harder testing and hidden runtime coupling. | Replace with injected application services. |
Definition of Done
The refactor is complete when:
SOR.Gamehandlers are thin adapters.- Core game and ability rules are testable without ASP.NET Core, EF Core, Redis, or NATS.
- Shared ephemeral state required for correctness is stored in Redis or another backing service.
- Runtime startup is fast and does not rely on implicit maintenance work.
- Maintenance tasks can be run as one-off admin processes.
- Config values are environment-driven, typed, and validated.
- Logs are structured event streams with no direct
Console.WriteLinein game logic. - Health/readiness checks reflect the backing services required by the enabled process type.
- The production process model can scale game workers without changing code.