Merge pull request #402 from CodeForPhilly/docs-dev-section

restore developer-facing docs files, create folders for user-facing docs and dev-facing docs

Author: earth-walker

docs/README.md

@@ -1,49 +1,19 @@
-# Starlight Starter Kit: Basics
+# BDT Docs
 
-[![Built with Starlight](https://astro.badg.es/v2/built-with-starlight/tiny.svg)](https://starlight.astro.build)
+How to contribute to the docs
 
-```
-npm create astro@latest -- --template starlight
-```
+## Setup
 
-> 🧑‍🚀 **Seasoned astronaut?** Delete this file. Have fun!
+`cd docs/`
 
-## 🚀 Project Structure
+`npm install`
 
-Inside of your Astro + Starlight project, you'll see the following folders and files:
+`npm run dev`
 
-```
-.
-├── public/
-├── src/
-│   ├── assets/
-│   ├── content/
-│   │   └── docs/
-│   └── content.config.ts
-├── astro.config.mjs
-├── package.json
-└── tsconfig.json
-```
+## Docs Pages
 
-Starlight looks for `.md` or `.mdx` files in the `src/content/docs/` directory. Each file is exposed as a route based on its file name.
+Each page in the docs is a markdown file located at content/docs/...
 
-Images can be added to `src/assets/` and embedded in Markdown with a relative link.
+To edit a docs page, simply edit the markdown file.
 
-Static assets, like favicons, can be placed in the `public/` directory.
-
-## 🧞 Commands
-
-All commands are run from the root of the project, from a terminal:
-
-| Command                   | Action                                           |
-| :------------------------ | :----------------------------------------------- |
-| `npm install`             | Installs dependencies                            |
-| `npm run dev`             | Starts local dev server at `localhost:4321`      |
-| `npm run build`           | Build your production site to `./dist/`          |
-| `npm run preview`         | Preview your build locally, before deploying     |
-| `npm run astro ...`       | Run CLI commands like `astro add`, `astro check` |
-| `npm run astro -- --help` | Get help using the Astro CLI                     |
-
-## 👀 Want to learn more?
-
-Check out [Starlight’s docs](https://starlight.astro.build/), read [the Astro documentation](https://docs.astro.build), or jump into the [Astro Discord server](https://astro.build/chat).
+To add a docs page, add a markdown file in the appropriate directory (`user/` for user-facing pages or `dev/` for developer-facing pages). The file must include [frontmatter](https://www.markdownlang.com/advanced/frontmatter.html) with `title` and `description` fields. In `astro.config.mjs`, add an item to the sidebar in the appropriate location to add your page to the sidebar.

docs/astro.config.mjs

@@ -10,9 +10,27 @@ export default defineConfig({
       description:
         "User guide for the Benefit Decision Toolkit screener builder app",
       sidebar: [
-        { label: "Introduction", slug: "intro" },
-        { label: "User Guide", slug: "user-guide" },
-        { label: "Custom Checks", slug: "custom-checks" },
+        {
+          label: "User",
+          items: [
+            { label: "Introduction", slug: "user/intro" },
+            { label: "User Guide", slug: "user/user-guide" },
+            { label: "Custom Checks", slug: "user/custom-checks" },
+          ],
+        },
+        {
+          label: "Developer",
+          items: [
+            {
+              label: "Testing PRs with Codespaces",
+              slug: "dev/testing-prs-with-codespaces",
+            },
+            {
+              label: "Input Definition Transformation",
+              slug: "dev/input-definition-transformation",
+            },
+          ],
+        },
       ],
     }),
   ],

docs/src/content/docs/dev/input-definition-transformation.md

@@ -0,0 +1,87 @@
+---
+title: Input Definition Transformation
+description: Input Definition Transformation
+---
+
+## EligibilityCheck InputDefinitions
+
+Each EligibilityCheck defines a JSON Schema for that data it takes as inputs. This JSON Schema is located at `EligibilityCheck.inputDefinition`, and when a Check is added to a Benefit this JSON Schema is copied to `CheckConfig.inputDefinition`.
+
+Example `EligibilityCheck.inputDefinition` JSON Schema for `Person-min-age` (as of 2026-02-25):
+
+```
+{
+  "type": "object",
+  "properties": {
+    "people": {
+      "type": "array",
+      "items": {
+  		"type": "object",
+        "properties": {
+          "dateOfBirth": {
+            "type": "string",
+            "format": "date"
+          },
+          "id": {
+            "type": "string"
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+Example Data that would be accepted by `EligibilityCheck.inputDefinition` JSON Schema (as of 2026-02-25):
+
+```
+{
+  "people": [
+    {
+      "id": "client",
+      "dateOfBirth": "1960-01-01"
+    },
+    {
+      "id": "spouse",
+      "dateOfBirth": "1984-01-01"
+    }
+  ]
+}
+```
+
+## The reason for a transformation layer
+
+This JSON Schema existing makes it easy to validate the data being sent to an EligibilityCheck (library or custom). However, forcing the Screener Form to produce data that conforms to this Schema leads to a poor user experience.
+
+After some deliberation, the Tech team of BDT decided that the following format would be more suited to the user experience of building a form:
+
+```
+{
+  "people": {
+    "client": {
+      "dateOfBirth": "1960-01-01"
+    },
+    "spouse": {
+      "dateOfBirth": "1984-01-01"
+    }
+  }
+}
+```
+
+If this was the data the Screener Form was expected to produce, then we could have the user choose between the following options when building their form: `["people.client.dateOfBirth", "people.spouse.dateOfBirth"]`
+
+## The transformation Layer
+
+As of 2026-02-25, the Data Transformation Layer has two parts.
+
+- The endpoint `/screener/{screenerId}/form-paths` was made.
+  - This endpoint loops over each Benefit in the selected Screener, then loops over each Check selected in those benefits, and transforms the InputDefinitions of those checks into JSON Schemas that match the desired data (`transformInputDefinitionSchema`).
+  - Then once the JSON Schema has been created for a check, the "FormPaths" are extracted from that new JSON Schema (`extractJsonSchemaPaths`).
+  - These "FormPath" objects are returned to the Frontend.
+- A step was added to Decision Endpoints to transform the Form Data into a state that matched what the EligibilityChecks expect (`FormDataTransformer.transformFormData`).
+
+## Potential weaknesses of this approach
+
+- `InputSchemaService` and `FormDataTransformer` are two different classes in the backend. They are related, but because one of these operates on JSON Schema definitions and the other operates on actual Form Data it is difficult to determine the boundaries of these services.
+- The preferred schema of the Form Data for user experience is known only by the devs and/or by looking at what the transformations do. Some definition of what this "preferred schema" actually is could be added to the codebase.
+- The old method of having the form output match what the EligibilityCheck expected made it simple for devs to know what the output of the form needed to be in order to satisfy the checks. This may also be solved by documenting this preferred form-data schema.