Add a demo application, and record the domain map

The map is the thing worth showing, and the existing fixture has three entities:
enough to test the layout, nothing to look at. This adds a fourteen-entity
dispensing pharmacy -- a shape XAF developers recognise, with prescriptions,
stock batches, insurance and payments -- so the diagram reads as a real
application rather than as Foo and Bar. It belongs to nobody: publishing a
client's schema to demonstrate a diagram is a poor trade.

Recording it exposed a real weakness in the layout. The walk was depth-first, so
it left a hub after its first spoke and never came back; a sale's lines and
payments ended up halfway around the circle with their edges crossing everything
between. Breadth-first places a node and then all of its neighbours, which keeps
hubs and spokes together -- and hub-and-spoke is the shape most XAF domain models
have. The difference is visible at a glance.

The GIF is assembled from deterministic frames rather than filmed: hover each
entity, screenshot the figure, move on. Even timing, small file, and it can be
re-recorded when the diagram changes. Quantised against one shared palette,
because per-frame palettes make a flat dark background shimmer.

The sample's updater also carries version-gated migration blocks, which is how
XAF teams actually write them and which the extractor does not yet read.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: peopleworks

README.md

@@ -166,10 +166,23 @@ attachment on a machine with no internet, which is how handovers actually happen
 
 It draws **a map of your domain model** from the association attributes scattered across your
 codebase. Most teams have never seen theirs: it exists in one person's head, which is exactly the
-knowledge that leaves when they do. Alongside it: every entity and what each property is, every
-action with the code it runs, validation with the message the user will actually see, the Model
-Editor settings that appear in no C# file, and **an index of every criteria expression in the
-application** — a dialect that is neither SQL nor C# and is otherwise collected nowhere.
+knowledge that leaves when they do.
+
+![The domain model of a sample XAF application. Hovering an entity dims everything it does not touch, leaving only its own relationships lit — purple where deleting the parent deletes the child.](https://raw.githubusercontent.com/peopleworks/XAFLogicExplainer/main/docs/assets/domain-map.gif)
+
+<sub>Real output, from the sample application in this repository. Hover an entity and everything it
+does not touch fades; purple means deleting the parent deletes the child.</sub>
+
+Alongside it: every entity and what each property is, every action with the code it runs,
+validation with the message the user will actually see, the Model Editor settings that appear in no
+C# file, and **an index of every criteria expression in the application** — a dialect that is
+neither SQL nor C# and is otherwise collected nowhere.
+
+Try it on the sample without touching your own code:
+
+```bash
+xaflogic explain --project tests/XafLogicExplainer.Tests/Fixtures/DemoSolution/PharmacyDemo.Module --open
+```
 
 ## Optional: tell your code apart from DevExpress's
 

docs/assets/domain-map.gif

@@ -591,6 +591,7 @@
   <a href="#gap" class="nav__hideable">The gap</a>
   <a href="#output" class="nav__hideable">Output</a>
   <a href="#mcp" class="nav__hideable">MCP</a>
+  <a href="#explainer" class="nav__hideable">Explainer</a>
   <a href="#install" class="is-cta">Install</a>
 </nav>
 
@@ -974,6 +975,40 @@ <h2>Or let the agent<br>ask questions directly.</h2>
     </p>
   </section>
 
+  <!-- ------------------------------------------------------- explainer -->
+  <section id="explainer" class="reveal">
+    <p class="eyebrow">And for the person who inherits it</p>
+    <h2>Most teams have never seen<br>their own domain model.</h2>
+    <p>
+      It exists as association attributes scattered across twenty files, and the map of it lives in
+      one person's head — which is exactly the knowledge that leaves when they do.
+    </p>
+
+    <figure class="figure">
+      <div class="fig-frame">
+        <img src="https://raw.githubusercontent.com/peopleworks/XAFLogicExplainer/main/docs/assets/domain-map.gif"
+             alt="The domain model of a sample XAF application. Hovering an entity dims everything it does not touch, leaving only its own relationships lit."
+             loading="lazy" style="display:block;width:100%;height:auto">
+      </div>
+      <figcaption>
+        Real output. Hover an entity and everything it does not touch fades; purple means deleting
+        the parent deletes the child.
+      </figcaption>
+    </figure>
+
+    <p style="margin-top:2.4rem">
+      <code>xaflogic explain</code> writes one self-contained HTML file — no server, no build step,
+      no request to the network. It opens from an email attachment on a machine with no internet,
+      which is how handovers actually happen.
+    </p>
+    <p>
+      Alongside the map: every entity and what each property is, every action with the code it
+      runs, validation with the message the user will actually see, and <strong>an index of every
+      criteria expression in the application</strong> — a dialect that is neither SQL nor C# and is
+      otherwise collected nowhere.
+    </p>
+  </section>
+
   <!-- --------------------------------------------------------- catalog -->
   <section id="catalog" class="reveal">
     <p class="eyebrow">Optional, for licensees</p>

site/index.html

@@ -135,9 +135,16 @@ public static EntityGraph Build(ExtractedProject project, double? width = null,
     /// <remarks>
     /// Alphabetical order scatters an association's two ends to opposite sides, and every chord
     /// then crosses the middle — the diagram becomes a ball of string at about eight entities.
-    /// Walking the graph greedily from its most connected node keeps most relationships as short
-    /// arcs near the rim. It is a heuristic, not an optimum; the aim is legibility, not a minimal
-    /// crossing count.
+    /// <para>
+    /// The walk is breadth-first on purpose. Following one neighbour at a time leaves a hub after
+    /// its first spoke and never returns, so its remaining children land halfway around the circle
+    /// and their edges cross everything. Placing a node and then <em>all</em> of its neighbours
+    /// keeps a hub and its spokes together, which is the shape most XAF domain models have: an
+    /// order with its lines, a sale with its payments.
+    /// </para>
+    /// <para>
+    /// A heuristic, not an optimum. The aim is legibility, not a minimal crossing count.
+    /// </para>
     /// </remarks>
     private static List<ExtractedEntity> OrderToReduceCrossings(
         List<ExtractedEntity> entities,
@@ -163,21 +170,31 @@ private static List<ExtractedEntity> OrderToReduceCrossings(
         {
             // Start each connected group at its busiest entity, so the hub of a cluster anchors it.
             // Ties break alphabetically to keep the layout stable across runs.
-            var current = remaining
+            var seed = remaining
                 .OrderByDescending(n => degrees.GetValueOrDefault(n))
                 .ThenBy(n => n, StringComparer.Ordinal)
                 .First();
 
-            while (current is not null)
+            var queue = new Queue<string>();
+            queue.Enqueue(seed);
+            remaining.Remove(seed);
+
+            while (queue.Count > 0)
             {
+                var current = queue.Dequeue();
                 order.Add(byName[current]);
-                remaining.Remove(current);
 
-                current = neighbours[current]
+                var children = neighbours[current]
                     .Where(remaining.Contains)
                     .OrderByDescending(n => degrees.GetValueOrDefault(n))
                     .ThenBy(n => n, StringComparer.Ordinal)
-                    .FirstOrDefault();
+                    .ToList();
+
+                foreach (var child in children)
+                {
+                    remaining.Remove(child);
+                    queue.Enqueue(child);
+                }
             }
         }
 

src/XafLogicExplainer.Core/Generators/EntityGraph.cs

@@ -0,0 +1,29 @@
+using System;
+using System.ComponentModel;
+using DevExpress.ExpressApp.ConditionalAppearance;
+using DevExpress.Persistent.Base;
+using DevExpress.Persistent.Validation;
+using DevExpress.Xpo;
+
+namespace PharmacyDemo.Module.BusinessObjects;
+
+/// <summary>Who pays, and how much of it.</summary>
+[DefaultClassOptions]
+[NavigationItem("Care")]
+[XafDefaultProperty(nameof(Name))]
+[Description("Who pays, and how much of it.")]
+public class InsurancePlan : XPCustomObject
+{
+    public InsurancePlan(Session session) : base(session) { }
+
+    [Size(120)]
+    private string _name;
+    public string Name { get => _name; set => SetPropertyValue(nameof(Name), ref _name, value); }
+
+    [Description("Share of the price the insurer pays.")]
+    private decimal _coveragePercent;
+    public decimal CoveragePercent { get => _coveragePercent; set => SetPropertyValue(nameof(CoveragePercent), ref _coveragePercent, value); }
+
+    [Association("Plan-Patients")]
+    public XPCollection<Patient> Patients => GetCollection<Patient>(nameof(Patients));
+}

tests/XafLogicExplainer.Tests/Fixtures/DemoSolution/PharmacyDemo.Module/BusinessObjects/InsurancePlan.cs

@@ -0,0 +1,41 @@
+using System;
+using System.ComponentModel;
+using DevExpress.ExpressApp.ConditionalAppearance;
+using DevExpress.Persistent.Base;
+using DevExpress.Persistent.Validation;
+using DevExpress.Xpo;
+
+namespace PharmacyDemo.Module.BusinessObjects;
+
+/// <summary>A person the pharmacy dispenses to.</summary>
+[DefaultClassOptions]
+[NavigationItem("Care")]
+[XafDefaultProperty(nameof(FullName))]
+[Description("A person the pharmacy dispenses to.")]
+public class Patient : XPCustomObject
+{
+    public Patient(Session session) : base(session) { }
+
+    [Size(140)]
+    [RuleRequiredField("Patient_Name", DefaultContexts.Save, CustomMessageTemplate = "A patient must have a name.")]
+    private string _fullName;
+    public string FullName { get => _fullName; set => SetPropertyValue(nameof(FullName), ref _fullName, value); }
+
+    private DateTime _dateOfBirth;
+    public DateTime DateOfBirth { get => _dateOfBirth; set => SetPropertyValue(nameof(DateOfBirth), ref _dateOfBirth, value); }
+
+    [Size(400)]
+    [Description("Checked before dispensing.")]
+    private string _allergies;
+    public string Allergies { get => _allergies; set => SetPropertyValue(nameof(Allergies), ref _allergies, value); }
+
+    [Association("Plan-Patients")]
+    private InsurancePlan _plan;
+    public InsurancePlan Plan { get => _plan; set => SetPropertyValue(nameof(Plan), ref _plan, value); }
+
+    [Association("Patient-Prescriptions")]
+    public XPCollection<Prescription> Prescriptions => GetCollection<Prescription>(nameof(Prescriptions));
+
+    [Association("Patient-Sales")]
+    public XPCollection<Sale> Sales => GetCollection<Sale>(nameof(Sales));
+}

tests/XafLogicExplainer.Tests/Fixtures/DemoSolution/PharmacyDemo.Module/BusinessObjects/Patient.cs

@@ -0,0 +1,32 @@
+using System;
+using System.ComponentModel;
+using DevExpress.ExpressApp.ConditionalAppearance;
+using DevExpress.Persistent.Base;
+using DevExpress.Persistent.Validation;
+using DevExpress.Xpo;
+
+namespace PharmacyDemo.Module.BusinessObjects;
+
+/// <summary>Money taken against a sale.</summary>
+[DefaultClassOptions]
+[XafDefaultProperty(nameof(Reference))]
+[Description("Money taken against a sale.")]
+public class Payment : XPCustomObject
+{
+    public Payment(Session session) : base(session) { }
+
+    [Size(40)]
+    private string _reference;
+    public string Reference { get => _reference; set => SetPropertyValue(nameof(Reference), ref _reference, value); }
+
+    private decimal _amount;
+    public decimal Amount { get => _amount; set => SetPropertyValue(nameof(Amount), ref _amount, value); }
+
+    [Association("Method-Payments")]
+    private PaymentMethod _method;
+    public PaymentMethod Method { get => _method; set => SetPropertyValue(nameof(Method), ref _method, value); }
+
+    [Association("Sale-Payments")]
+    private Sale _sale;
+    public Sale Sale { get => _sale; set => SetPropertyValue(nameof(Sale), ref _sale, value); }
+}

tests/XafLogicExplainer.Tests/Fixtures/DemoSolution/PharmacyDemo.Module/BusinessObjects/Payment.cs

@@ -0,0 +1,28 @@
+using System;
+using System.ComponentModel;
+using DevExpress.ExpressApp.ConditionalAppearance;
+using DevExpress.Persistent.Base;
+using DevExpress.Persistent.Validation;
+using DevExpress.Xpo;
+
+namespace PharmacyDemo.Module.BusinessObjects;
+
+/// <summary>Cash, card, or an insurer.</summary>
+[DefaultClassOptions]
+[NavigationItem("Sales")]
+[XafDefaultProperty(nameof(Name))]
+[Description("Cash, card, or an insurer.")]
+public class PaymentMethod : XPCustomObject
+{
+    public PaymentMethod(Session session) : base(session) { }
+
+    [Size(60)]
+    private string _name;
+    public string Name { get => _name; set => SetPropertyValue(nameof(Name), ref _name, value); }
+
+    private bool _requiresAuthorization;
+    public bool RequiresAuthorization { get => _requiresAuthorization; set => SetPropertyValue(nameof(RequiresAuthorization), ref _requiresAuthorization, value); }
+
+    [Association("Method-Payments")]
+    public XPCollection<Payment> Payments => GetCollection<Payment>(nameof(Payments));
+}

tests/XafLogicExplainer.Tests/Fixtures/DemoSolution/PharmacyDemo.Module/BusinessObjects/PaymentMethod.cs

@@ -0,0 +1,32 @@
+using System;
+using System.ComponentModel;
+using DevExpress.ExpressApp.ConditionalAppearance;
+using DevExpress.Persistent.Base;
+using DevExpress.Persistent.Validation;
+using DevExpress.Xpo;
+
+namespace PharmacyDemo.Module.BusinessObjects;
+
+/// <summary>Staff licensed to dispense.</summary>
+[DefaultClassOptions]
+[NavigationItem("Staff")]
+[XafDefaultProperty(nameof(FullName))]
+[Description("Staff licensed to dispense.")]
+public class Pharmacist : XPCustomObject
+{
+    public Pharmacist(Session session) : base(session) { }
+
+    [Size(140)]
+    private string _fullName;
+    public string FullName { get => _fullName; set => SetPropertyValue(nameof(FullName), ref _fullName, value); }
+
+    [Size(40)]
+    private string _licenceNumber;
+    public string LicenceNumber { get => _licenceNumber; set => SetPropertyValue(nameof(LicenceNumber), ref _licenceNumber, value); }
+
+    private bool _isOnDuty;
+    public bool IsOnDuty { get => _isOnDuty; set => SetPropertyValue(nameof(IsOnDuty), ref _isOnDuty, value); }
+
+    [Association("Pharmacist-Sales")]
+    public XPCollection<Sale> Sales => GetCollection<Sale>(nameof(Sales));
+}

tests/XafLogicExplainer.Tests/Fixtures/DemoSolution/PharmacyDemo.Module/BusinessObjects/Pharmacist.cs

@@ -0,0 +1,29 @@
+using System;
+using System.ComponentModel;
+using DevExpress.ExpressApp.ConditionalAppearance;
+using DevExpress.Persistent.Base;
+using DevExpress.Persistent.Validation;
+using DevExpress.Xpo;
+
+namespace PharmacyDemo.Module.BusinessObjects;
+
+/// <summary>A doctor who writes prescriptions.</summary>
+[DefaultClassOptions]
+[NavigationItem("Care")]
+[XafDefaultProperty(nameof(FullName))]
+[Description("A doctor who writes prescriptions.")]
+public class Prescriber : XPCustomObject
+{
+    public Prescriber(Session session) : base(session) { }
+
+    [Size(140)]
+    private string _fullName;
+    public string FullName { get => _fullName; set => SetPropertyValue(nameof(FullName), ref _fullName, value); }
+
+    [Size(40)]
+    private string _licenceNumber;
+    public string LicenceNumber { get => _licenceNumber; set => SetPropertyValue(nameof(LicenceNumber), ref _licenceNumber, value); }
+
+    [Association("Prescriber-Prescriptions")]
+    public XPCollection<Prescription> Prescriptions => GetCollection<Prescription>(nameof(Prescriptions));
+}