clean install

web/profiles/farm/docs/model/logic/group.md

@@ -0,0 +1,33 @@
+# Group membership
+
+farmOS includes an optional "Group asset" module, which adds a new Asset type
+called Group, as well as some organizational features that are unique to Group
+Assets.
+
+A Group can have "members", which are other individual Assets. Group membership
+is tracked via "group assignment" Logs. This is very similar to the way that
+[Location](/model/logic/location) works for "movable" Assets. This means that
+an Asset's group membership can change, and the full history of its previous
+memberships is maintained in Logs.
+
+A useful feature of Groups is that any Logs associated with the Group will also
+be associated with its member Assets.
+
+A common use case for this is tracking "herds" of Animal assets. Each herd can
+be represented as a Group Asset, with Animal Assets assigned to it. Logs can be
+used to move the whole group, instead of referencing Animal Assets individually.
+
+Notably, when the Group module is enabled, it overrides the Asset location
+logic to consider group membership. If the Asset is a member of a group, and
+the group has a movement Log that is more recent than any of the Asset's own
+movement Logs, then the Asset's location will be based on the group's Log.
+
+## Group membership logic
+
+The logic for determining an Asset's group membership is as follows:
+
+- *Does the asset have a group assignment Log?*
+    - Yes: *Does the group assignment Log reference groups?*
+        - Yes: **groups referenced by the group assignment Log**
+        - No: **no group**
+    - No: **no group**

web/profiles/farm/docs/model/logic/inventory.md

@@ -0,0 +1,20 @@
+# Inventory
+
+farmOS can track the inventory of Assets over time.
+
+Inventory is tracked via [Logs](/model/type/log) with *inventory adjustment*
+[Quantities](/model/type/quantity). The Inventory module adds two fields to
+Quantity records: "inventory asset" and "inventory adjustment". Each Quantity
+can reference a single Asset, and either "reset", "increment", or "decrement"
+that Asset's inventory. The Quantity's "measure", "value", and "units" fields
+are used in the inventory calculations.
+
+Asset inventory is determined by querying all Quantities that reference the
+Asset and define an adjustment type of "reset", "increment", or "decrement".
+Inventory is calculated by adding all "increment" adjustments and subtracting
+all "decrement" adjustments, starting from the most recent "reset" adjustment
+(or zero if no "reset" adjustment exists).
+
+A separate inventory is tracked for each measure+unit pair, so Assets can have
+a single simple inventory (without a specified measure or unit), or they can
+have multiple inventories of different measures and units.

web/profiles/farm/docs/model/logic/location.md

@@ -0,0 +1,80 @@
+# Location
+
+farmOS can track the physical location of Assets over time. This includes map
+geometry as well as relation to other Assets.
+
+## Fixed Assets
+
+Some Assets are *fixed* in location. The geometry of these Assets is
+*intrinsic* to the Asset itself.
+
+Land is an example of an Asset with a fixed location. Although geography
+changes over time, land assets in farmOS should be considered a snapshot of the
+physical land they represent at the current time. This is useful because it
+provides a simplified model for referring to a logical piece of land and its
+geometry.
+
+Changes to a fixed Asset's intrinsic geometry should be limited to minor
+updates or corrections. If the changes are more substantial, a new Asset should
+be created, and the old Asset archived, to demarcate it as a new phase of the
+place in question.
+
+## Movable Assets
+
+If an Asset is not fixed, then it is considered *movable*, and its location and
+geometry will be determined by *movement* Logs that reference it.
+
+In order to set or change a movable Asset's location, a movement Log must be
+created that defines its new location at that point in time.
+
+Any Log can be a movement. It just needs to reference the Assets that are
+moving, along with their new location. The new location can be in the form of a
+geometry and/or a reference to one or more location Assets.
+
+It is possible to find an Asset's location at any point in time by querying its
+movement Logs.
+
+Generally a movement Log is only included if it is "done", although it is also
+possible to find "pending" movement Logs in the future to find an Asset's
+projected future location.
+
+## Locations
+
+Assets can be designated as *locations*. This allows other Assets to be moved
+to them.
+
+Typically, fixed Assets will also be designated as locations. However, movable
+Assets can also be locations. Consider a tractor (Equipment Asset) with
+multiple attachments (more Equipment Assets). It is possible to record that an
+attachment is connected to the tractor, and therefore its location is derived
+from the tractor's location.
+
+Fixed location Assets can designate *parent* Assets to create a hierarchical
+organization.
+
+## Logic
+
+The logic for determining an Asset's geometry is as follows:
+
+- *Is the Asset fixed?*
+    - Yes: *Does it have an intrinsic geometry?*
+        - Yes: **intrinsic geometry**
+        - No: **no geometry**
+    - No: *Does it have a movement Log?*
+        - Yes: *Does the movement Log have geometry?*
+            - Yes: **movement Log geometry**
+            - No: *Does the movement Log reference a location Asset?*
+                - Yes: **(recurse to determine location Asset's geometry)**
+                - No: **no geometry**
+        - No: **no geometry**
+
+## Geometry
+
+When a Log is saved without a geometry, and it references locations that have
+geometries, the combined geometries of the referenced locations will be copied
+to the Log. Assets referenced in the Location relationship are given first
+priority. If none are found, then Assets referenced in the Log's Asset
+relationship will be used. In the latter case, only Assets that are explicitly
+designated as locations will be included, and geometry will not be copied if
+the Log is a movement (otherwise it would be impossible to clear the geometry
+of a non-fixed location Asset via movement Logs).