From d79b13d98e85c18c3b756b56513462d74c68d6c9 Mon Sep 17 00:00:00 2001
From: Jon <jonathon.lockwood@networkedweb.com>
Date: Sun, 2 Mar 2025 02:39:37 +0930
Subject: [PATCH] docs(user): initial feature flags

ref: #662 #659 #661 #496
---
 app/devops/models/feature_flag.py             |  2 +
 .../user/devops/feature_flags.md              | 80 +++++++++++++++++++
 .../centurion_erp/user/devops/index.md        |  5 ++
 mkdocs.yml                                    |  3 +
 4 files changed, 90 insertions(+)
 create mode 100644 docs/projects/centurion_erp/user/devops/feature_flags.md

diff --git a/app/devops/models/feature_flag.py b/app/devops/models/feature_flag.py
index feed61b3..9fa76541 100644
--- a/app/devops/models/feature_flag.py
+++ b/app/devops/models/feature_flag.py
@@ -77,6 +77,8 @@ class FeatureFlag(
 
     app_namespace = 'devops'
 
+    documentation = 'devops/feature_flags'
+
     page_layout: dict = [
         {
             "name": "Details",
diff --git a/docs/projects/centurion_erp/user/devops/feature_flags.md b/docs/projects/centurion_erp/user/devops/feature_flags.md
new file mode 100644
index 00000000..37acde98
--- /dev/null
+++ b/docs/projects/centurion_erp/user/devops/feature_flags.md
@@ -0,0 +1,80 @@
+---
+title: Feature Flags
+description: Feature Flag component Documentation for Centurion ERP by No Fuss Computing
+date: 2025-03-02
+template: project.html
+about: https://github.com/nofusscomputing/centurion_erp
+---
+
+Feature flags are a tool that a developer can use so as to conduct progressive releases. That is by hiding a feature behind a flag that is only enabled (available to end users) when it is marked as enabled.
+
+
+## Fields
+
+- **ID** Primary Key / ID of the feature flag. _This field is hidden and automagically generated. ID is viewable from the API endpoint_
+
+- **Name** Arbitrary name for this feature flag
+
+- **Description** Arbitrary description for this feature flag
+
+- **Enabled** Is this feature enabled
+
+- **Software** The software this feature flag belongs
+
+- **created** Date and time the feature flag was created
+
+- **modified** Date and time the feature flag was modified
+
+
+## API Endpoint
+
+!!! danger
+    The Feature Flag Endpoint is publicly accessible. i.e. does not require that a user log in to Centurion. This is by design. You are advised not to enter any sensitive information within the name or description fields of the feature flag.
+
+The API endpoint that is available for feature flagging returns a paginated JSON document containing ALL of the feature flags for the software in question. The format of this document is as follows.
+
+``` jsonc
+{
+    "results": [
+
+        {
+            "2025-0001": {                               // ID of the feature (format: YYYY-<Feature ID>, using year of creation), Dictionary
+                "name": "Feature name 1",                // String
+                "description": "Feature description",    // String
+                "enabled": true,                         // Boolean
+                "created": "Date time created",          // String
+                "modified": "Date time modified"         // String
+            }
+        },
+        {
+            "2025-0002": {
+                "name": "Feature name 2",
+                "description": "Feature description",
+                "enabled": true,
+                "created": "Date time created",
+                "modified": "Date time modified"
+            }
+        }
+    ],
+    "meta": {
+        "pagination": {
+            "page": 1,
+            "pages": 1,
+            "count": 1
+        }
+    },
+    "links": {
+        "first": "https://mydomain.tld/public/flags/1234?page%5Bnumber%5D=1",
+        "last": "https://mydomain.tld/public/flags/1234?page%5Bnumber%5D=1",
+        "next": null,
+        "prev": null
+    }
+}
+```
+
+
+### Using the endpoint in your software
+
+The software you are developing will need to be able to query the flags endpoint, including the ability to obtain paginated results. As JSON is returned from the endpoint there is no restriction upon what programming language you are using. The only requirement is the ability to parse JSON. Most if not all programming languages can do this.
+
+A simple query to the endpoint is all that is required. As only 10 results are returned per page, if `meta.pagination.pages > 1` subsequent requests will be required to obtain all available feature flags. Once you have the complete document, a simple `if` statement is all that is required. i.e. `if flags_json['2025-0001']['enabled']`.
diff --git a/docs/projects/centurion_erp/user/devops/index.md b/docs/projects/centurion_erp/user/devops/index.md
index 3cc09175..26d44a9f 100644
--- a/docs/projects/centurion_erp/user/devops/index.md
+++ b/docs/projects/centurion_erp/user/devops/index.md
@@ -7,3 +7,8 @@ about: https://github.com/nofusscomputing/centurion_erp
 ---
 
 Developer Operations or DevOps for short, is a module that contains items related to a software developers workflow / area of responsibility.
+
+
+## DevOps Components
+
+- [Feature Flags](./feature_flagging.md)
diff --git a/mkdocs.yml b/mkdocs.yml
index 818166cd..f9848fd8 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -190,6 +190,9 @@ nav:
       - DevOps:
 
         - projects/centurion_erp/user/devops/index.md
+
+        - projects/centurion_erp/user/devops/feature_flagging.md
+
       - ITAM:
 
         - projects/centurion_erp/user/itam/index.md