Merge pull request #275 from CodeForPhilly/user-guide

Starter Site and Deployment GH Action for BDT User Guide

Author: Michael-Dratch

.firebaserc

@@ -7,6 +7,9 @@
       "hosting": {
         "builder-frontend": [
           "bdt-builder"
+        ],
+        "bdt-docs": [
+          "bdt-docs"
         ]
       }
     }

.github/workflows/deploy-docs.yml

@@ -0,0 +1,73 @@
+name: "Build and Deploy Docs to Firebase Hosting"
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - "docs/user-docs/**"
+
+env:
+  PROJECT_ID: "benefit-decision-toolkit-play"
+  FIREBASE_TARGET: "bdt-docs"
+
+jobs:
+  build-and-deploy-docs:
+    runs-on: ubuntu-latest
+
+    permissions:
+      contents: read
+      id-token: write
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      # -------------------------
+      # Install Python & MKDocs
+      # -------------------------
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: "3.x"
+
+      - name: Cache Python dependencies
+        uses: actions/cache@v4
+        with:
+          path: ~/.cache/pip
+          key: ${{ runner.os }}-pip-${{ hashFiles('docs/user-docs/requirements.txt') }}
+          restore-keys: |
+            ${{ runner.os }}-pip-
+
+      - name: Install Python dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -r docs/user-docs/requirements.txt
+
+      - name: Build MKDocs site
+        working-directory: docs/user-docs
+        run: mkdocs build
+
+      # -------------------------
+      # Install Node & Firebase CLI
+      # -------------------------
+      - name: Set up Node
+        uses: actions/setup-node@v3
+        with:
+          node-version: "18"
+
+      - name: Install Firebase CLI
+        run: npm install -g firebase-tools
+
+      # -------------------------
+      # Authenticate to Firebase
+      # -------------------------
+      - id: auth
+        uses: google-github-actions/auth@v2
+        with:
+          workload_identity_provider: projects/1034049717668/locations/global/workloadIdentityPools/github-actions-google-cloud/providers/github
+          service_account: cicd-build-deploy-api@benefit-decision-toolkit-play.iam.gserviceaccount.com
+          project_id: ${{ env.PROJECT_ID }}
+
+      - name: Deploy Docs to Firebase Hosting
+        run: firebase deploy --only hosting:${{ env.FIREBASE_TARGET }}

.gitignore

@@ -78,7 +78,6 @@ node_modules/
 *.iws
 
 .quarkus/
-
 .devboxrc
-
 .claude/settings.local.json
+docs/user-docs/site/

docs/user-docs/docs/index.md

@@ -0,0 +1,50 @@
+# Introduction
+
+## 1. What Is the Benefit Decision Toolkit?
+
+The **Benefit Decision Toolkit (BDT)** is a low-code platform for building and publishing custom benefit eligibility screeners to the web.
+
+Using BDT, organizations can quickly create screeners that help individuals determine whether they may qualify for specific benefits. The platform is designed to be simple, flexible, and accessible, enabling teams to:
+
+- Build eligibility screeners without extensive engineering support
+- Configure eligibility logic using a guided interface
+- Deploy screeners for public or internal use
+- Provide users with clear, immediate eligibility results
+
+BDT streamlines the process of translating policy rules into an interactive, user-friendly web experience.
+
+---
+
+## 2. What Is an Eligibility Screener?
+
+An **eligibility screener** is a web-based form that:
+
+1. Collects relevant information from a user
+2. Evaluates that information against defined eligibility rules
+3. Displays eligibility results based on the evaluation
+
+Each screener consists of two primary components:
+
+### User Interface (Frontend)
+
+The user interface is the form that end users interact with. It:
+
+- Collects required input data
+- Guides users through the screening questions
+- Displays eligibility results
+
+### Eligibility Logic (Backend)
+
+The eligibility logic defines how user inputs are evaluated. It:
+
+- Applies benefit eligibility rules
+- Processes responses
+- Determines the final eligibility outcome
+
+Together, these components allow organizations to convert benefit requirements into a structured, automated decision experience.
+
+> TODO: Insert example screenshot of a screener
+
+## Next Steps
+
+The [User Guide](user-guide.md) walks through how to create, configure, and publish a screener using BDT. It provides step-by-step instructions and practical guidance to help you begin building and deploying your own eligibility screeners.

docs/user-docs/docs/user-guide.md

@@ -0,0 +1,113 @@
+# Building an Eligibility Screener
+
+This section explains how to create, configure, test, and publish an eligibility screener using the Benefit Decision Toolkit (BDT).
+
+---
+
+## 1. Screener Projects
+
+After signing in, you will land on the **Screeners** view. This page displays all of your existing screener projects and serves as your starting point for creating and managing screeners.
+
+From here, you can:
+
+- View existing screeners
+- Open and edit a screener
+- Create a new screener project
+
+To begin building a new screener, select **Create New Screener** and provide a descriptive name. The name should clearly reflect the benefit or set of benefits being screened.
+
+> TODO: Add image of Screeners view
+
+---
+
+## 2. The Screener Dashboard
+
+When you open a screener project, you are taken to the **Screener Dashboard**.
+
+The Dashboard is the central workspace for your screener. From here, you can:
+
+- Define eligibility logic
+- Build and edit the frontend form
+- Test the screener
+- Publish the screener
+
+At the top of the page, the navigation bar contains four primary workflow tabs:
+
+- **Manage Benefits**
+- **Form Editor**
+- **Preview**
+- **Publish**
+
+These tabs represent the main stages of screener development.
+
+> TODO: Add image of Screener Dashboard
+
+---
+
+## 3. Defining Eligibility Logic (Manage Benefits)
+
+The **Manage Benefits** tab is where you define the eligibility logic used by your screener.
+
+A single screener can evaluate eligibility for one or multiple benefits. The evaluation logic for each benefit is configured separately. This design a single BDT screener to screens users for multiple related programs, while keeping management of each benefit seperate.
+
+> TODO: Add image of Manage Benefits tab
+
+### 3.1 Benefits Overview
+
+When you open the **Manage Benefits** tab, you will see a list of benefits associated with the screener.
+
+From this page, you can:
+
+- Create a new benefit
+- Edit an existing benefit
+- Remove a benefit
+
+Selecting a benefit opens the **Configure Benefit** page.
+
+> TODO: Add image of Configure Benefit page
+
+---
+
+## 4. Configuring a Benefit
+
+The **Configure Benefit** page is where you define the rules that determine eligibility.
+
+Eligibility logic in BDT is built using **Eligibility Checks**.
+
+### What Is an Eligibility Check?
+
+An **Eligibility Check** is a reusable rule component that:
+
+- Accepts one or more user inputs
+- Evaluates a defined condition
+- Returns a boolean result (True or False)
+
+For example, a rule might require applicants to be at least 65 years old. You could add a _Person Minimum Age_ check and configure the minimum age parameter to `65`.
+
+By combining multiple checks, you define the full set of eligibility rules for a benefit.
+
+Currently, a benefit evaluates as **eligible** only if _all_ of its eligibility checks return `True`.
+
+---
+
+## 5. Adding and Managing Eligibility Checks
+
+On the Configure Benefit page, you will see a list of available eligibility checks.
+
+Checks are organized into two categories:
+
+- **Public Checks** – Prebuilt checks available to all BDT users
+- **Your Checks** – Custom checks that you have created
+
+To use a check:
+
+1. Select the check from the list
+2. Click **Add**
+3. Configure its parameters
+
+Once added, the check appears in the benefit’s list of configured checks.
+
+> TODO: Add image of check list  
+> TODO: Add image of check parameter configuration
+
+For information about creating reusable custom checks, see **Creating Custom Checks**.

docs/user-docs/mkdocs.yml

@@ -0,0 +1,4 @@
+site_name: Benefits Decision Toolkit
+
+theme:
+  name: material

docs/user-docs/requirements.txt

@@ -0,0 +1,2 @@
+mkdocs = "1.6.1"
+mkdocs-material = "9.7.1"

firebase.json

@@ -3,17 +3,18 @@
     {
       "target": "builder-frontend",
       "public": "./builder-frontend/dist",
-      "ignore": [
-        "firebase.json",
-        "**/.*",
-        "**/node_modules/**"
-      ],
+      "ignore": ["firebase.json", "**/.*", "**/node_modules/**"],
       "rewrites": [
         {
           "source": "**",
           "destination": "/index.html"
         }
       ]
+    },
+    {
+      "target": "bdt-docs",
+      "public": "./docs/user-docs/site",
+      "ignore": ["firebase.json", "**/.*", "**/node_modules/**"]
     }
   ],
   "emulators": {