[TASK] Add Example Configuration section for Permissions Management docs

Documentation/PermissionsManagement/ExampleConfiguration/Index.rst

@@ -0,0 +1,123 @@
+.. include:: /Includes.rst.txt
+
+.. index:: backend, acl, permissions, user groups, user management
+
+.. _example-configuration:
+
+============================================
+Example configuration of backend user groups
+============================================
+
+Knowing how backend user groups can be :ref:`categorized <_available-acl-options>`,
+and how they can be organized using :ref:`naming conventions <_naming-convention>`
+to distinguish their purpose or context, also following other best practices,
+more advanced examples of group structures for projects with a single or multisite setup
+can be discussed.
+
+.. _single-site-structure:
+
+Backend groups’ structure for a small project
+==============================================
+
+When setting up backend groups and permissions for small, single-site projects,
+consider future complexity. Organizing groups by best practices from the start
+makes future extension and maintenance easier.
+
+Consider a scenario where two role groups are required: one for general content management,
+named :samp:`Content Editor`, and another for survey management, named :samp:`Survey Manager`.
+
+The following conditions should be met:
+
+* Both roles should manage content in all languages
+* Both roles should perform any file operations
+* The Content Editor role has a dedicated file mount for organizing various files
+* The Survey Manager role should have access to a dedicated file mount within the same file storage
+* The Content Editor role should be able to view files uploaded by users with the Survey Manager role, as they might need them for blog posts mentioning the surveys
+* The Content Editor role should manage all types of content, except for surveys
+* The Content Editor should have access to a dedicated branch in system categories
+* The Survey Manager role should only see the storage folder and a selected part of the pages tree where the surveys are listed and rendered
+* The Survey Manager role does not need access to any system categories
+
+With these requirements in mind, the backend groups structure can be planned.
+Following the recommendations of having the :ref:`System Groups <_system-groups>`
+and :ref:`Access Control List Groups <_acl-groups>`, it could look like this:
+
+..  uml:: _backend-groups-simple-project.plantuml
+    :align: center
+    :width: 700
+
+Having defined all the required :samp:`System` and :samp:`Access Control List` groups,
+they can be combined to fulfill the :samp:`Content Editor` and :samp:`Survey Manager`
+roles requirements.
+
+..  uml:: _backend-groups-simple-project-organized.plantuml
+    :align: center
+    :width: 700
+
+Both :samp:`System` and :samp:`Access Control List (ACL)` groups serve as components
+that can be integrated into a larger entity, in this case, the role group.
+These role groups can then be assigned to users. As previously mentioned,
+it's recommended that only the role groups be directly assigned to users.
+
+.. _multisite-structure:
+
+Backend groups’ structure for a multi-site project
+==================================================
+
+When designing backend user groups for a multi-site project, the approach remains
+consistent with that of a smaller, :ref:`single-site project <_single-site-structure>`.
+Adhering to recommended best practices from the start simplifies the expansion
+and preparation of a more advanced setup.
+
+This scenario describes a project with three separate sites (a multi-site setup).
+There will be three distinct :samp:`Content Editors` roles, one for each site,
+along with multiple other roles that will have cross-site access and permissions
+to manage content.
+
+Rhe following condition should be met:
+
+* Project has 3 separate sites defined: Website A, Website B, Website C
+* Project has one default language and one translation to English language
+* For each site there are separate Content Editor roles as they will have different permissions
+* Content Editor roles on Website A and Website C will have access to all languages, while the Content Editor role for Website B will have access only to the English language
+* Each Content Editor role  should have access to dedicated system categories branch
+* Each Content Editor role can manage general content elements
+* Content Editor role on Website A and C can manage news
+* Content Editor role on Website A and C can manage galleries
+* Content Editor role on Website A can manage use custom page types
+* Content Editor role on Website A can manage contact forms (send responses etc.)
+* Content Editor role on Website B can manage surveys
+
+Start by creating the necessary groups to form role groups. This includes system groups
+for each site and shared groups across different roles and sites. Next, define the
+ACL groups, which will be universally reusable for all role groups on any site.
+
+..  uml:: _backend-groups-multisite-project-1.plantuml
+    :align: center
+    :width: 700
+
+..  uml:: _backend-groups-multisite-project-2.plantuml
+    :align: center
+    :width: 700
+
+Groups specific to particular sites (e.g., page group, database mounts) have
+been identified as well as the :samp:`shared groups`, which are universal,
+and should be reused across role groups. These shared groups are applicable
+for roles dedicated to a single site as well as for cross-site groups.
+
+The ACL groups could be further granulated if necessary, by separating permissions
+for different content elements and dividing records’ related groups into multiple
+ones — for editing records, managing lists and details through plugins, etc.
+It wasn't done here to avoid overly complicating the diagram, which is already
+quite comprehensive. However, in your setup, it might be necessary to create
+more ACL groups, each responsible for a smaller set of permissions than those shown here.
+
+The desired backend groups structure and aggregation could look like this:
+
+..  uml:: _backend-groups-multisite-project-organized.plantuml
+    :align: center
+    :width: 700
+
+You should grasp the essence of this concept: numerous smaller backend groups
+can be combined to form a Role group. Role groups are the 'top' tier and are
+the only ones that can be assigned to users later on.

Documentation/PermissionsManagement/ExampleConfiguration/_backend-groups-multisite-project-1.plantuml

@@ -0,0 +1,42 @@
+@startuml
+skinparam nodesep 10
+skinparam ranksep 20
+
+rectangle "Website A" AS Website_A #line.dotted {
+  rectangle "PG_website_a" as PG_website_a #Application
+  rectangle "DBM_website_a" as DBM_website_a #Application
+  rectangle "DBM_website_a_news" as DBM_website_a_news #Application
+  rectangle "FM_website_a" as FM_website_a #Application
+  rectangle "CM_website_a" as CM_website_a #Application
+  PG_website_a -[hidden]-> DBM_website_a
+  DBM_website_a -[hidden]-> DBM_website_a_news
+  DBM_website_a_news -[hidden]-> FM_website_a
+  FM_website_a -[hidden]-> CM_website_a
+}
+
+rectangle "Website B" AS Website_B #line.dotted {
+  rectangle "PG_website_b" as PG_website_b #Application
+  rectangle "DBM_website_b" as DBM_website_b #Application
+  rectangle "DBM_website_b_news" as DBM_website_b_news #Application
+  rectangle "DBM_website_b_survey" as DBM_website_b_survey #Application
+  rectangle "FM_website_b" as FM_website_b #Application
+  rectangle "FM_website_b_survey" as FM_website_b_survey #Application
+  rectangle "CM_website_b" as CM_website_b #Application
+  PG_website_b -[hidden]-> DBM_website_b
+  DBM_website_b -[hidden]-> DBM_website_b_news
+  DBM_website_b_news -[hidden]-> DBM_website_b_survey
+  DBM_website_b_survey -[hidden]-> FM_website_b
+  FM_website_b -[hidden]-> FM_website_b_survey
+  FM_website_b_survey -[hidden]-> CM_website_b
+}
+
+rectangle "Website C" AS Website_C #line.dotted {
+  rectangle "PG_website_c" as PG_website_c #Application
+  rectangle "DBM_website_c" as DBM_website_c #Application
+  rectangle "FM_website_c" as FM_website_c #Application
+  rectangle "CM_website_c" as CM_website_c #Application
+  PG_website_c -[hidden]-> DBM_website_c
+  DBM_website_c -[hidden]-> FM_website_c
+  FM_website_c -[hidden]-> CM_website_c
+}
+@enduml

Documentation/PermissionsManagement/ExampleConfiguration/_backend-groups-multisite-project-2.plantuml

@@ -0,0 +1,26 @@
+@startuml
+skinparam nodesep 10
+skinparam ranksep 20
+
+rectangle "Shared System groups" AS Shared_System_Groups #line.dotted {
+  rectangle "FO_all" AS FO_all #Application
+  rectangle "L_all" AS L_all #Application
+  rectangle "L_english" AS L_english #Application
+  FO_all -[hidden]-> L_all
+  L_all -[hidden]-> L_english
+}
+
+rectangle "Shared ACL groups" AS Shared_ACL_Groups #line.dotted {
+  rectangle "ACL_content_elements" AS ACL_content_elements #Technology
+  rectangle "ACL_news" AS ACL_news #Technology
+  rectangle "ACL_gallery" AS ACL_gallery #Technology
+  rectangle "ACL_survey" AS ACL_survey #Technology
+  rectangle "ACL_contact_forms" AS ACL_contact_forms #Technology
+  rectangle "ACL_pages_custom" AS ACL_pages_custom #Technology
+  ACL_content_elements -[hidden]-> ACL_news
+  ACL_news -[hidden]-> ACL_gallery
+  ACL_gallery -[hidden]-> ACL_survey
+  ACL_survey -[hidden]-> ACL_contact_forms
+  ACL_contact_forms -[hidden]-> ACL_pages_custom
+}
+@enduml

Documentation/PermissionsManagement/ExampleConfiguration/_backend-groups-multisite-project-organized.plantuml

@@ -0,0 +1,70 @@
+@startuml
+skinparam nodesep 10
+skinparam ranksep 20
+
+rectangle "Website A" #line.dotted {
+    rectangle "R_website_a_editor" as R_website_a_editor #Implementation
+    rectangle "PG_website_a" as PG_website_a #Application
+    rectangle "DBM_website_a" as DBM_website_a #Application
+    rectangle "FM_website_a" as FM_website_a #Application
+    rectangle "FO_all" as FO_all #Application
+    rectangle "L_all" as L_all #Application
+    rectangle "CM_website_a" as CM_website_a #Application
+    rectangle "ACL_content_elements" as ACL_content_elements #Technology
+    rectangle "ACL_news" as ACL_news #Technology
+    rectangle "ACL_gallery" as ACL_gallery #Technology
+    rectangle "ACL_pages_custom" as ACL_pages_custom #Technology
+    rectangle "ACL_contact_forms" as ACL_contact_forms #Technology
+    R_website_a_editor <-- PG_website_a
+    PG_website_a -- DBM_website_a
+    DBM_website_a -- FM_website_a
+    FM_website_a -- FO_all
+    FO_all -- L_all
+    L_all -- CM_website_a
+    CM_website_a -- ACL_content_elements
+    ACL_content_elements -- ACL_news
+    ACL_news -- ACL_gallery
+    ACL_gallery -- ACL_pages_custom
+    ACL_pages_custom -- ACL_contact_forms
+}
+
+rectangle "Website B" #line.dotted {
+    rectangle "R_website_b_editor" as R_website_b_editor #Implementation
+    rectangle "PG_website_b" as PG_website_b #Application
+    rectangle "DBM_website_b" as DBM_website_b #Application
+    rectangle "FM_website_b" as FM_website_b #Application
+    rectangle "FO_all" as FO_all1 #Application
+    rectangle "L_english" as L_english #Application
+    rectangle "CM_website_b" as CM_website_b #Application
+    rectangle "ACL_content_elements" as ACL_content_elements1 #Technology
+    rectangle "ACL_survey" as ACL_survey #Technology
+    R_website_b_editor <-- PG_website_b
+    PG_website_b -- DBM_website_b
+    DBM_website_b -- FM_website_b
+    FM_website_b -- FO_all1
+    FO_all1 -- L_english
+    L_english -- CM_website_b
+    CM_website_b -- ACL_content_elements1
+    ACL_content_elements1 -- ACL_survey
+}
+
+rectangle "Website C" #line.dotted {
+    rectangle "R_website_c_editor" as R_website_c_editor #Implementation
+    rectangle "PG_website_c" as PG_website_c #Application
+    rectangle "DBM_website_c" as DBM_website_c #Application
+    rectangle "FM_website_c" as FM_website_c #Application
+    rectangle "FO_all" as FO_all2 #Application
+    rectangle "L_all" as L_all1 #Application
+    rectangle "CM_website_c" as CM_website_c #Application
+    rectangle "ACL_content_elements" as ACL_content_elements2 #Technology
+    rectangle "ACL_news" as ACL_news1 #Technology
+    R_website_c_editor <-- PG_website_c
+    PG_website_c -- DBM_website_c
+    DBM_website_c -- FM_website_c
+    FM_website_c -- FO_all2
+    FO_all2 -- L_all1
+    L_all1 -- CM_website_c
+    CM_website_c -- ACL_content_elements2
+    ACL_content_elements2 -- ACL_news1
+}
+@enduml

Documentation/PermissionsManagement/ExampleConfiguration/_backend-groups-simple-project-organized.plantuml

@@ -0,0 +1,44 @@
+@startuml
+skinparam nodesep 10
+skinparam ranksep 20
+
+rectangle "Content Editor" #line.dotted {
+  rectangle "R_content_editor" as R_content_editor #Implementation
+  rectangle "PG_website_a" as PG_website_a #Application
+  rectangle "DBM_website_a" as DBM_website_a #Application
+  rectangle "FM_website_a" as FM_website_a #Application
+  rectangle "FO_all" as FO_all #Application
+  rectangle "L_all" as L_all #Application
+  rectangle "CM_website_a" as CM_website_a #Application
+  rectangle "ACL_content_elements" as ACL_content_elements #Technology
+  rectangle "ACL_news" as ACL_news #Technology
+  rectangle "ACL_gallery" as ACL_gallery #Technology
+
+  R_content_editor <-- PG_website_a
+  PG_website_a -- DBM_website_a
+  DBM_website_a -- FM_website_a
+  FM_website_a -- FO_all
+  FO_all -- L_all
+  L_all -- CM_website_a
+  CM_website_a -- ACL_content_elements
+  ACL_content_elements -- ACL_news
+  ACL_news -- ACL_gallery
+}
+
+rectangle "Survey Manager" #line.dotted {
+  rectangle "R_survey_manager" as R_survey_manager #Implementation
+  rectangle "PG_website_a" as PG_website_a2 #Application
+  rectangle "DBM_website_a_survey" as DBM_website_a_survey #Application
+  rectangle "FM_website_a_survey" as FM_website_a_survey #Application
+  rectangle "FO_all" as FO_all2 #Application
+  rectangle "L_all" as L_all2 #Application
+  rectangle "ACL_survey" as ACL_survey #Technology
+
+  R_survey_manager <-- PG_website_a2
+  PG_website_a2 -- DBM_website_a_survey
+  DBM_website_a_survey -- FM_website_a_survey
+  FM_website_a_survey -- FO_all2
+  FO_all2 -- L_all2
+  L_all2 -- ACL_survey
+}
+@enduml

Documentation/PermissionsManagement/ExampleConfiguration/_backend-groups-simple-project.plantuml

@@ -0,0 +1,32 @@
+@startuml
+skinparam nodesep 10
+skinparam ranksep 20
+
+rectangle "System Groups" #line.dotted {
+  rectangle "PG_website_a" as PG_website_a #Application
+  rectangle "DBM_website_a" as DBM_website_a #Application
+  rectangle "DBM_website_a_survey" as DBM_website_a_survey #Application
+  rectangle "FM_website_a" as FM_website_a #Application
+  rectangle "FM_website_a_survey" as FM_website_a_survey #Application
+  rectangle "CM_website_a" as CM_website_a #Application
+  rectangle "FO_all" as FO_all #Application
+  rectangle "L_all" as L_all #Application
+  PG_website_a -[hidden]-> DBM_website_a
+  DBM_website_a -[hidden]-> DBM_website_a_survey
+  DBM_website_a_survey -[hidden]-> FM_website_a
+  FM_website_a -[hidden]-> FM_website_a_survey
+  FM_website_a_survey -[hidden]-> CM_website_a
+  CM_website_a -[hidden]-> FO_all
+  FO_all -[hidden]-> L_all
+}
+
+rectangle "Access Control List Groups" #line.dotted {
+  rectangle "ACL_content_elements" as ACL_content_elements #Technology
+  rectangle "ACL_news" as ACL_news #Technology
+  rectangle "ACL_gallery" as ACL_gallery #Technology
+  rectangle "ACL_survey" as ACL_survey #Technology
+  ACL_content_elements -[hidden]-> ACL_news
+  ACL_news -[hidden]-> ACL_gallery
+  ACL_gallery -[hidden]-> ACL_survey
+}
+@enduml

Documentation/PermissionsManagement/Index.rst

@@ -107,3 +107,4 @@ the naming convention for backend groups later on.
 
    GeneralRecommendations/Index
    SettingUpBackendGroups/Index
+   ExampleConfiguration/Index

Documentation/PermissionsManagement/SettingUpBackendGroups/Index.rst

@@ -120,7 +120,7 @@ Page Group
     Examples: *PG_website_a*, *PG_website_a_blog*, *PG_website_b*, *PG_website_b_gallery*
 
     Grants permissions to all pages in the pages tree for a given site or only
-selected branches of pages in the tree.
+    selected branches of pages in the tree.
 
     Those groups will be assigned directly to the pages (see Page Permissions
     for more details) following the TSConfig or the Access Module configuration.