using Microsoft.AspNetCore.Builder;

namespace Prefab.Module;

/// <summary>
/// Defines a contract for modular components that can register services and configure the application pipeline within a
/// web application.
/// </summary>
/// <remarks>Implement this interface to encapsulate the registration of services and middleware required by a
/// module. This enables modular composition of application features and promotes separation of concerns.</remarks>
public interface IModule
{
    /// <summary>
    /// Configures and returns the specified web application builder.
    /// </summary>
    /// <param name="builder">The WebApplicationBuilder instance to configure. Cannot be null.</param>
    /// <returns>The configured WebApplicationBuilder instance.</returns>
    WebApplicationBuilder Build(WebApplicationBuilder builder);

    /// <summary>
    /// Configures the specified web application by adding middleware, services, or other components required for
    /// application startup.
    /// </summary>
    /// <remarks>Call this method during application startup to apply custom configuration to the web
    /// application pipeline. This method is commonly used to register middleware, endpoints, or other application
    /// features before the application is run.</remarks>
    /// <param name="app">The <see cref="WebApplication"/> instance to configure. Must not be null.</param>
    /// <returns>The configured <see cref="WebApplication"/> instance. This is typically the same instance as the input
    /// parameter, with additional configuration applied.</returns>
    WebApplication Configure(WebApplication app);
}