diff --git a/.github/ISSUE_TEMPLATE/add-resource.md b/.github/ISSUE_TEMPLATE/add-resource.md new file mode 100644 index 0000000..265ff64 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/add-resource.md @@ -0,0 +1,45 @@ +--- +name: Add a Resource +about: Submit a new social service organization for the resource directory +title: "Add resource: [Organization Name]" +labels: ["data"] +--- + +## Organization Details + +**Name:** +**Phone:** +**Website:** +**Address:** +**Hours:** + +## Classification + +**Service domains** (from [standard vocabulary](../CONTRIBUTING.md#domain-vocabulary)): + + +**Coverage area** (e.g., statewide, stl_metro, kc_metro, specific counties): + + +**Target population** (from [standard vocabulary](../CONTRIBUTING.md#population-vocabulary)): + + +**Cost model** (free, sliding_scale, income_based, suggested_donation): + + +## Description + +Brief description of services provided (1-2 sentences): + + +## Verification + +- [ ] I have verified this organization is currently operating +- [ ] I have confirmed the phone number connects to the organization +- [ ] I have checked that this organization is not already in the directory + +**How did you verify this information?** + + +**Your relationship to this organization (if any):** + diff --git a/.github/ISSUE_TEMPLATE/data-issue.md b/.github/ISSUE_TEMPLATE/data-issue.md new file mode 100644 index 0000000..1a3cfa4 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/data-issue.md @@ -0,0 +1,31 @@ +--- +name: Report Incorrect Data +about: Report outdated or incorrect resource information +title: "Data issue: [Organization Name]" +labels: ["data-quality"] +--- + +## Which resource? + +**Organization name or ID:** + + +## What is wrong? + +- [ ] Phone number changed +- [ ] Organization closed +- [ ] Address changed +- [ ] Hours changed +- [ ] Website changed +- [ ] Incorrect eligibility/coverage information +- [ ] Other + +## Correct information + +What should it say instead? + + +## How do you know? + +How did you discover this information is incorrect? (e.g., called the number, visited the website, work there) + diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 0000000..c5e23e6 --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,19 @@ +## Summary + + + +## Type of Change + +- [ ] New resource(s) added to `mo-resources.json` +- [ ] Resource data correction +- [ ] Bug fix +- [ ] New feature +- [ ] Accessibility improvement +- [ ] Documentation update + +## Checklist + +- [ ] `node scripts/validate.js` passes +- [ ] `node tests/eligibility.test.js` passes +- [ ] New resources have been verified (phone/website confirmed) +- [ ] No PII included in any files diff --git a/.github/workflows/validate.yml b/.github/workflows/validate.yml new file mode 100644 index 0000000..4cba040 --- /dev/null +++ b/.github/workflows/validate.yml @@ -0,0 +1,24 @@ +name: Validate + +on: + push: + branches: [main] + pull_request: + branches: [main] + +jobs: + validate: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - name: Use Node.js 20 + uses: actions/setup-node@v4 + with: + node-version: 20 + + - name: Validate resource directory + run: node scripts/validate.js + + - name: Run tests + run: node tests/eligibility.test.js diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..5bb239c --- /dev/null +++ b/.gitignore @@ -0,0 +1,13 @@ +node_modules/ +.env +.env.* +.DS_Store +*.log +dist/ +build/ +coverage/ +.idea/ +.vscode/ +*.swp +*.swo +*~ diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..13dc01a --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,96 @@ +# Contributing to Access to Services + +Thank you for helping improve access to social services in Missouri. This guide covers how to contribute resources, report data issues, and submit code changes. + +## Adding a Resource + +Resource entries live in `mo-resources.json`. To add a new organization: + +### Required Fields + +| Field | Example | Notes | +|-------|---------|-------| +| `id` | `stl-food-outreach` | Unique. Use pattern: `region-shortname` | +| `name` | `Food Outreach` | Official organization name | +| `domain` | `["food"]` | From [standard vocabulary](#domain-vocabulary) | +| `type` | `food_bank` | Organization type | +| `coverage` | `stl_metro` | Geographic coverage area | +| `population` | `["all"]` | From [standard vocabulary](#population-vocabulary) | +| `description` | `"Provides nutritious food..."` | Brief, accurate description | +| `verified` | `2026-03-28` | Date you verified the information (YYYY-MM-DD) | + +### Optional Fields + +`phone`, `phone_alt`, `address`, `website`, `hours`, `counties`, `cost`, `insurance`, `note` + +### Submission Checklist + +Before submitting a new resource: + +- [ ] Verified the organization is currently operating (called or checked website) +- [ ] Confirmed the phone number connects to the organization +- [ ] Checked for duplicate entries in `mo-resources.json` +- [ ] Used standard domain and population vocabulary +- [ ] Set `verified` to today's date +- [ ] Ran `node scripts/validate.js` and it passes + +### How to Submit + +1. Fork the repository +2. Add your entry to the `resources` array in `mo-resources.json` +3. Run `node scripts/validate.js` to validate +4. Open a pull request with the title: `Add resource: [Organization Name]` +5. Include in the PR description: how you verified the information and your relationship to the organization (if any) + +## Reporting Incorrect Information + +If you find outdated or incorrect resource data: + +1. Open an issue with the title: `Data issue: [Organization Name]` +2. Include: what is wrong, what the correct information is, and how you know + +Common issues: phone number changed, organization closed, hours changed, address moved. + +## Code Changes + +### Setup + +```bash +git clone https://github.com/dougdevitre/access-to-services.git +cd access-to-services +``` + +### Before Submitting + +1. Run validation: `node scripts/validate.js` +2. Run tests: `node tests/eligibility.test.js` +3. Test any JSX changes in a React environment + +### Code Style + +- Use descriptive variable names (not abbreviated) +- Include ARIA attributes for interactive elements +- Keep screening questions at a 5th-8th grade reading level +- Do not commit PII or real client data + +## Domain Vocabulary + +``` +food, housing, mental_health, substance_use, healthcare, education, +employment, legal, children, family, public_safety, disability, +aging, transportation, crisis, financial, immigration, reentry +``` + +## Population Vocabulary + +``` +all, low_income, seniors, disabled, children, children_0_3, +children_under5, school_age, families_with_children, veterans, +pregnant, lgbtq_youth, justice_involved, homeless, immigrants, +caregivers, medicare, families_prenatal_5, families_children_disabilities, +all_rural +``` + +## Questions? + +Open an issue or reach out to the maintainers. diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..be3ce53 --- /dev/null +++ b/LICENSE @@ -0,0 +1,190 @@ + Apache License + Version 2.0, January 2004 + http://www.apache.org/licenses/ + + TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION + + 1. Definitions. + + "License" shall mean the terms and conditions for use, reproduction, + and distribution as defined by Sections 1 through 9 of this document. + + "Licensor" shall mean the copyright owner or entity authorized by + the copyright owner that is granting the License. + + "Legal Entity" shall mean the union of the acting entity and all + other entities that control, are controlled by, or are under common + control with that entity. For the purposes of this definition, + "control" means (i) the power, direct or indirect, to cause the + direction or management of such entity, whether by contract or + otherwise, or (ii) ownership of fifty percent (50%) or more of the + outstanding shares, or (iii) beneficial ownership of such entity. + + "You" (or "Your") shall mean an individual or Legal Entity + exercising permissions granted by this License. + + "Source" form shall mean the preferred form for making modifications, + including but not limited to software source code, documentation + source, and configuration files. + + "Object" form shall mean any form resulting from mechanical + transformation or translation of a Source form, including but + not limited to compiled object code, generated documentation, + and conversions to other media types. + + "Work" shall mean the work of authorship, whether in Source or + Object form, made available under the License, as indicated by a + copyright notice that is included in or attached to the work + (an example is provided in the Appendix below). + + "Derivative Works" shall mean any work, whether in Source or Object + form, that is based on (or derived from) the Work and for which the + editorial revisions, annotations, elaborations, or other modifications + represent, as a whole, an original work of authorship. For the purposes + of this License, Derivative Works shall not include works that remain + separable from, or merely link (or bind by name) to the interfaces of, + the Work and Derivative Works thereof. + + "Contribution" shall mean any work of authorship, including + the original version of the Work and any modifications or additions + to that Work or Derivative Works thereof, that is intentionally + submitted to the Licensor for inclusion in the Work by the copyright owner + or by an individual or Legal Entity authorized to submit on behalf of + the copyright owner. For the purposes of this definition, "submitted" + means any form of electronic, verbal, or written communication sent + to the Licensor or its representatives, including but not limited to + communication on electronic mailing lists, source code control systems, + and issue tracking systems that are managed by, or on behalf of, the + Licensor for the purpose of discussing and improving the Work, but + excluding communication that is conspicuously marked or otherwise + designated in writing by the copyright owner as "Not a Contribution." + + "Contributor" shall mean Licensor and any individual or Legal Entity + on behalf of whom a Contribution has been received by the Licensor and + subsequently incorporated within the Work. + + 2. Grant of Copyright License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + copyright license to reproduce, prepare Derivative Works of, + publicly display, publicly perform, sublicense, and distribute the + Work and such Derivative Works in Source or Object form. + + 3. Grant of Patent License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + (except as stated in this section) patent license to make, have made, + use, offer to sell, sell, import, and otherwise transfer the Work, + where such license applies only to those patent claims licensable + by such Contributor that are necessarily infringed by their + Contribution(s) alone or by combination of their Contribution(s) + with the Work to which such Contribution(s) was submitted. If You + institute patent litigation against any entity (including a + cross-claim or counterclaim in a lawsuit) alleging that the Work + or a Contribution incorporated within the Work constitutes direct + or contributory patent infringement, then any patent licenses + granted to You under this License for that Work shall terminate + as of the date such litigation is filed. + + 4. Redistribution. You may reproduce and distribute copies of the + Work or Derivative Works thereof in any medium, with or without + modifications, and in Source or Object form, provided that You + meet the following conditions: + + (a) You must give any other recipients of the Work or + Derivative Works a copy of this License; and + + (b) You must cause any modified files to carry prominent notices + stating that You changed the files; and + + (c) You must retain, in the Source form of any Derivative Works + that You distribute, all copyright, patent, trademark, and + attribution notices from the Source form of the Work, + excluding those notices that do not pertain to any part of + the Derivative Works; and + + (d) If the Work includes a "NOTICE" text file as part of its + distribution, then any Derivative Works that You distribute must + include a readable copy of the attribution notices contained + within such NOTICE file, excluding any notices that do not + pertain to any part of the Derivative Works, in at least one + of the following places: within a NOTICE text file distributed + as part of the Derivative Works; within the Source form or + documentation, if provided along with the Derivative Works; or, + within a display generated by the Derivative Works, if and + wherever such third-party notices normally appear. The contents + of the NOTICE file are for informational purposes only and + do not modify the License. You may add Your own attribution + notices within Derivative Works that You distribute, alongside + or as an addendum to the NOTICE text from the Work, provided + that such additional attribution notices cannot be construed + as modifying the License. + + You may add Your own copyright statement to Your modifications and + may provide additional or different license terms and conditions + for use, reproduction, or distribution of Your modifications, or + for any such Derivative Works as a whole, provided Your use, + reproduction, and distribution of the Work otherwise complies with + the conditions stated in this License. + + 5. Submission of Contributions. Unless You explicitly state otherwise, + any Contribution intentionally submitted for inclusion in the Work + by You to the Licensor shall be under the terms and conditions of + this License, without any additional terms or conditions. + Notwithstanding the above, nothing herein shall supersede or modify + the terms of any separate license agreement you may have executed + with Licensor regarding such Contributions. + + 6. Trademarks. This License does not grant permission to use the trade + names, trademarks, service marks, or product names of the Licensor, + except as required for reasonable and customary use in describing the + origin of the Work and reproducing the content of the NOTICE file. + + 7. Disclaimer of Warranty. Unless required by applicable law or + agreed to in writing, Licensor provides the Work (and each + Contributor provides its Contributions) on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or + implied, including, without limitation, any warranties or conditions + of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A + PARTICULAR PURPOSE. You are solely responsible for determining the + appropriateness of using or redistributing the Work and assume any + risks associated with Your exercise of permissions under this License. + + 8. Limitation of Liability. In no event and under no legal theory, + whether in tort (including negligence), contract, or otherwise, + unless required by applicable law (such as deliberate and grossly + negligent acts) or agreed to in writing, shall any Contributor be + liable to You for damages, including any direct, indirect, special, + incidental, or consequential damages of any character arising as a + result of this License or out of the use or inability to use the + Work (including but not limited to damages for loss of goodwill, + work stoppage, computer failure or malfunction, or any and all + other commercial damages or losses), even if such Contributor + has been advised of the possibility of such damages. + + 9. Accepting Warranty or Additional Liability. While redistributing + the Work or Derivative Works thereof, You may choose to offer, + and charge a fee for, acceptance of support, warranty, indemnity, + or other liability obligations and/or rights consistent with this + License. However, in accepting such obligations, You may act only + on Your own behalf and on Your sole responsibility, not on behalf + of any other Contributor, and only if You agree to indemnify, + defend, and hold each Contributor harmless for any liability + incurred by, or claims asserted against, such Contributor by reason + of your accepting any such warranty or additional liability. + + END OF TERMS AND CONDITIONS + + Copyright 2026 Access to Services Contributors + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. diff --git a/README.md b/README.md new file mode 100644 index 0000000..b8a4c7b --- /dev/null +++ b/README.md @@ -0,0 +1,196 @@ +# Access to Services + +**A Social Determinants of Health (SDOH) screening and referral tool for Missouri.** + +Screen clients across 14 SDOH domains, estimate benefits eligibility using 2025 Federal Poverty Level guidelines, and generate referrals from a verified directory of 58+ Missouri social service organizations. + +Built as a [Claude skill](https://docs.anthropic.com) with an interactive React UI component. + +--- + +## Why This Exists + +Social service navigators, case managers, and community health workers spend significant time manually matching clients to programs and resources. This tool standardizes the screening process, surfaces benefits a client may qualify for, and connects flagged domains to verified local resources — all in one workflow. + +**This is not a diagnostic tool.** It is an educational screening aid. All eligibility results are estimates, not determinations. + +--- + +## What It Does + +### 1. Client Intake +Collects household composition, income, geography, and special circumstances (veteran status, disability, pregnancy, etc.) to inform eligibility screening. + +### 2. SDOH Screening (14 Domains) +Each domain uses a plain-language screening question appropriate for direct client conversation: + +| Domain | Screening Question | +|--------|--------------------| +| Food Security | Have you worried about running out of food in the past 30 days? | +| Housing | Are you worried about losing your housing or do you need a place to stay? | +| Safety | Do you feel physically and emotionally safe where you live? | +| Transportation | Can you reliably get to appointments and services? | +| Utilities | Have you had trouble paying utility bills in the past 12 months? | +| Financial Strain | Are you having trouble paying for basic needs like rent, food, or medicine? | +| Employment | Do you need help finding a job or a better job? | +| Education | Do you or your children need help with school, training, or GED? | +| Healthcare Access | Do you have health insurance and access to a doctor? | +| Mental Health | Have you been feeling down, depressed, hopeless, or overwhelmed? | +| Substance Use | Do you have concerns about alcohol or drug use? | +| Social Support | Do you have people you can count on for help and support? | +| Child Care | Do you have reliable, affordable child care? | +| Legal Issues | Do you have legal issues that need attention? | + +Responses are scored as **No concern** (0), **Some concern** (1), or **Urgent/Crisis** (2) to produce a composite SDOH score. + +### 3. Benefits Eligibility Estimation +Screens against 12 Missouri programs using income-to-FPL thresholds: + +| Program | FPL Threshold | Population | +|---------|:------------:|------------| +| SNAP | 130% | All | +| WIC | 185% | Pregnant / children under 5 | +| Medicaid (Adult) | 138% | Adults | +| Medicaid (Children) | 300% | Children | +| TANF | 50% | Families with children | +| Child Care Subsidy | 185% | Families with children | +| LIHEAP | 150% | All | +| School Meals (Free) | 130% | School-age children | +| School Meals (Reduced) | 185% | School-age children | +| Head Start | 100% | Children under 5 | +| Section 8 (HCV) | 50% | All (waitlist) | +| SSI | — | Disability required | + +### 4. Report Generation +Produces a structured screening summary with crisis flags, composite scores, benefits matches, and priority actions — ready to copy into case notes or send to a Claude chat for referral generation. + +--- + +## Resource Directory + +`mo-resources.json` contains **58 verified Missouri social service resources** following a structured schema ([SCHEMA.md](SCHEMA.md)). + +### Coverage + +| Area | Resources | Key Types | +|------|:---------:|-----------| +| Statewide | 16 | FSD, hotlines, CMHCs, legal aid, workforce, VR | +| National | 10 | 988, DV hotline, SAMHSA, Veterans Crisis Line, RAINN | +| St. Louis metro | 9 | FQHCs, shelters, DV services, housing authority, SUD | +| Kansas City metro | 6 | FQHCs, shelters, housing authority, legal aid | +| Mid-Missouri | 3 | FQHC, community action agencies | +| SE Missouri | 2 | FQHC, community action (Bootheel) | +| SW Missouri | 2 | CMHCs, food bank | +| Eastern MO | 3 | VA, legal aid, food bank | +| Western MO | 3 | VA, legal aid, food bank | + +### Service Types +Crisis hotlines, FQHCs, CMHCs, food banks, shelters (emergency + DV), housing authorities, legal aid, SUD treatment, veteran services, community action agencies, reentry programs, immigration services, disability advocacy, child care referral, workforce centers, and government programs. + +### Data Quality +- Every entry includes a `verified` date (YYYY-MM-DD) +- Entries older than 6 months are flagged for re-verification +- Validated against a [JSON Schema](mo-resources.schema.json) on every commit +- Schema enforces standard domain and population vocabularies + +--- + +## Project Structure + +``` +access-to-services/ +├── intake-app.jsx # React SDOH intake & screening component +├── mo-resources.json # Verified Missouri resource directory (58 entries) +├── mo-resources.schema.json # JSON Schema for resource validation +├── access-to-services.skill # Claude skill definition +├── SCHEMA.md # Human-readable schema & query guide +├── eval-results.md # Skill routing evaluation (15 test cases) +├── scripts/ +│ └── validate.js # Resource directory validation (schema + freshness) +├── tests/ +│ └── eligibility.test.js # 58 automated tests (FPL, eligibility, data integrity) +├── CONTRIBUTING.md # How to add resources and submit changes +├── LICENSE # Apache-2.0 (code) + CC-BY-4.0 (data) +└── .gitignore +``` + +--- + +## Quick Start + +### As a Claude Skill +The `access-to-services.skill` file is loaded directly by Claude. When active, it provides SDOH screening, benefits guidance, crisis triage, and referral generation backed by the resource directory. + +### Embedding the React Component + +```jsx +import SDOHIntakeApp from "./intake-app"; + +function App() { + return ; +} +``` + +The component expects an optional global `sendPrompt(text)` function for chat integration. If unavailable, "Send to Chat" falls back to clipboard copy. + +### Validating Resources + +```bash +# Validate schema, vocabulary, freshness, and actionability +node scripts/validate.js + +# Run all automated tests (FPL, eligibility, data integrity) +node tests/eligibility.test.js +``` + +--- + +## Contributing + +We welcome contributions from navigators, case managers, social workers, developers, and anyone who wants to improve access to services. + +**Common contributions:** +- Adding a new resource to `mo-resources.json` +- Reporting outdated phone numbers or hours +- Improving accessibility or mobile responsiveness +- Adding coverage for underserved Missouri regions + +See [CONTRIBUTING.md](CONTRIBUTING.md) for the full guide, including required fields, validation steps, and submission process. + +--- + +## Accessibility + +The React component includes: +- Semantic HTML (`
`, `