[Draft] feat: Server SDK Diagrams + Generator Action (#657)

* Add diagrams * Render PlantUML files * update action * update action * update action * Generate SVG files for PlantUML diagrams * Change action trigger * Add titles and delete old * Use defaulting * Fix ref checkout * Generate SVG files for PlantUML diagrams * Add diagrams into docs under features. * Generate SVG files for PlantUML diagrams * Update to refer to default sse enabled * Generate SVG files for PlantUML diagrams * remove old version statics --------- Co-authored-by: DevCycle Automation <[email protected]>
DevCycleHQ · Jan 23, 2025 · 3460843 · 3460843
1 parent 01c91e3
commit 3460843
Show file tree

Hide file tree

Showing 8 changed files with 204 additions and 0 deletions.
diff --git a/.github/workflows/diagrams.yml b/.github/workflows/diagrams.yml
@@ -0,0 +1,31 @@
+name: Generate PlantUML Diagrams
+on:
+  pull_request:
+    paths:
+      - 'diagrams/**.puml'
+
+permissions:
+  contents: write
+jobs:
+  generate_plantuml:
+    runs-on: ubuntu-latest
+    name: Generate
+    steps:
+      - name: Checkout Source
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ github.head_ref }}
+      - name: Get changed UML files
+        id: getfile
+        run: |
+          echo "::set-output name=files::$(git diff --name-only HEAD^ HEAD | grep .puml | xargs)"
+
+      - name: Generate SVG Diagrams
+        uses: holowinski/plantuml-github-action@main
+        with:
+          args: -v -tsvg "diagrams/**.puml" -o "../static/diagrams"
+
+      - name: Push Local Changes
+        uses: stefanzweifel/[email protected]
+        with:
+          commit_message: "Generate SVG files for PlantUML diagrams"
diff --git a/diagrams/config-manager.puml b/diagrams/config-manager.puml
@@ -0,0 +1,64 @@
+@startuml
+'DevCycle Config Manager
+group Config Manager
+group Constructor/Initialization
+start
+    if (options.DisableRealtimeUpdates) then (no)
+        :Start Config Consolidation Thread;
+    else (yes)
+    endif
+stop
+end group
+
+group Config Polling Thread
+start
+    repeat :Polling Interval;
+        if (Polling Enabled) then (yes)
+            :Fetch Config;
+            if (Success) then (yes)
+                :Update Config;
+                :Send Config Updated Event to EventHandler;
+        else (no)
+            repeat :Retry Fetch;
+            repeat while (Retryable Error) is (yes) not (no)
+            :Return error to EventHandler;
+            kill
+        endif
+        else (no)
+        :Cancel Polling;
+        kill
+        endif
+    repeat while (Polling Enabled) is (yes)
+stop
+end group
+
+
+group Config Consolidation Thread
+
+    while (Event Received)
+    switch (Event Type)
+        case ()
+            :New Config Available;
+            :Fetch Config with minimum Last-Modified timestamp;
+        case ()
+            :Config Updated;
+            if (SSE URL is different than existing?) then (yes)
+                :Disable SSE;
+                :Update SSE URL;
+                :Start SSE Connection;
+            else (no)
+            endif
+        case ()
+            :SSE Connection Error;
+            :Disable SSE;
+            :Start Polling Thread;
+        case ()
+            :SSE Connection Success;
+            :Disable Polling;
+    endswitch
+  endwhile
+  -[hidden]->
+  detach
+end group
+end group
+@enduml
diff --git a/diagrams/event-manager.puml b/diagrams/event-manager.puml
@@ -0,0 +1,28 @@
+@startuml
+'DevCycle Config Manager
+group Event Manager
+group Constructor/Initialization
+start
+    if (options.DisableAutomaticEventLogging and options.DisableCustomEventLogging) then (yes)
+        end
+    else (no)
+        :Start Event Flush Thread;
+    endif
+stop
+end group
+
+group Event Flush Thread
+while (Event Received) is (not Flush Stop)
+    switch (Event Type)
+        case ()
+            :Flush Interval;
+        case ()
+            :Force Flush;
+    endswitch
+    :Flush Events;
+endwhile (Flush Stop)
+end
+end group
+end group
+
+@enduml
diff --git a/diagrams/server-sdk-initialization.puml b/diagrams/server-sdk-initialization.puml
@@ -0,0 +1,66 @@
+@startuml
+'DevCycle Server SDK Initialization Sequence Diagram
+start
+:new DevCycleClient(sdkKey, options);
+group Constructor/Initialization
+    if (Valid Server SDK Key) then (yes)
+        if (options.UseLocalBucketing) then (yes)
+            fork
+            group Initialize Config Manager
+                :Initialize Config Manager;
+            end group
+            fork again
+            group Initialize Event Manager
+                :Initialize Event Manager;
+            end group
+            fork again
+            if (options.ConfigEventHandler exists) then (yes)
+                fork
+                group Initial Fetch Thread
+                    :Fetch Initial Config;
+                    if (Success) then (yes)
+                        :Initialize Config;
+                    else (no)
+                        if (Retryable Error) then (yes)
+                            :Retry Fetch;
+                        else (no)
+                            :return error to EventHandler;
+                        endif
+                    endif
+                    :Send Initialized Event;
+                end group
+                end fork
+            else (no)
+                :Fetch Initial Config;
+                if (Success) then (yes)
+                    :Initialize Config;
+                else (no)
+                    if (Retryable Error) then (yes)
+                        :Retry Fetch;
+                    else (no)
+                        :Throw error;
+                        kill
+                    endif
+                endif
+            endif
+            end fork
+            if (options.DisableRealtimeUpdates) then (yes)
+                :Start Config Polling Thread;
+            else (no)
+            endif
+        else (no)
+            if (options.ConfigEventHandler exists) then (yes)
+                :Send Initialized Event;
+            else (no)
+            endif
+        endif
+    else (no)
+        :SDK Key Validation Failed;
+        :Throw error;
+        kill
+    endif
+end group
+:Return DevCycleClient;
+stop
+
+@enduml
diff --git a/docs/sdk/features.md b/docs/sdk/features.md
@@ -347,3 +347,15 @@ extremely low latency.
 Cloud bucketing is required to use specific features such as [EdgeDB](/platform/feature-flags/targeting/edgedb) and
 [Feature Opt-In](/platform/extras/feature-opt-in). If you aren't using these features, then Local Bucketing
 is the recommended mode.
+
+## Server SDK Diagrams
+
+The following diagrams illustrate the initialization flow, and logical background processes created/managed by the SDKs.
+### Initialization Flow
+![Initialization Flow](/diagrams/server-sdk-initialization.svg)
+
+### Config Manager
+![Config Manager](/diagrams/config-manager.svg)
+
+### Event Manager
+![Event Manager](/diagrams/event-manager.svg)
diff --git a/static/diagrams/config-manager.svg b/static/diagrams/config-manager.svg
diff --git a/static/diagrams/event-manager.svg b/static/diagrams/event-manager.svg
diff --git a/static/diagrams/server-sdk-initialization.svg b/static/diagrams/server-sdk-initialization.svg