Add documentation - overview of asset fields

docs/asset_fields_overview.md

@@ -0,0 +1,40 @@
+## Asset fields overview
+
+Asset Manager stores a a number of fields whose values work together to enforce how the asset is served.
+These fields are closely related to various document states from the publishing applications.
+Whitehall uses most of the fields, since it implements a full "editioned" flow. The following examples are thus based on Whitehall's behaviour.
+
+1. `draft`
+
+Assets are set to draft (boolean `true`) when they first get created on a draft edition. When the document gets published, the draft state of the `Asset` is also updated to `false`.
+All assets associated with live content must be publicly available. A `draft: true` value can be read as "the asset has never been live". Once it is set to `false`, it should not be set back to `true`. There are other ways to further represent that the asset is no longer live, such as setting a `redirect_url` or a `replacement_id`.
+
+The draft state should always match the state of the `parent_document_url`. Recently, a [validation rule](https://github.com/alphagov/asset-manager/blob/cffce4e0e1323eab138e016de9b33536f62fef60/app/models/asset.rb#L288) has been added to ensure this, though no data patch was run for existing data.
+
+Assets must be in draft for certain authorisation protocols to apply. See [documentation](https://github.com/alphagov/asset-manager/blob/cffce4e0e1323eab138e016de9b33536f62fef60/docs/authorisation.md).
+
+2. `state`
+
+This is a representation of the internal Asset Manager processing of the asset, particularly around uploading and virus scanning status.
+The state machine includes `scanned_clean`, `clean`, `scanned_infected`, `upload_success`, `uploaded`.
+
+NB: There are some invalid remnants of a previous state machine, including state values such as `deleted`, in the database. These should be removed.
+
+3. `deleted_at`
+
+The deletion timestamp gets set when an asset is deleted in the corresponding publishing application, either by deleting an attachment or discarding a document.
+A `nil` value means the asset has not been deleted (default).
+
+4. `replacement_id`
+
+This is a BSON object ID, set when the user uploads a new file in the place of an old one, typically with the intention of preserving some contextual document metadata. 
+Default is `nil`. The replaced asset redirects to its replacement, provided the replacement is not in draft.
+
+Whilst deletion and replacements are mutually exclusive (an asset should not logically have both), they do coexist in the database.
+Deletion, replacement, and draft work together to support previewing of draft content. An asset will not redirect to its replacement if the replacement is in draft.
+This ensures that until the publish event is fired, the users can preview images and documents on the draft stack.
+
+5. `redirect_url`
+
+This is typically set when the parent edition is unpublished. Default is `nil`. It is usually set to the parent document URL. Because of this, most redirected assets will return a `404` status. 
+Upon re-drafting the parent edition, the redirect URL gets set back to `nil`.