Add docs and tests

docs/source/simulation_structure.rst

@@ -11,3 +11,55 @@ top level, there is an object called the ``SimulationController`` _(doesn't exis
 and a software controller for managing software and users.
 
 Each node of the simulation 'tree' has responsibility for creating, deleting, and updating its direct descendants.
+
+
+
+Actions
+=======
+Agents can interact with the simulation by using actions. Actions are standardised with the
+:py:class:`primaite.simulation.core.Action` class, which just holds a reference to two special functions.
+
+1. The action function itself, it must accept a `request` parameters which is a list of strings that describe what the
+   action should do. It must also accept a `context` dict which can house additional information surrounding the action.
+   For example, the context will typically include information about which entity intiated the action.
+2. A validator function. This function should return a boolean value that decides if the request is permitted or not.
+   It uses the same paramters as the action function.
+
+Action Permissions
+------------------
+When an agent tries to perform an action on a simulation component, that action will only be executed if the request is
+validated. For example, some actions can require that an agent is logged into an admin account. Each action defines its
+own permissions using an instance of :py:class:`primaite.simulation.core.ActionPermissionValidator`. The below code
+snippet demonstrates usage of the ``ActionPermissionValidator``.
+
+.. code:: python
+
+    from primaite.simulator.core import Action, ActionManager, SimComponent
+    from primaite.simulator.domain.controller import AccountGroup, GroupMembershipValidator
+
+    class Smartphone(SimComponent):
+        name: str
+        apps = []
+
+        def __init__(self, **kwargs):
+            super().__init__(**kwargs)
+            self.action_manager = ActionManager()
+
+            self.action_manager.add_action(
+                "reset_factory_settings",
+                Action(
+                    func = lambda request, context: self.reset_factory_settings(),
+                    validator = GroupMembershipValidator([AccountGroup.domain_admin]),
+                ),
+            )
+
+        def reset_factory_settings(self):
+            self.apps = []
+
+    phone = Smartphone(name="phone1")
+
+    # try to wipe the phone as a domain user, this will have no effect
+    phone.apply_action(["reset_factory_settings"], context={"request_source":{"groups":["domain_user"]})
+
+    # try to wipe the phone as an admin user, this will wipe the phone
+    phone.apply_action(["reset_factory_settings"], context={"request_source":{"groups":["domain_admin"]})