CorePin is a Windows desktop application with a native background service, on-demand performance recorder, managed report engine, and standalone benchmark. The system is divided so that user interaction and analysis remain outside the latency-sensitive service and profiler processes.
This document describes the current component boundaries, runtime lifecycles, and invariants that future changes must preserve. File formats, configuration fields, build commands, and diagnostic procedures are documented separately.
flowchart LR
User["User"] --> UI["CorePin.UI"]
UI --> Config["Runtime configuration"]
UI <--> Database["Library and benchmark database"]
UI --> Request["One-shot recording request"]
Config --> Service["CorePin.Service"]
Request --> Service
Windows["Windows process events"] --> Service
Service --> Game["Game process"]
Service --> Profiler["CorePin.Profiler"]
Profiler --> Session["Performance session"]
Session --> Performance["CorePin.Performance"]
Performance --> UI
UI --> Benchmark["CorePin.Benchmark"]
Benchmark --> UI
The principal ownership split is:
- CorePin.UI owns user interaction, configuration authoring, game-library data, benchmark history, and report presentation.
- CorePin.Service owns process monitoring and temporary runtime changes for managed games.
- CorePin.Profiler records performance facts for one explicitly requested game session.
- CorePin.Performance reads recordings and produces analysis independently of the UI.
- CorePin.Benchmark supplies a standalone, repeatable gaming-style workload.
CorePin.UI is the WPF desktop application. It provides the game library, CPU
profile editor, per-game settings, service controls, performance reports,
system benchmark, updates, and local-data maintenance.
The UI is the only component that authors the main configuration. It discovers installed games through provider-specific integrations and keeps library data and benchmark history in its local database. It can be closed while the service continues managing configured games.
The UI does not monitor process starts, apply affinity or priority, collect performance samples, or diagnose recordings directly.
Game providers are isolated under CorePin.UI/Providers. A provider discovers
installed titles and returns normalized library records; persistence and
per-game settings remain owned by the common library layer. The Amazon Games
provider reads the launcher's installed-game database without modifying it,
resolves the declared runtime from each installation's fuel.json, and
optionally caches portrait artwork referenced by Amazon's local product-details
catalog. The Xbox provider
keeps Windows package discovery, gaming-root discovery, AppX/GDK manifest
parsing, executable classification, evidence merging, and prior-install
reconciliation in separate components. Its machine package-repository reader
is an explicitly isolated fallback because that registry layout is a Windows
implementation detail. A clean scan removes a prior title only when its known
game executables are also gone; inaccessible discovery sources retain the prior
record until a later scan can decide safely.
CorePin.Shared defines the authoritative managed configuration contract and
validation used by the UI. The native service maintains a corresponding parser
and model because it does not depend on the managed runtime.
Changes to this contract must keep managed serialization, native parsing, validation, defaults, and configuration documentation synchronized.
CorePin.Service is a native Windows service responsible for runtime behavior.
It loads the saved configuration, monitors new processes, matches configured
games, resolves scheduling ownership, applies temporary settings, and restores
prior state when managed games exit.
Its responsibilities include affinity and priority, optional enforcement, core isolation, Smart Background Optimization, power-plan coordination, selected UI and launcher lifecycle behavior, and launching the profiler after claiming a matching one-shot request.
The service is designed to remain small and inexpensive while idle. Reporting, database maintenance, benchmark execution, and user-facing policy do not belong in this component.
CorePin.Profiler is an on-demand native recorder, not a persistent service. A
single profiler process follows one game session after the service claims an
armed recording request.
It records available process, frame-delivery, CPU, GPU, memory, storage, and runtime-context measurements. It writes an append-only, recoverable performance session and can continue until the game exits even if the CorePin service or UI stops.
The profiler records facts with minimal impact on the game. It does not assign profiles, draw conclusions, generate reports, or use the UI database.
CorePin.Performance is the managed session-reading and analysis layer. It
validates and decodes performance sessions, aggregates samples for a selected
time range, calculates comparison metrics, and builds the session diagnosis
shown by the UI.
This boundary is independent of WPF so that format reading and analysis can be tested without the desktop application. Optional measurements remain explicitly unavailable when the recorder did not provide dependable data.
CorePin.Benchmark is a standalone native DirectX workload used by the UI's
System Benchmark and Demo Mode. Benchmark suites run controlled workload modes
and return measurements to the UI, which calculates and stores the versioned
scores. Demo Mode runs the visual scene without saving a result.
The benchmark does not depend on game profiles, the CorePin service, or the performance profiler. Its detailed workload, command-line contract, and result format are documented in CorePin Benchmark.
CorePin.ScenarioRunner is a standalone developer tool for exercising multiple
CPU profiles and game-setting combinations against the benchmark workload. It
uses CorePin through its public runtime behavior rather than adding automation
logic to the service, profiler, or UI.
Scenario results and temporary performance recordings are owned and cleaned up by the runner. This component is not part of the normal end-user workflow.
CorePin.Native.Shared contains native constants that must agree across
process boundaries, including the service-to-profiler protocol. It is the
shared source of truth for those native contracts.
CorePin.Notification is a short-lived helper that plays optional recording
start and stop sounds. Keeping sound playback outside the profiler prevents UI
or audio-system work from becoming part of the recording process.
CorePin keeps distinct data stores for distinct responsibilities:
| Data | Primary Owner | Purpose |
|---|---|---|
| Runtime configuration | UI writes; service reads | CPU profiles, app assignments, service options, and runtime behavior. |
| Library database | UI | Discovered games, executable metadata, artwork state, view preferences, and benchmark history. |
| Recording request | UI creates; service claims | Arms exactly one future session for a specific game executable. |
| Performance sessions | Profiler writes; Performance reads | Recorded facts, launch context, and restoration outcome for completed or recoverable sessions. |
Machine-wide runtime data is stored under C:\ProgramData\CorePin. The
configuration file is the service-facing contract; the database is not. The
service does not query the UI database, and the profiler has no database
dependency.
Detailed fields and compatibility rules belong in Configuration and Performance Session Format.
The normal runtime sequence is:
- The user edits CPU profiles, service options, or per-game settings in the UI.
- The UI validates and atomically saves the configuration.
- The service accepts the new configuration as the snapshot for future launches.
- Windows reports a new process, and the service resolves its identity.
- The service matches the process to an enabled app profile and resolves the scheduling owner.
- If CorePin owns scheduling, the service records the original process state before applying the requested runtime settings.
- Optional power, isolation, background optimization, VR, UI, and launcher behavior begins for that managed session.
- Child processes can inherit applicable behavior when configured.
- When the managed process tree exits, CorePin restores temporary state and ends the session-level behavior.
A configuration reload never changes an already running managed game. Each launch retains the immutable settings and original process state needed for consistent enforcement and exact restoration. Newly saved settings apply to the next launch.
Each game selects one scheduling-owner policy:
| Owner | Runtime Behavior |
|---|---|
| CorePin | CorePin applies the selected CPU profile and configured process behavior. |
| AMD/Windows when active | Compatible AMD/Windows scheduling owns placement when detected; CorePin uses the selected profile as a fallback. |
| AMD/Windows only | Placement remains under AMD/Windows control without a CorePin affinity fallback. |
Only one scheduling owner controls a managed session. CorePin-owned paths can apply affinity, priority, child handling, enforcement, isolation, and VR companion placement. Platform-owned paths deliberately avoid competing affinity changes while retaining the surrounding session lifecycle needed for power, profiling, background optimization, and cleanup.
Overlapping managed games must use a coherent ownership state so two scheduling strategies do not fight over shared runtime behavior.
Core isolation and Smart Background Optimization alter processes outside the game for the duration of a managed session.
Core isolation moves eligible background processes away from CPU threads reserved for the game. Its modes expand the set of candidates, while protected Windows, service, game-related, anti-cheat, audio, capture, and VR processes are kept out of unsafe paths.
Smart Background Optimization observes suitable background processes and can apply Windows EcoQoS while gaming. It protects active, visible, latency-sensitive, and game-related software.
Both features record original process state before making a change. Their restoration responsibilities remain separate from the current configuration so that a config reload cannot erase the information required to undo a live change.
Performance recording is independent of CPU-profile assignment:
- The UI creates a one-shot request for the selected game's verified executable.
- The request remains available even when the UI closes.
- When the matching process starts, the service atomically claims the request.
- The service resolves the launch context and starts one profiler process.
- The profiler validates the target process and begins recording.
- The profiler finalizes the session when the game exits or a configured recording limit is reached.
CorePin.Performancereads and analyzes the session for presentation by the UI.
The session stores the settings and effective runtime context used for that specific run. Later profile edits do not rewrite historical recordings. Profiler startup or collection failure must not prevent the game from running.
The System Benchmark is intentionally separate from managed-game operation:
- The UI selects the benchmark suite and graphics adapter.
- The UI launches
CorePin.Benchmarkfor each required component. - The benchmark returns measurements for a completed component.
- The UI validates the result, calculates versioned scores, and saves only a complete suite to benchmark history.
The service and profiler do not participate. This keeps benchmark results from changing CPU profiles or creating performance-report sessions. Demo Mode uses the same executable but does not produce a score or history entry.
Future changes should preserve these rules:
- A configuration replacement becomes active only after successful parsing and validation; otherwise the last valid snapshot remains in use.
- Configuration changes affect future launches, not running managed processes.
- Original process and system state is captured before temporary changes and retained until restoration succeeds or recovery can retry safely.
- Scheduling ownership is explicit and competing affinity owners are avoided.
- The service remains lean while idle and does not absorb UI, reporting, benchmark, or maintenance responsibilities.
- The profiler records facts with bounded overhead; diagnosis belongs in the managed performance layer.
- Missing optional telemetry is represented as unavailable, never as a valid zero.
- Interrupted session files remain recoverable according to the documented format.
- Recording and benchmark failures do not prevent a game from launching or alter unrelated CorePin history.
- UI-only data remains outside the service and profiler contracts.
- Configuration: persisted config fields and validation.
- Performance Session Format: binary records, compatibility, and recovery.
- CorePin Benchmark: workload and result contracts.
- Automated Scenario Runner: profile-matrix automation.
- Developer Troubleshooting: runtime diagnostics, logs, tracing, and test selection.
- Build From Source: toolchain, builds, tests, and packaging.