docs(schema): start documenting graphql schema

api/src/schema/compliance-check.js

@@ -0,0 +1,9 @@
+import gql from 'graphql-tag';
+
+export const typeDef = gql`
+type ComplianceCheck {
+    checkPasses: Boolean
+    metadata: JSON
+}
+`
+

api/src/schema/repo-check.js

@@ -0,0 +1,8 @@
+import gql from 'graphql-tag';
+
+export const typeDef = gql`
+type RepoCheck {
+    vulnerabilityAlertsEnabled: ComplianceCheck
+    hasSecurityMd: ComplianceCheck
+}
+`

api/src/schema/url-check.js

@@ -0,0 +1,14 @@
+import gql from 'graphql-tag';
+
+export const typeDef = gql`
+type URLCheck {
+    accessibility: AccessibilityReport
+}
+
+type AccessibilityReport {
+    minimumColourContrast: ComplianceCheck
+    ariaLabelsIncluded: ComplianceCheck
+
+}
+`
+

docs/checks/url-checks.md

@@ -0,0 +1,9 @@
+# URL (Service) Checks
+
+Some products have one or more services exposed through URLs. URL compliance checks perform a series of automated accessibility and security compliance checks using information that can be retrieved via these public URLs.
+
+## GraphQL Schema
+
+```javascript
+--8<-- "api/src/schema/url-check.js:4:11"
+```

docs/index.md

@@ -0,0 +1,12 @@
+# Observatory (R U OK?)
+
+Observatory is an automated real-time scanning framework for products whose source code is managed on [`PHACDataHub`](https://github.com/PHACDataHub/). The purpose of Observatory is to ensure compliance with requirements around concerns such as security and accessibility.
+
+## Term Glossary
+
+For the purposes of Observatory, we use the glossary below to define several terms used throughout our GraphQL Schema and data models.
+
+| Term        | Meaning                                                                                                                                                                       |
+| ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Product** | Any software product managed under [`PHACDataHub`](https://github.com/PHACDataHub/).                                                                                          |
+| **Service** | Any software product managed under [`PHACDataHub`](https://github.com/PHACDataHub/) that is exposed through one or more service URLs (i.e. not all products deploy services). |