Entitlements Overview

Priority (highest → lowest):

┌─────────────────────────────────────────────────────────────────────────┐
│  1. TenantFeatureOverride  →  Custom value set for THIS specific tenant │
│     Example: "MaxAdmins" = 500 (override for Acme Corp)                 │
├─────────────────────────────────────────────────────────────────────────┤
│  2. EditionFeature         →  Value set in the tenant's active edition  │
│     Example: "MaxAdmins" = 50 (Pro plan default)                        │
├─────────────────────────────────────────────────────────────────────────┤
│  3. Feature.DefaultValue   →  Global fallback for the feature           │
│     Example: "MaxAdmins" = 5 (platform default)                         │
└─────────────────────────────────────────────────────────────────────────┘

Resolution Order:
  Check Override → exists? use it : Check Edition → exists? use it : use Default

// Mark a command to require a feature
public class CreateChatRoomCommand : ICommand<Guid>, IRequireFeature
{
    public string RequiredFeatureName => "Chat.Enabled";
    
    // ... command properties
    public string Name { get; set; }
    public string Description { get; set; }
}

// Inside QuotaCounterRepository.cs:
public async Task<bool> TryReserveSlotAsync(Guid tenantId, string resourceType, CancellationToken ct = default)
{
    var counter = await GetAsync(tenantId, resourceType, ct);
    if (counter == null) return true; // No counter = no limit

    // Check 1: Per-tenant limit
    if (counter.Max != -1 && (counter.Used + counter.Reserved) >= counter.Max)
        return false;

    // Check 2: Pooled limit (sibling tenants sharing a PoolRootTenantId)
    if (counter.PoolRootTenantId.HasValue)
    {
        var rootCounter = await GetAsync(counter.PoolRootTenantId.Value, resourceType, ct);
        if (rootCounter != null && rootCounter.PoolMax != -1)
        {
            var poolUsage = await GetPoolUsageAsync(counter.PoolRootTenantId.Value, resourceType, ct);
            if (poolUsage >= rootCounter.PoolMax)
                return false;
        }
    }

    // Atomically reserve the slot
    counter.Reserved++;
    await _db.SaveChangesAsync(ct);
    return true;
}

public static class DependencyInjection
{
    public static IServiceCollection AddEntitlementsModule(
        this IServiceCollection services, IConfiguration config)
    {
        // Domain repositories
        services.AddScoped<IFeatureRepository, FeatureRepository>();
        services.AddScoped<IEditionRepository, EditionRepository>();
        services.AddScoped<ISubscriptionRepository, SubscriptionRepository>();
        services.AddScoped<IFeatureOverrideRepository, FeatureOverrideRepository>();
        
        // Application services
        services.AddScoped<IFeatureCache, FeatureCache>();
        services.AddScoped<IEditionConstraintValidator, EditionConstraintValidator>();
        services.AddScoped<IDowngradeImpactValidator, DowngradeImpactValidator>();
        services.AddScoped<IOverflowPolicyExecutor, OverflowPolicyExecutor>();
        services.AddScoped<IQuotaCounterProvisioner, QuotaCounterProvisioner>();
        
        // AstraFlow mediator pipeline behavior
        services.AddTransient(typeof(IPipelineBehavior<,>), 
            typeof(FeatureCheckBehavior<,>));
        
        // Startup seeder (seeds system features)
        services.AddTransient<IStartupSeeder, EntitlementsStartupSeeder>();
        
        return services;
    }
}

Entitlements/
├── Entitlements.Domain/
│   ├── Entities/
│   │   ├── Feature.cs                  # Controllable capability
│   │   ├── Edition.cs                  # Named plan (Basic, Pro, Enterprise)
│   │   ├── EditionFeature.cs           # Feature value within an edition
│   │   ├── EditionVersion.cs           # Versioned snapshot of edition features
│   │   ├── TenantSubscription.cs       # Tenant ↔ Edition binding
│   │   ├── TenantFeatureOverride.cs    # Per-tenant custom value
│   │   └── QuotaCounter.cs            # Usage tracking for numeric features
│   ├── Interfaces/
│   │   ├── IFeatureRepository.cs
│   │   ├── IEditionRepository.cs
│   │   ├── ISubscriptionRepository.cs
│   │   └── IFeatureOverrideRepository.cs
│   ├── Enums/
│   │   ├── FeatureValueType.cs         # Boolean, Numeric, String
│   │   ├── OverflowPolicy.cs           # Block, Warn, Allow
│   │   ├── SubscriptionType.cs         # Monthly, Annual, Lifetime, Trial
│   │   ├── SubscriptionStatus.cs       # Active, Suspended, Cancelled, Expired
│   │   ├── RolloutStrategy.cs          # Immediate, Gradual, Manual
│   │   └── ExpiryBehavior.cs           # Downgrade, Suspend, Grace
│   └── Specifications/
│       └── FeatureSearchSpec.cs
├── Entitlements.Application/
│   ├── Commands/
│   │   ├── Features/     # CreateFeature, UpdateFeature, DeleteFeature
│   │   ├── Editions/     # CRUD + SetFeatures + DirectApply + Versions
│   │   ├── Subscriptions/ # Assign, Upgrade, Downgrade, Suspend, Resume, Cancel
│   │   └── Overrides/    # SetOverride, RemoveOverride
│   ├── Queries/
│   │   ├── Features/     # GetFeatures, GetFeatureById
│   │   ├── Editions/     # GetEditions, GetById, GetFeatures, GetVersions
│   │   ├── Subscriptions/ # GetSubscriptions, GetById, GetDowngradeImpact
│   │   └── Overrides/    # GetOverrides, GetResolvedFeatures
│   ├── DTOs/             # Request/Response DTOs
│   ├── Mapping/          # explicit DTO mapping rules
│   ├── Services/
│   │   └── EditionConstraintValidator.cs
│   └── Abstractions/
│       ├── IFeatureCache.cs
│       ├── IDowngradeImpactValidator.cs
│       ├── IOverflowPolicyExecutor.cs
│       └── IQuotaCounterProvisioner.cs
└── Entitlements.Infrastructure/
    ├── EntitlementsDbContextFactory.cs
    ├── EntitlementsStartupSeeder.cs
    ├── Persistence/
    │   ├── FeatureRepository.cs
    │   ├── EditionRepository.cs
    │   ├── SubscriptionRepository.cs
    │   └── FeatureOverrideRepository.cs
    ├── Caching/
    │   ├── FeatureCache.cs
    │   └── NoOpFeatureCache.cs
    └── DependencyInjection.cs

src/modules/entitlements/
├── editions/                    # Edition management
│   └── src/
│       ├── domain/
│       │   ├── entities/        # Edition.ts, EditionFeature.ts, EditionVersion.ts
│       │   └── interfaces/      # IEditionRepository.ts
│       ├── data/
│       │   ├── models/          # EditionDto.ts, EditionFeatureDto.ts
│       │   ├── mappers/         # EditionMapper.ts
│       │   └── repositories/    # EditionRepository.ts
│       └── presentation/
│           ├── viewmodels/      # useEditionsViewModel.ts, useEditionDetailViewModel.ts
│           ├── views/           # EditionsView.tsx, EditionDetailView.tsx
│           └── components/      # EditionFeaturesTable.tsx, VersionHistory.tsx
├── features/                    # Feature registry
│   └── src/ { domain, data, presentation }
├── subscriptions/               # Subscription lifecycle
│   └── src/ { domain, data, presentation }
└── overrides/                   # Per-tenant overrides
    └── src/ { domain, data, presentation }

/// <summary>
/// Registered when the Entitlements module is not loaded.
/// All features are treated as enabled with unlimited quotas.
/// </summary>
public class NoOpFeatureCache : IFeatureCache
{
    public Task<ResolvedFeature> GetResolvedValue(
        Guid tenantId, string featureName)
    {
        return Task.FromResult(new ResolvedFeature
        {
            Name = featureName,
            Value = "true",          // Always enabled
            ValueType = FeatureValueType.Boolean,
            Source = ResolutionSource.Default,
        });
    }

    public Task<int> GetCurrentUsage(Guid tenantId, string featureName)
        => Task.FromResult(0); // No usage tracked
}

Step 1: Define Features
  → POST /api/v1/features
  → Create features like "Chat.Enabled" (Boolean), "MaxAdmins" (Numeric)

Step 2: Create Editions
  → POST /api/v1/editions
  → Create plans like "Basic", "Pro", "Enterprise"
  → Set feature values per edition

Step 3: Assign Subscriptions
  → POST /api/v1/subscriptions
  → Link each tenant to an edition

Step 4: Gate Commands (Optional)
  → Implement IRequireFeature on commands
  → FeatureCheckBehavior automatically enforces

Step 5: Apply Overrides (Optional)
  → POST /api/v1/tenants/{id}/features/overrides
  → Give specific tenants custom values