Unify configuration under AddTrax with step builder pattern

src/Trax.Effect.Data.InMemory/Extensions/ServiceExtensions.cs

@@ -1,7 +1,7 @@
-using Trax.Effect.Configuration.TraxEffectBuilder;
 using Trax.Effect.Data.InMemory.Services.InMemoryContextFactory;
 using Trax.Effect.Data.Services.IDataContextFactory;
 using Trax.Effect.Extensions;
+using TraxEffectBuilder = Trax.Effect.Configuration.TraxEffectBuilder.TraxEffectBuilder;
 
 namespace Trax.Effect.Data.InMemory.Extensions;
 
@@ -43,16 +43,14 @@ public static class ServiceExtensions
     ///
     /// Example usage:
     /// ```csharp
-    /// services.AddTraxEffects(options => options.AddInMemoryEffect());
+    /// services.AddTrax(trax => trax.AddEffects(effects => effects.UseInMemory()));
     /// ```
     ///
     /// Note that data stored in the in-memory database is lost when the application stops,
     /// so this implementation is not suitable for production scenarios where data persistence
     /// is required.
     /// </remarks>
-    public static TraxEffectConfigurationBuilder AddInMemoryEffect(
-        this TraxEffectConfigurationBuilder configurationBuilder
-    ) =>
+    public static TraxEffectBuilder UseInMemory(this TraxEffectBuilder configurationBuilder) =>
         configurationBuilder.AddEffect<IDataContextProviderFactory, InMemoryContextProviderFactory>(
             toggleable: false
         );

src/Trax.Effect.Data.InMemory/Services/InMemoryContext/InMemoryContext.cs

@@ -25,7 +25,7 @@ namespace Trax.Effect.Data.InMemory.Services.InMemoryContext;
 ///
 /// Example usage:
 /// ```csharp
-/// services.AddTraxEffects(options => options.AddInMemoryEffect());
+/// services.AddTrax(trax => trax.AddEffects(effects => effects.UseInMemory()));
 /// ```
 ///
 /// Note that data stored in the in-memory database is lost when the application stops,

src/Trax.Effect.Data.InMemory/Services/InMemoryContextFactory/InMemoryContexFactory.cs

@@ -29,7 +29,7 @@ namespace Trax.Effect.Data.InMemory.Services.InMemoryContextFactory;
 ///
 /// Example usage:
 /// ```csharp
-/// services.AddTraxEffects(options => options.AddInMemoryEffect());
+/// services.AddTrax(trax => trax.AddEffects(effects => effects.UseInMemory()));
 /// ```
 /// </remarks>
 public class InMemoryContextProviderFactory : IDataContextProviderFactory

src/Trax.Effect.Data.Postgres/Extensions/ServiceExtensions.cs

@@ -15,6 +15,7 @@
 using Trax.Effect.Enums;
 using Trax.Effect.Extensions;
 using Trax.Effect.Models;
+using TraxEffectBuilder = Trax.Effect.Configuration.TraxEffectBuilder.TraxEffectBuilder;
 
 namespace Trax.Effect.Data.Postgres.Extensions;
 
@@ -56,13 +57,13 @@ public static class ServiceExtensions
     ///
     /// Example usage:
     /// ```csharp
-    /// services.AddTraxEffects(options =>
-    ///     options.AddPostgresEffect("Host=localhost;Database=trax;Username=postgres;Password=password")
+    /// services.AddTrax(trax => trax
+    ///     .AddEffects(effects => effects.UsePostgres("Host=localhost;Database=trax;Username=postgres;Password=password"))
     /// );
     /// ```
     /// </remarks>
-    public static TraxEffectConfigurationBuilder AddPostgresEffect(
-        this TraxEffectConfigurationBuilder configurationBuilder,
+    public static TraxEffectBuilder UsePostgres(
+        this TraxEffectBuilder configurationBuilder,
         string connectionString
     )
     {

src/Trax.Effect.Data.Postgres/Services/PostgresContext/PostgresContext.cs

@@ -29,8 +29,8 @@ namespace Trax.Effect.Data.Postgres.Services.PostgresContext;
 ///
 /// Example usage:
 /// ```csharp
-/// services.AddTraxEffects(options =>
-///     options.AddPostgresEffect("Host=localhost;Database=trax;Username=postgres;Password=password")
+/// services.AddTrax(trax => trax
+///     .AddEffects(effects => effects.UsePostgres("Host=localhost;Database=trax;Username=postgres;Password=password"))
 /// );
 /// ```
 /// </remarks>

src/Trax.Effect.Data.Postgres/Services/PostgresContextFactory/PostgresContextProviderFactory.cs

@@ -29,8 +29,8 @@ namespace Trax.Effect.Data.Postgres.Services.PostgresContextFactory;
 ///
 /// Example usage:
 /// ```csharp
-/// services.AddTraxEffects(options =>
-///     options.AddPostgresEffect("Host=localhost;Database=trax;Username=postgres;Password=password")
+/// services.AddTrax(trax => trax
+///     .AddEffects(effects => effects.UsePostgres("Host=localhost;Database=trax;Username=postgres;Password=password"))
 /// );
 /// ```
 /// </remarks>

src/Trax.Effect.Data/Extensions/ServiceExtensions.cs

@@ -1,7 +1,7 @@
 using Microsoft.Extensions.DependencyInjection;
 using Microsoft.Extensions.Logging;
-using Trax.Effect.Configuration.TraxEffectBuilder;
 using Trax.Effect.Data.Services.DataContextLoggingProvider;
+using TraxEffectBuilder = Trax.Effect.Configuration.TraxEffectBuilder.TraxEffectBuilder;
 
 namespace Trax.Effect.Data.Extensions;
 
@@ -48,26 +48,27 @@ public static class ServiceExtensions
     ///
     /// Example usage:
     /// ```csharp
-    /// services.AddTraxEffects(options =>
-    ///     options
-    ///         .AddPostgresEffect(connectionString)
-    ///         .AddEffectDataContextLogging(
+    /// services.AddTrax(trax => trax
+    ///     .AddEffects(effects => effects
+    ///         .UsePostgres(connectionString)
+    ///         .AddDataContextLogging(
     ///             minimumLogLevel: LogLevel.Information,
     ///             blacklist: ["Microsoft.EntityFrameworkCore.*"]
     ///         )
+    ///     )
     /// );
     /// ```
     /// </remarks>
-    public static TraxEffectConfigurationBuilder AddEffectDataContextLogging(
-        this TraxEffectConfigurationBuilder configurationBuilder,
+    public static TraxEffectBuilder AddDataContextLogging(
+        this TraxEffectBuilder configurationBuilder,
         LogLevel? minimumLogLevel = null,
         List<string>? blacklist = null
     )
     {
         // Verify that data context logging is enabled
         if (configurationBuilder.DataContextLoggingEffectEnabled == false)
             throw new Exception(
-                "Data Context Logging effect is not enabled in Trax.Core. Ensure a Data Effect has been added to TraxEffects (before calling AddEffectDataContextLogging). e.g. .AddTraxEffects(x => x.AddPostgresEffect(connectionString).AddDataContextEffectLogging())"
+                "Data Context Logging effect is not enabled in Trax.Core. Ensure a Data Effect has been added to TraxEffects (before calling AddDataContextLogging). e.g. .AddTrax(trax => trax.AddEffects(effects => effects.UsePostgres(connectionString).AddDataContextLogging()))"
             );
 
         // Create and register the logging configuration

src/Trax.Effect.Provider.Json/Extensions/ServiceExtensions.cs

@@ -1,9 +1,9 @@
 using Microsoft.Extensions.DependencyInjection;
-using Trax.Effect.Configuration.TraxEffectBuilder;
 using Trax.Effect.Extensions;
 using Trax.Effect.Provider.Json.Services.JsonEffect;
 using Trax.Effect.Provider.Json.Services.JsonEffectFactory;
 using Trax.Effect.Services.EffectProviderFactory;
+using TraxEffectBuilder = Trax.Effect.Configuration.TraxEffectBuilder.TraxEffectBuilder;
 
 namespace Trax.Effect.Provider.Json.Extensions;
 
@@ -41,14 +41,12 @@ public static class ServiceExtensions
     ///
     /// Example usage:
     /// ```csharp
-    /// services.AddTraxEffects(options =>
-    ///     options.AddJsonEffect()
+    /// services.AddTrax(trax => trax
+    ///     .AddEffects(effects => effects.AddJson())
     /// );
     /// ```
     /// </remarks>
-    public static TraxEffectConfigurationBuilder AddJsonEffect(
-        this TraxEffectConfigurationBuilder configurationBuilder
-    )
+    public static TraxEffectBuilder AddJson(this TraxEffectBuilder configurationBuilder)
     {
         configurationBuilder.ServiceCollection.AddTransient<
             IJsonEffectProvider,

src/Trax.Effect.Provider.Parameter/Extensions/ServiceExtensions.cs

@@ -1,11 +1,11 @@
 using System.Text.Json;
 using Microsoft.Extensions.DependencyInjection;
-using Trax.Effect.Configuration.TraxEffectBuilder;
 using Trax.Effect.Extensions;
 using Trax.Effect.Provider.Parameter.Configuration;
 using Trax.Effect.Provider.Parameter.Services.ParameterEffectProviderFactory;
 using Trax.Effect.Services.EffectProviderFactory;
 using Trax.Effect.Utils;
+using TraxEffectBuilder = Trax.Effect.Configuration.TraxEffectBuilder.TraxEffectBuilder;
 
 namespace Trax.Effect.Provider.Parameter.Extensions;
 
@@ -45,8 +45,8 @@ public static class ServiceExtensions
     ///
     /// Example usage:
     /// ```csharp
-    /// services.AddTraxEffects(options =>
-    ///     options.SaveTrainParameters()
+    /// services.AddTrax(trax => trax
+    ///     .AddEffects(effects => effects.SaveTrainParameters())
     /// );
     /// ```
     ///
@@ -58,24 +58,24 @@ public static class ServiceExtensions
     ///     WriteIndented = true
     /// };
     ///
-    /// services.AddTraxEffects(options =>
-    ///     options.SaveTrainParameters(jsonOptions)
+    /// services.AddTrax(trax => trax
+    ///     .AddEffects(effects => effects.SaveTrainParameters(jsonOptions))
     /// );
     /// ```
     ///
     /// Or with parameter configuration to control which parameters are saved:
     /// ```csharp
-    /// services.AddTraxEffects(options =>
-    ///     options.SaveTrainParameters(configure: cfg =>
+    /// services.AddTrax(trax => trax
+    ///     .AddEffects(effects => effects.SaveTrainParameters(configure: cfg =>
     ///     {
     ///         cfg.SaveInputs = true;
     ///         cfg.SaveOutputs = false;
-    ///     })
+    ///     }))
     /// );
     /// ```
     /// </remarks>
-    public static TraxEffectConfigurationBuilder SaveTrainParameters(
-        this TraxEffectConfigurationBuilder builder,
+    public static TraxEffectBuilder SaveTrainParameters(
+        this TraxEffectBuilder builder,
         JsonSerializerOptions? jsonSerializerOptions = null,
         Action<ParameterEffectConfiguration>? configure = null
     )

src/Trax.Effect.StepProvider.Logging/Extensions/ServiceExtensions.cs

@@ -1,15 +1,15 @@
 using Microsoft.Extensions.DependencyInjection;
-using Trax.Effect.Configuration.TraxEffectBuilder;
 using Trax.Effect.Extensions;
 using Trax.Effect.StepProvider.Logging.Services.StepLoggerFactory;
 using Trax.Effect.StepProvider.Logging.Services.StepLoggerProvider;
+using TraxEffectBuilder = Trax.Effect.Configuration.TraxEffectBuilder.TraxEffectBuilder;
 
 namespace Trax.Effect.StepProvider.Logging.Extensions;
 
 public static class ServiceExtensions
 {
-    public static TraxEffectConfigurationBuilder AddStepLogger(
-        this TraxEffectConfigurationBuilder configurationBuilder,
+    public static TraxEffectBuilder AddStepLogger(
+        this TraxEffectBuilder configurationBuilder,
         bool serializeStepData = false
     )
     {

src/Trax.Effect.StepProvider.Progress/Extensions/ServiceExtensions.cs

@@ -1,18 +1,16 @@
 using Microsoft.Extensions.DependencyInjection;
-using Trax.Effect.Configuration.TraxEffectBuilder;
 using Trax.Effect.Extensions;
 using Trax.Effect.StepProvider.Progress.Services.CancellationCheckFactory;
 using Trax.Effect.StepProvider.Progress.Services.CancellationCheckProvider;
 using Trax.Effect.StepProvider.Progress.Services.StepProgressFactory;
 using Trax.Effect.StepProvider.Progress.Services.StepProgressProvider;
+using TraxEffectBuilder = Trax.Effect.Configuration.TraxEffectBuilder.TraxEffectBuilder;
 
 namespace Trax.Effect.StepProvider.Progress.Extensions;
 
 public static class ServiceExtensions
 {
-    public static TraxEffectConfigurationBuilder AddStepProgress(
-        this TraxEffectConfigurationBuilder configurationBuilder
-    )
+    public static TraxEffectBuilder AddStepProgress(this TraxEffectBuilder configurationBuilder)
     {
         configurationBuilder.ServiceCollection.AddTransient<
             ICancellationCheckProvider,

src/Trax.Effect/Configuration/TraxBuilder/TraxBuilder.cs

@@ -0,0 +1,44 @@
+using Microsoft.Extensions.DependencyInjection;
+using Trax.Effect.Configuration.TraxEffectConfiguration;
+using Trax.Effect.Services.EffectRegistry;
+
+namespace Trax.Effect.Configuration.TraxBuilder;
+
+/// <summary>
+/// Root builder for configuring the Trax system.
+/// </summary>
+/// <remarks>
+/// Each subsystem (effects, mediator, scheduler) has its own scoped builder,
+/// accessible via extension methods on this type:
+/// <code>
+/// services.AddTrax(trax => trax
+///     .AddEffects(effects => effects
+///         .UsePostgres(connectionString)
+///         .AddJson()
+///         .SaveTrainParameters()
+///     )
+///     .AddMediator(typeof(Program).Assembly)
+///     .AddScheduler(scheduler => scheduler
+///         .UseLocalWorkers()
+///         .Schedule&lt;IMyTrain&gt;(...)
+///     )
+/// );
+/// </code>
+/// </remarks>
+public class TraxBuilder(IServiceCollection services, IEffectRegistry registry)
+{
+    /// <summary>
+    /// Gets the service collection for registering services.
+    /// </summary>
+    public IServiceCollection ServiceCollection => services;
+
+    /// <summary>
+    /// Gets the effect registry for registering effect providers.
+    /// </summary>
+    internal IEffectRegistry EffectRegistry => registry;
+
+    /// <summary>
+    /// Gets or sets the effect configuration, populated by <c>AddEffects()</c>.
+    /// </summary>
+    internal TraxEffectConfiguration.TraxEffectConfiguration? EffectConfiguration { get; set; }
+}

src/Trax.Effect/Configuration/TraxBuilder/TraxBuilderWithEffects.cs

@@ -0,0 +1,26 @@
+using Microsoft.Extensions.DependencyInjection;
+
+namespace Trax.Effect.Configuration.TraxBuilder;
+
+/// <summary>
+/// Builder state after <c>AddEffects()</c> has been called.
+/// Extension methods for <c>AddMediator()</c> target this type,
+/// enforcing that effects are configured before the mediator.
+/// </summary>
+public class TraxBuilderWithEffects
+{
+    /// <summary>
+    /// The root builder that holds accumulated configuration state.
+    /// </summary>
+    public TraxBuilder Root { get; }
+
+    public TraxBuilderWithEffects(TraxBuilder root)
+    {
+        Root = root;
+    }
+
+    /// <summary>
+    /// Gets the service collection for registering services.
+    /// </summary>
+    public IServiceCollection ServiceCollection => Root.ServiceCollection;
+}

src/Trax.Effect/Configuration/TraxBuilder/TraxMarker.cs

@@ -0,0 +1,7 @@
+namespace Trax.Effect.Configuration.TraxBuilder;
+
+/// <summary>
+/// Marker service registered by <c>AddTrax()</c>. Used by <c>AddTraxDashboard()</c>
+/// and <c>AddTraxGraphQL()</c> to verify that <c>AddTrax()</c> was called first.
+/// </summary>
+public sealed class TraxMarker;

src/Trax.Effect/Configuration/TraxEffectBuilder/TraxEffectConfigurationBuilder.cs → src/Trax.Effect/Configuration/TraxEffectBuilder/TraxEffectBuilder.cs

@@ -2,19 +2,27 @@
 using Microsoft.Extensions.DependencyInjection;
 using Microsoft.Extensions.Logging;
 using Newtonsoft.Json;
+using Trax.Effect.Configuration.TraxBuilder;
 using Trax.Effect.Services.EffectRegistry;
 using Trax.Effect.Utils;
 
 namespace Trax.Effect.Configuration.TraxEffectBuilder;
 
-public class TraxEffectConfigurationBuilder(
-    IServiceCollection serviceCollection,
-    IEffectRegistry? effectRegistry = null
-)
+/// <summary>
+/// Builder for configuring the Trax effect system (data providers, step providers, lifecycle hooks).
+/// </summary>
+public class TraxEffectBuilder
 {
-    public IServiceCollection ServiceCollection => serviceCollection;
+    private readonly TraxBuilder.TraxBuilder _parent;
 
-    public IEffectRegistry? EffectRegistry => effectRegistry;
+    internal TraxEffectBuilder(TraxBuilder.TraxBuilder parent)
+    {
+        _parent = parent;
+    }
+
+    public IServiceCollection ServiceCollection => _parent.ServiceCollection;
+
+    public IEffectRegistry? EffectRegistry => _parent.EffectRegistry;
 
     public bool DataContextLoggingEffectEnabled { get; set; } = false;
 
@@ -28,7 +36,7 @@ public class TraxEffectConfigurationBuilder(
     public JsonSerializerSettings NewtonsoftJsonSerializerSettings { get; set; } =
         TraxJsonSerializationOptions.NewtonsoftDefault;
 
-    protected internal TraxEffectConfiguration.TraxEffectConfiguration Build()
+    internal TraxEffectConfiguration.TraxEffectConfiguration Build()
     {
         var configuration = new TraxEffectConfiguration.TraxEffectConfiguration
         {

src/Trax.Effect/Extensions/FunctionalExtensions.cs

@@ -21,7 +21,7 @@ value is EffectRunner
                 || value is IStepEffectRunner
             )
                 throw new InvalidOperationException(
-                    $"{valueExpr} has not been loaded. Ensure services.AddTraxEffects() is being added to your Dependency Injection Container"
+                    $"{valueExpr} has not been loaded. Ensure services.AddTrax() is being added to your Dependency Injection Container"
                 );
 
             if (value is IServiceProvider)