Domain docs

README.md

@@ -5,6 +5,12 @@
 
 Ruby on Rails app that handles the submission of lettings and sales of social housing data in England. Currently in private beta.
 
+## Domain documentation
+
+- [Service overview](docs/service_overview.md)
+- [User roles](docs/user_roles.md)
+- [Schemes](docs/schemes.md)
+- [Organisation relationships (Parent/Child)](docs/organisation_relationships.md)
 
 ## Technical Documentation
 
@@ -22,12 +28,6 @@ Ruby on Rails app that handles the submission of lettings and sales of social ho
 API documentation can be found here: <https://communitiesuk.github.io/mhclg-data-collection-beta>. This is driven by [OpenAPI docs](docs/api/DLUHC-CORE-Data.v1.json)
  
 
-## Service
-
-All lettings and and sales of social housing in England need to be logged with the Department for levelling up, housing and communities (DLUHC). This is done by Local Authorities and Housing Associations, who are the primary users of this service. Data is collected via a form that runs on an annual data collection window basis. Form changes are made annually to add new questions, remove any that are no longer needed, or adjust wording or answer options etc. Each data collection window runs from 1st April to 1st April + an extra 3 months to allow for any late submissions, meaning that between April and July, two collection windows are open simultaneously and logs can be submitted for either.
-
-ADD (Analytics & Data Directorate) statisticians are the other primary users of the service. The data collected is transferred to DLUHCs data warehouse (CDS - consolidated data store), via nightly exports to XML which are transferred to S3 and ingested from there. CDS ingests and transforms the data, ultimately storing it in a MS SQL database and exposing it to analysts and statisticians via Amazon Workspaces.  
-
 System architecture:
 ![View of system architecture](docs/images/architecture.png)
 

docs/organisation_relationships.md

@@ -0,0 +1,23 @@
+# Definitions
+
+- **Stock owning organisation** (parent): an organisation that owns housing stock (parent). It may manage the allocation of people in and out of their accommodation, or it may contract this out to a managing agent (child).
+
+- **Managing agent (child)**: These are about orgs. In scenarios where one organisation owns stock and another organisation is contracted to manage the stock and tenants, the latter organisation is often called a ‘managing agent’. A managing agent is the same as a child and is the term more commonly used by data providing organisations. Parent/child is what we call them internally but is not a term that should be used for external customers. Managing agents are responsible for the allocation of people in and out of the accommodation, and/or responsible for the services provided to support those people in the accommodation (in the case of Supported Housing).
+
+# Permissions
+
+## Organisational relationships:
+
+Organisations that own stock can contract out the management of that stock to another organisation. This relationship is often referred to as a parent/child relationship. This is a useful analogy as a parent can have multiple children, and a child can have many parents. A child organisation can also be a parent, and a parent organisation can also be a child organisation:
+
+![Organisational relationships](docs/images/organisational_relationships.png)
+
+The case logs that a user can see depends on their role:
+
+    - Customer Support users can access any case log
+    - Data coordinators can access any case log for which the organisation they work for is ultimately responsible for, meaning they can see logs managed by a child organisation
+    - Data providers can only access case logs for which their organisation manages (or directly owns)
+
+Taking the relationships from the above diagram, and looking at which logs each user can access:
+
+![User log access permissions](docs/images/user_log_permissions.png)

docs/schemes.md

@@ -0,0 +1,5 @@
+# Supported housing schemes
+
+- **Schemes**: Groups of similar properties in the same location, intended for similar tenants with the same type of support needs, managed in the same way. As some of the information we need about a new tenancy is the same for all new tenancies in the ‘scheme’, users can set up a ‘scheme’ in the CORE system by completing the information once. In Supported Housing forms, the user just supplies the appropriate scheme. This means providers do not have to complete identical information multiple times in each CORE form. Effectively we model these as "templates" or "predefined answer sets"
+
+- **Management groups**: Schemes are often managed together as part of a ‘management group’. An organisation may have multiple management groups, and each management group may have multiple schemes. For Supported Housing logs, users must select the management group first, then select scheme. 

docs/service_overview.md

@@ -0,0 +1,5 @@
+## Service
+
+All lettings and and sales of social housing in England need to be logged with the Department for levelling up, housing and communities (DLUHC). This is done by Local Authorities and Housing Associations, who are the primary users of this service. Data is collected via a form that runs on an annual data collection window basis. Form changes are made annually to add new questions, remove any that are no longer needed, or adjust wording or answer options etc. Each data collection window runs from 1st April to 1st April + an extra 3 months to allow for any late submissions, meaning that between April and July, two collection windows are open simultaneously and logs can be submitted for either.
+
+ADD (Analytics & Data Directorate) statisticians are the other primary users of the service. The data collected is transferred to DLUHCs data warehouse (CDS - consolidated data store), via nightly exports to XML which are transferred to S3 and ingested from there. CDS ingests and transforms the data, ultimately storing it in a MS SQL database and exposing it to analysts and statisticians via Amazon Workspaces. 

docs/user_roles.md

@@ -0,0 +1,13 @@
+# External Users
+
+The primary users of the system are external data providing organisations: Local Authorities and Private Registered Providers (Housing Associations). These have 2 main user type:
+
+- Data Coordinators - administrators for their own organisation, can also complete logs
+- Data Providers - complete the logs
+
+Additionally there are Data Protection Officers (DPO) which at some organisations is a separate role, but in our codebase is modelled as an attribute of the user (i.e. a data coordinator or provider can additionally be a DPO). They are responsible for ensuring the organisation has signed the data sharing agreement.
+
+# Internal users
+
+- Customer support (helpdesk) - can administrate all organisations
+- ADD statisticians - primary consumers of the data collected via CDS/DAP