#24: Synergy.Architecture: Added README.md

It contains first version of description how to add sequence diagrams to application.

Architecture/README.md

@@ -1 +1,124 @@
-[//]: # (TODO Introduce docs for generating Sequence Diagrams from code)
+# Synergy.Architecture nuget packages
+
+Here is the documentation of the `Synergy.Architecture.Diagrams` and `Synergy.Architecture.Annotations` nuget packages.
+They were created to help developers to add sequence diagrams from code.
+It is based on the idea of *Diagrams as Code*
+
+Find packages on nuget: 
+- [Synergy.Architecture.Diagrams](https://www.nuget.org/packages/Synergy.Architecture.Diagrams/)
+- [Synergy.Architecture.Annotations](https://www.nuget.org/packages/Synergy.Architecture.Annotations/)
+
+## Enlisting Public API
+
+To enlist public API, we use the following tool:
+
+```csharp
+using Synergy.Architecture.Annotations.Diagrams.Sequence;
+using Synergy.Architecture.Diagrams.Documentation;
+using Synergy.Architecture.Diagrams.Sequence;
+using Synergy.Documentation.Annotations;
+using Synergy.Documentation.Code;
+using static Synergy.Architecture.Annotations.Diagrams.Sequence.SequenceDiagramGroupType;
+
+namespace Synergy.Architecture.Tests.Samples;
+
+[CodeFilePath]
+public class SequenceDiagramSamples
+{
+    public static CodeFile SequenceDiagrams => CodeFolder.Current()
+                                                         .File($"{nameof(SequenceDiagramSamples)}.md");
+
+    [Fact]
+    public async Task Sequence()
+    {
+        var blueprint = TechnicalBlueprint
+                        .Titled("Sequence diagrams samples")
+                        .Add(this.IfElseDiagrams())
+                        .Add(this.LoopAfterLoopDiagram())
+                        .Add(this.DatabaseDiagrams())
+                        .Add(this.OverrideMessageAndResultDiagrams())
+            ;
+
+        await File.WriteAllTextAsync(SequenceDiagrams.FilePath, blueprint.Render());
+    }
+
+    private IEnumerable<SequenceDiagram> IfElseDiagrams()
+    {
+        yield return SequenceDiagram
+                     .From(new SequenceDiagramActor("Some Actor", Note: "very hand some"))
+                     .Calling<SequenceDiagramSamples>(c => c.IfElse())
+                     .Footer("This diagram shows if-else."
+                     );
+    }
+
+    [SequenceDiagramExternalCall("Chrome", "https://www.google.com", Group = SequenceDiagramGroupType.Alt, GroupHeader = "when google is available")]
+    [SequenceDiagramExternalCall("Firefox", "https://www.foogle.com", Group = SequenceDiagramGroupType.Alt, GroupHeader = "when google is available")]
+    [SequenceDiagramExternalCall("Firefox", "https://www.google.com", Group = SequenceDiagramGroupType.Else, GroupHeader = "otherwise")]
+    private void IfElse()
+    {
+    }
+
+    private IEnumerable<SequenceDiagram> LoopAfterLoopDiagram()
+    {
+        yield return SequenceDiagram
+                     .From(new SequenceDiagramActor("Upset Actor", Note: "very upset", Colour: "red"))
+                     .Calling<SequenceDiagramSamples>(c => c.LoopAfterLoop())
+                     .Footer("This diagram shows loop placed after another loop."
+                     );
+    }
+
+    [SequenceDiagramExternalCall("Chrome", "https://www.google.com", Group = Loop, GroupHeader = "Looping until something happens")]
+    [SequenceDiagramExternalCall("Firefox", "https://www.foogle.com", Group = Loop, GroupHeader = "Looping until something happens")]
+    [SequenceDiagramExternalCall("Firefox", "https://www.google.com", Group = Loop, GroupHeader = "This should be different loop")]
+    private void LoopAfterLoop()
+    {
+    }
+
+    private IEnumerable<SequenceDiagram> DatabaseDiagrams()
+    {
+        yield return SequenceDiagram
+                     .From(new SequenceDiagramActor("Some\\nactor", Archetype:SequenceDiagramArchetype.Participant))
+                     .Calling<SequenceDiagramSamples>(c => c.Upsert())
+                     .Footer("This diagram shows standard database operations."
+                     );
+    }
+
+    [SequenceDiagramDatabaseCall($"SELECT * FROM [Item] WHERE [Id] = @itemId")]
+    [SequenceDiagramDatabaseCall($"INSERT INTO [Item] VALUES ...", Group = Alt, GroupHeader = "if item does not exist yet")]
+    [SequenceDiagramDatabaseCall($"UPDATE [Item] SET ... WHERE [Id] = @itemId", Group = Else, GroupHeader = "else")]
+    private void Upsert()
+    {
+    }
+
+    private IEnumerable<SequenceDiagram> OverrideMessageAndResultDiagrams()
+    {
+        yield return SequenceDiagram
+                     .From(new SequenceDiagramActor("Some\\nactor", Archetype:SequenceDiagramArchetype.Control))
+                     .Calling<SequenceDiagramSamples>(c => c.OverrideMessageAndResult())
+                     .Footer("This diagram shows how to override message and result for ordinary [SequenceDiagramCall]."
+                     );
+    }
+
+    [SequenceDiagramCall(typeof(Helper), nameof(Helper.SomeStaticMethod), 
+        Message = "GET https://www.google.com",
+        Result = "200 OK")]
+    private void OverrideMessageAndResult()
+    {
+    }
+}
+
+internal class Helper
+{
+    public static void SomeStaticMethod()
+    {
+    }
+}
+```
+
+For sample code, please check: [SequenceDiagramSamples.cs](Synergy.Architecture.Tests/Samples/SequenceDiagramSamples.cs)
+
+To see the results, please check: [SequenceDiagramSamples.md](Synergy.Architecture.Tests/Samples/SequenceDiagramSamples.md)
+
+**Note:**
+
+

Architecture/Synergy.Architecture.Annotations/Synergy.Architecture.Annotations.csproj

@@ -11,7 +11,7 @@
         <PackageLicenseFile>license.txt</PackageLicenseFile>
         <Description>Architecture testing annotations</Description>
         <Copyright>Copyright © Synergy Marcin Celej 2023</Copyright>
-        <PackageProjectUrl>https://github.com/synergy-software/synergy.framework</PackageProjectUrl>
+        <PackageProjectUrl>https://github.com/synergy-software/synergy.framework/tree/master/Architecture/README.md</PackageProjectUrl>
         <PackageIcon>synergy.png</PackageIcon>
         <PackageTags>Diagrams as Code</PackageTags>
         <AssemblyVersion>$(Version)</AssemblyVersion>

Architecture/Synergy.Architecture.Diagrams/Synergy.Architecture.Diagrams.csproj

@@ -11,7 +11,7 @@
         <PackageLicenseFile>license.txt</PackageLicenseFile>
         <Description>Behaviour Driven Development support</Description>
         <Copyright>Copyright © Synergy Marcin Celej 2023</Copyright>
-        <PackageProjectUrl>https://github.com/synergy-software/synergy.framework</PackageProjectUrl>
+        <PackageProjectUrl>https://github.com/synergy-software/synergy.framework/tree/master/Architecture/README.md</PackageProjectUrl>
         <PackageIcon>synergy.png</PackageIcon>
         <PackageTags>BDD Behaviour Driven Development</PackageTags>
         <AssemblyVersion>$(Version)</AssemblyVersion>

Architecture/Synergy.Architecture.Tests/Architecture/Debt/Todos.Technical.Debt.verified.md

@@ -1,6 +1,6 @@
 # Technical Debt for Synergy.Contracts
 
-Total: 10
+Total: 11
 
 ## [SequenceDiagramDeactivationAttribute.cs](../../../Synergy.Architecture.Annotations/Diagrams/Sequence/SequenceDiagramDeactivationAttribute.cs)
 - TODO: Marcin Celej [from: Marcin Celej on: 21-05-2023]: Use this attribute in some sample
@@ -25,3 +25,6 @@ Total: 10
 - TODO: Marcin Celej [from: Marcin Celej on: 13-07-2023]: add configuration setting to: autoactivate on
 - TODO: Marcin Celej [from: Marcin Celej on: 06-07-2023]: Allow to inline self call
 - TODO: Marcin Celej [from: Marcin Celej on: 06-07-2023]: Add configuration setting to generate only 'new' word here without exact ctor mentioned here - to simplify diagram
+
+## [README.Generate.cs](../../Docs/README.Generate.cs)
+- TODO: Marcin Celej [from: Marcin Celej on: 09-01-2024]: Extract this to a separate project Synergy.Documentation.Docs with all needed samples inside

Architecture/Synergy.Architecture.Tests/Docs/README.Generate.cs

@@ -0,0 +1,25 @@
+using Synergy.Architecture.Tests.Samples;
+using Synergy.Documentation.Code;
+using Synergy.Documentation.Markup;
+
+namespace Synergy.Architecture.Tests.Docs;
+
+// TODO: Marcin Celej [from: Marcin Celej on: 09-01-2024]: Extract this to a separate project Synergy.Documentation.Docs with all needed samples inside
+
+partial class README
+{
+    private static readonly CodeFile readmeFile = CodeFolder.Current().Up(2).File($"{nameof(README)}.md");
+
+    private CodeFile SampleSequenceDiagramsFile => CodeFile.For<SequenceDiagramSamples>();
+    private Markdown.Link SampleSequenceDiagramsLink => Markdown.Link.To(this.SampleSequenceDiagramsFile).RelativeFrom(readmeFile);
+
+    private CodeFile SequenceDiagramsFile => SequenceDiagramSamples.SequenceDiagrams;
+    private Markdown.Link SequenceDiagramsLink => Markdown.Link.To(this.SequenceDiagramsFile).RelativeFrom(readmeFile);
+
+    [Fact]
+    public void Generate()
+    {
+        var content = this.TransformText();
+        File.WriteAllText(readmeFile.FilePath, content);
+    }
+}