PI-1611: Overview documentation for Approved Premises and OASys (#2481)

* PI-1611: Overview documentation for Approved Premises and OASys

Co-authored-by: Marcus Aspin <[email protected]>

projects/approved-premises-and-oasys/README.md

@@ -1,3 +1,39 @@
-# approved-premises-and-oasys
+# Approved Premises and OASys
 
-// TODO Describe the service
+## Business Need
+
+Read-only integration service mediating access to the OASys ORDS endpoints that provide a wide range of OASys data for the Approved Premises (CAS1) service. The integration service is a thin proxy over the OASys endpoints, providing access to the ORDS APIs using the OASys OAuth credentials and enabling per-endpoint access control via HMPPS Auth authorities. Accessing OASys APIs via the integration services also ensures that we include the OASys API calls in the Digital Studio observability tools such as Application Insights and Sentry.
+
+## Context Map
+
+![Context Map](./tech-docs/source/img/approved-premises-and-oasys-context-map.svg)
+
+## Interfaces
+
+### API Access Control
+
+API endpoints are secured by authorities present in the HMPPS Auth client supplied with
+requests
+
+| API Endpoint | Required Role                         |
+|--------------|---------------------------------------|
+| All          | ROLE\_APPROVED\_PREMISES\_ASSESSMENTS |
+
+## Concepts
+
+### OASys ORDS Endpoints
+
+OASys provides access to data via a set of API endpoints built using a technology called Oracle REST Data Services (ORDS). The ORDS APIs may add extra constraints to the set of data returned by OASys depending on how they have been set up.
+
+### Assessment Response Constraints
+
+The Approved Premises ORDS endpoints return assessment matching the following parameters:
+
+|                     |                                      |
+|---------------------|--------------------------------------|
+| **Assessment Type** | OASys Layer 3 Assessments            |
+| **Completed Date**  | Completed within the last six months |
+| **Status**          | COMPLETE or LOCKED_INCOMPLETE        |
+| **Signed Status**   | Signed or Unsigned                   |
+
+Assessments that fall outside of these parameters (e.g. completed on a date older than six months ago) will not be returned by the ORDS endpoints and therefore are not available via the API

projects/approved-premises-and-oasys/tech-docs/diag/approved-premises-and-oasys-context-map.d2

@@ -0,0 +1,38 @@
+
+style {
+  fill: "#ffffff"
+}
+
+context-approved-premises: Approved Premises Context {
+  link: https://github.com/ministryofjustice/hmpps-approved-premises-api
+
+  entities: Entities {
+    grid-columns: 1
+    referral: Approved Premises Referral
+  }
+}
+
+context-oasys: OASys Context {
+  style.stroke-width: 8
+
+  entities: Entities {
+    grid-columns: 3
+    rosh: Risk of Serious Harm
+    rosh_summary: Risk of Serious Harm Summary
+    risk_individual: Risk to the Individual
+    risk_assessment: Risk Assessment
+    offence: Offence Details
+    needs: Needs Details
+    health: Health Details
+    latest_assessment: Latest Assessment
+  }
+  interface: Approved Premises and OASys {
+    type: Anti-Corruption Layer
+  }
+}
+
+context-approved-premises--context-oasys.interface: Upstream\n\n\nDownstream
+
+*.style.border-radius: 10
+*.*.style.border-radius: 10
+*.*.style.stroke-width: 2