Skip to content

Commit 4259fd1

Browse files
rian-berian-be
committed
Refactor: Rehome examples under Examples
Added - Example specific README files for BillingQuotas, FeatureFlags, IamRoles, and WorkflowApprovals - Top level Examples index README that links into each runnable sample Changed - Moved the runnable example applications out of Polygon/ and into Examples/\n- Updated the example tree so each sample is grouped with its own project, mutations, policies, scenarios, and state files\n- Kept the example namespaces and project structure intact while changing only the repository layout Result The repository now presents examples as dedicated top level area with self contained documentation and direct links to each sample, making the runnable demos easier to discover and navigate.
1 parent 40c3997 commit 4259fd1

47 files changed

Lines changed: 699 additions & 4 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

Polygon/BillingQuotas/BillingQuotas.csproj renamed to Examples/BillingQuotas/BillingQuotas.csproj

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@
88
</PropertyGroup>
99

1010
<ItemGroup>
11-
<ProjectReference Include="..\..\ModularityKit.Mutator\ModularityKit.Mutator.csproj" />
11+
<ProjectReference Include="..\..\src\ModularityKit.Mutator.csproj" />
1212
</ItemGroup>
1313

1414
<ItemGroup>

Polygon/BillingQuotas/Mutations/DecreaseQuotaMutation.cs renamed to Examples/BillingQuotas/Mutations/DecreaseQuotaMutation.cs

File renamed without changes.

Polygon/BillingQuotas/Mutations/IncreaseQuotaMutation.cs renamed to Examples/BillingQuotas/Mutations/IncreaseQuotaMutation.cs

File renamed without changes.

Polygon/BillingQuotas/Mutations/ResetQuotaMutation.cs renamed to Examples/BillingQuotas/Mutations/ResetQuotaMutation.cs

File renamed without changes.

Polygon/BillingQuotas/Policies/MaxQuotaPolicy.cs renamed to Examples/BillingQuotas/Policies/MaxQuotaPolicy.cs

File renamed without changes.

Polygon/BillingQuotas/Policies/PreventNegativeQuotaPolicy.cs renamed to Examples/BillingQuotas/Policies/PreventNegativeQuotaPolicy.cs

File renamed without changes.

Polygon/BillingQuotas/Program.cs renamed to Examples/BillingQuotas/Program.cs

File renamed without changes.

‎Examples/BillingQuotas/README.md‎

Lines changed: 155 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,155 @@
1+
# BillingQuotas
2+
3+
This example shows how to model quota changes as mutations, keep the state immutable, and enforce policy limits before change is applied.
4+
5+
It is the most compact sample in the repository. Use it when you want to see the engine doing one thing well: controlled numeric state changes with validation and policy checks.
6+
7+
## Domain
8+
9+
The domain state is map of user IDs to quota values:
10+
11+
- each user has an integer quota
12+
- quota changes are applied through mutations
13+
- policies prevent quota values from moving outside allowed bounds
14+
15+
The example runs two scenarios:
16+
17+
- an emergency increase for selected users
18+
- a scheduled monthly reset
19+
20+
## What this example demonstrates
21+
22+
- registering the mutation engine with strict options
23+
- executing both single mutations and batch mutations
24+
- validating mutation input before state changes occur
25+
- enforcing maximum and minimum quota limits through policies
26+
- collecting engine statistics after the scenarios finish
27+
28+
## Project structure
29+
30+
- [`Program.cs`](Program.cs) - composition root and scenario runner
31+
- [`BillingQuotas.csproj`](BillingQuotas.csproj) - console project definition
32+
- [`State/QuotaState.cs`](State/QuotaState.cs) - immutable quota state
33+
- [`Mutations/IncreaseQuotaMutation.cs`](Mutations/IncreaseQuotaMutation.cs)
34+
- [`Mutations/DecreaseQuotaMutation.cs`](Mutations/DecreaseQuotaMutation.cs)
35+
- [`Mutations/ResetQuotaMutation.cs`](Mutations/ResetQuotaMutation.cs)
36+
- [`Policies/MaxQuotaPolicy.cs`](Policies/MaxQuotaPolicy.cs)
37+
- [`Policies/PreventNegativeQuotaPolicy.cs`](Policies/PreventNegativeQuotaPolicy.cs)
38+
- [`Scenarios/EmergencyIncreaseScenario.cs`](Scenarios/EmergencyIncreaseScenario.cs)
39+
- [`Scenarios/MonthlyResetScenario.cs`](Scenarios/MonthlyResetScenario.cs)
40+
41+
## How it works
42+
43+
`Program.cs` wires the engine like this:
44+
45+
1. create `ServiceCollection`
46+
2. register `ModularityKit.Mutator` with `MutationEngineOptions.Strict`
47+
3. build the service provider
48+
4. resolve `IMutationEngine`
49+
5. register quota policies
50+
6. run the two scenarios
51+
7. print statistics from `GetStatisticsAsync()`
52+
53+
The scenarios then create their own initial state, build mutations, and call the engine.
54+
55+
## Mutation flow
56+
57+
### Increase quota
58+
59+
[`IncreaseQuotaMutation`](Mutations/IncreaseQuotaMutation.cs) increments a user's quota.
60+
61+
- validates `UserId`
62+
- validates that `Amount` is positive
63+
- applies a new quota value
64+
- emits `ChangeSet` entry for the modified user quota
65+
66+
### Decrease quota
67+
68+
[`DecreaseQuotaMutation`](Mutations/DecreaseQuotaMutation.cs) decrements a user's quota.
69+
70+
- validates `UserId`
71+
- validates that `Amount` is positive
72+
- rejects changes that would drop quota below zero
73+
- emits `ChangeSet` entry for the modified quota
74+
75+
### Reset quota
76+
77+
[`ResetQuotaMutation`](Mutations/ResetQuotaMutation.cs) sets the user's quota back to zero.
78+
79+
- validates `UserId`
80+
- applies zero value
81+
- emits change entry for the affected user
82+
83+
## Policies
84+
85+
### Max quota
86+
87+
[`MaxQuotaPolicy`](Policies/MaxQuotaPolicy.cs) blocks increases that would exceed the configured maximum.
88+
89+
This policy is useful for:
90+
91+
- capping emergency overrides
92+
- constraining tenant limits
93+
- showing how policy evaluation can inspect the concrete mutation type
94+
95+
### Prevent negative quota
96+
97+
[`PreventNegativeQuotaPolicy`](Policies/PreventNegativeQuotaPolicy.cs) blocks quota decreases that would go below zero.
98+
99+
This policy is useful for:
100+
101+
- ensuring accounting integrity
102+
- protecting against accidental underflow
103+
- demonstrating simple deny decisions
104+
105+
## Scenarios
106+
107+
### Emergency increase
108+
109+
[`EmergencyIncreaseScenario`](Scenarios/EmergencyIncreaseScenario.cs) starts from state with multiple users and applies batch of increases.
110+
111+
It shows:
112+
113+
- batch execution
114+
- per mutation policy decisions
115+
- mixed success outcomes inside one batch
116+
117+
### Monthly reset
118+
119+
[`MonthlyResetScenario`](Scenarios/MonthlyResetScenario.cs) resets every user's quota in one batch.
120+
121+
It shows:
122+
123+
- system level mutation context
124+
- batch generation from current state
125+
- folding successful results back into final state
126+
127+
## What to read first
128+
129+
1. [`Program.cs`](Program.cs)
130+
2. [`State/QuotaState.cs`](State/QuotaState.cs)
131+
3. [`Mutations/IncreaseQuotaMutation.cs`](Mutations/IncreaseQuotaMutation.cs)
132+
4. [`Mutations/DecreaseQuotaMutation.cs`](Mutations/DecreaseQuotaMutation.cs)
133+
5. [`Policies/MaxQuotaPolicy.cs`](Policies/MaxQuotaPolicy.cs)
134+
6. [`Policies/PreventNegativeQuotaPolicy.cs`](Policies/PreventNegativeQuotaPolicy.cs)
135+
7. [`Scenarios/EmergencyIncreaseScenario.cs`](Scenarios/EmergencyIncreaseScenario.cs)
136+
8. [`Scenarios/MonthlyResetScenario.cs`](Scenarios/MonthlyResetScenario.cs)
137+
138+
## Run
139+
140+
```bash
141+
dotnet run --project Examples/BillingQuotas/BillingQuotas.csproj
142+
```
143+
144+
## Expected output
145+
146+
The sample prints:
147+
148+
- the emergency increase scenario
149+
- the monthly reset scenario
150+
- success or policy denial messages
151+
- final quota values
152+
- aggregate engine statistics
153+
154+
The exact numbers depend on the runtime and any policy thresholds you change.
155+

Polygon/BillingQuotas/Scenarios/EmergencyIncreaseScenario.cs renamed to Examples/BillingQuotas/Scenarios/EmergencyIncreaseScenario.cs

File renamed without changes.

Polygon/BillingQuotas/Scenarios/MonthlyResetScenario.cs renamed to Examples/BillingQuotas/Scenarios/MonthlyResetScenario.cs

File renamed without changes.

0 commit comments

Comments
 (0)