diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 84fa1826..294f84cc 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -1,29 +1,31 @@ ## Description - + -## Related Issue - +## Related Issues + -## Changes Made - +Closes # + +## Type of Change +- [ ] 🐛 Bug fix (non-breaking) +- [ ] ✨ New feature (non-breaking) +- [ ] 💥 Breaking change +- [ ] 📚 Documentation +- [ ] 🧪 Tests only +- [ ] 🔴 Core change (requires RFC) -- -- -- ## Testing - + + +- [ ] `uv run pytest` passes locally and generates no additional warnings or errors. +- [ ] Added / updated tests to cover the changes. +- [ ] Manually tested (describe how) + ## Checklist - - -- [ ] I have read the [contributing](https://github.com/dotimplement/HealthChain/CONTRIBUTING.md) guidelines -- [ ] I have performed a self-review of my own code -- [ ] I have commented my code, particularly in hard-to-understand areas -- [ ] I have made corresponding changes to the documentation -- [ ] My changes generate no new warnings -- [ ] I have added tests that prove my fix is effective or that my feature works -- [ ] New and existing unit tests pass locally with my changes - -## Additional Notes - +- [ ] I have read [`CONTRIBUTING.md`](https://github.com/dotimplement/HealthChain/blob/main/CONTRIBUTING.md) and followed the guidelines. +- [ ] I have linked all relevant Issues / Discussions / RFCs. +- [ ] I have updated documentation where needed. +- [ ] I understand all code changes and can explain the design decisions and trade-offs. +- [ ] I am available to respond to review feedback. diff --git a/CLAUDE.MD b/CLAUDE.MD index 1f199cfb..1ac45c61 100644 --- a/CLAUDE.MD +++ b/CLAUDE.MD @@ -1,193 +1,167 @@ # HealthChain - Claude Code Context -## Project Overview +> **Purpose**: This file guides AI assistants and developers working on HealthChain. It encodes coding standards, constraints, and workflows to keep architecture and domain judgment in human hands. It's a working document that will be updated as the project evolves. -HealthChain is an open-source Python framework for productionizing healthcare AI applications with native protocol understanding. It provides built-in FHIR support, real-time EHR connectivity, and production-ready deployment capabilities for AI/ML engineers working with healthcare systems. +## 0. Project Overview -**Key Problem Solved**: EHR data is specific, complex, and fragmented. HealthChain eliminates months of custom integration work by providing native understanding of healthcare protocols and data formats. +HealthChain is an open-source Python framework for productionizing healthcare AI applications with native protocol understanding. It provides built-in FHIR support, real-time EHR connectivity, and deployment tooling for healthcare AI/ML systems. + +**Key Problem**: EHR data is specific, complex, and fragmented. HealthChain eliminates months of custom integration work by understanding healthcare protocols and data formats out of the box. **Target Users**: - HealthTech engineers building clinical workflow integrations - LLM/GenAI developers aggregating multi-EHR data - ML researchers deploying models as healthcare APIs -## Architecture & Structure +For more background, see @README.md and @docs/index.md. + +--- + +## 1. Non-Negotiable Golden Rules + +| # | AI *may* do | AI *must NOT* do | +|---|-------------|------------------| +| G-0 | When unsure about implementation details or requirements, ask developer for clarification before making changes. | ❌ Write changes or use tools when you are not sure about something project specific, or if you don't have context for a particular feature/decision. | +| G-1 | Generate code inside `healthchain/` or explicitly pointed files. | ❌ Modify or create test files without explicit approval. | +| G-2 | For changes >200 LOC or >3 files, propose a plan and wait for confirmation. | ❌ Refactor large modules without human guidance. | +| G-3 | Follow lint/style configs (`pyproject.toml`, `.ruff.toml`). Use `ruff` for formatting. | ❌ Reformat code to any other style. | +| G-4 | Stay within the current task context. Inform the dev if it'd be better to start afresh. | ❌ Continue work from a prior prompt after "new task" – start a fresh session. | + +--- + +## 2. Testing Discipline + +| What | AI CAN Do | AI MUST NOT Do | +|------|-----------|----------------| +| Implementation | Generate business logic | Write new tests without confirmation | +| Test Planning | Suggest test scenarios and coverage gaps | Implement test code during design phase | +| Debugging | Analyze test failures and suggest fixes | Modify test expectations without approval | + +**Key principle**: Tests encode business requirements and human intent. AI assistance is welcome for suggestions, maintenance, and execution, but new test creation always requires explicit confirmation. + +--- + +## 3. Build, Test & Utility Commands + +Use `uv` for all development tasks: + +```bash +# Testing +uv run pytest + +# Linting & Formatting +uv run ruff check . --fix # Lint and auto-fix +uv run ruff format . # Format code + +# Dependency Management +uv sync # Install/sync dependencies +uv add # Add dependency +uv add --dev # Add dev dependency +``` + +--- + +## 4. Coding Standards + +- **Python**: 3.10-3.11, prefer sync for legacy EHR compatibility; async available for modern systems but use only when explicitly needed +- **Dependencies**: Pydantic v2 (<2.11.0), NumPy <2.0.0 (spaCy compatibility) +- **Environment**: Use `uv` to manage dependencies and run commands (`uv run `) +- **Formatting**: `ruff` enforces project style +- **Typing**: Always use explicit type hints, even for obvious types; Pydantic v2 models for external data +- **Naming**: + - Code: `snake_case` (functions/vars), `PascalCase` (classes), `SCREAMING_SNAKE` (constants) + - Files: No underscores, e.g., `fhiradapter.py` not `fhir_adapter.py` +- **Error Handling**: Prefer specific exceptions over generic +- **Documentation**: Docstrings for public APIs only +- **Healthcare Standards**: Follow HL7 FHIR and CDS Hooks specifications +- **Testing**: Separate test files matching source file patterns. Use flat functions instead of classes for tests. + +--- + +## 5. Project Layout & Core Components ``` healthchain/ -├── cli.py # Command-line interface -├── config/ # Configuration management -├── configs/ # YAML and Liquid templates -├── fhir/ # FHIR resource utilities and helpers -├── gateway/ # API gateways (FHIR, CDS Hooks) -├── interop/ # Format conversion (FHIR ↔ CDA) -├── io/ # Document and data I/O -├── models/ # Pydantic data models -├── pipeline/ # Pipeline components and NLP integrations -├── sandbox/ # Testing utilities with synthetic data -├── templates/ # Code generation templates -└── utils/ # Shared utilities - -tests/ # Test suite -cookbook/ # Usage examples and tutorials -docs/ # MkDocs documentation +├── cli.py # CLI entrypoint +├── config/ # Configuration management +├── configs/ # YAML + Liquid configs/templates +├── fhir/ # FHIR utilities and helpers +├── gateway/ # API gateways (FHIR, CDS Hooks) +├── interop/ # Format conversion (FHIR ↔ CDA, etc.) +├── io/ # Data containers, adapters, mappers (external formats ↔ HealthChain) +├── models/ # Pydantic data models +├── pipeline/ # Pipeline components and NLP integrations +├── sandbox/ # CDS Hooks testing scenarios & data loaders +├── templates/ # Code generation templates +└── utils/ # Shared utilities + +tests/ # Test suite +cookbook/ # Usage examples and tutorials +docs/ # MkDocs documentation ``` -## Core Modules - -### 1. Pipeline (`healthchain/pipeline/`) -- Build medical NLP pipelines with components like SpacyNLP -- Process clinical documents with automatic FHIR conversion -- Type-safe pipeline composition using generics - -### 2. Gateway (`healthchain/gateway/`) -- **FHIRGateway**: Connect to multiple FHIR sources, aggregate patient data -- **CDSHooksGateway**: Real-time clinical decision support integration with Epic/Cerner -- **HealthChainAPI**: FastAPI-based application framework - -### 3. FHIR Utilities (`healthchain/fhir/`) -- Type-safe FHIR resource creation and validation -- Bundle manipulation and resource extraction -- Recently refactored for clearer separation of concerns - -### 4. Interop (`healthchain/interop/`) -- Convert between FHIR and CDA formats -- Configuration-driven templates using Liquid -- Support for various healthcare data standards - -### 5. Sandbox (`healthchain/sandbox/`) -- Test CDS Hooks services with synthetic data -- Load from test datasets (Synthea, MIMIC) -- Request/response validation and debugging - -### 6. I/O (`healthchain/io/`) -- Document processing and management -- Data loading for ML workflows -- Recently refactored for better organization - -## Development Guidelines - -### Code Style -- **Linter**: Ruff for code formatting and linting -- **Type Hints**: Use Pydantic models and type annotations throughout -- **Python Version**: Support 3.9-3.11 (not 3.12+) -- **Testing**: pytest with async support (`pytest-asyncio`) - -### Key Dependencies -- **fhir.resources**: FHIR resource models (v8.0.0+) -- **FastAPI/Starlette**: API framework -- **Pydantic**: Data validation (v2.x, <2.11.0) -- **spaCy**: NLP processing (v3.x) -- **python-liquid**: Template engine for data conversion - -### Patterns & Conventions - -1. **Type Safety**: Leverage Pydantic models for all data structures -2. **Pipeline Pattern**: Use composable components with `Pipeline[T]` generic type -3. **Gateway Pattern**: Extend base gateway classes for new integrations -4. **Configuration**: Use YAML configs in `configs/` directory -5. **Templates**: Liquid templates for FHIR/CDA conversion - -### Testing -- Tests organized in `tests/` mirroring source structure -- Use pytest fixtures for common test data -- Async tests for gateway/API functionality -- Recently consolidated test structure - -### Documentation - -**Style Guide:** -- **Concise**: Get to the point quickly - developers want answers, not essays -- **Friendly**: Conversational but professional tone; use emojis sparingly in headers -- **Developer-Friendly**: Code examples first, explanations second; show don't tell -- **Scannable**: Use bullets, tables, clear sections; respect developer's time -- **Practical**: Focus on "how" over "why"; include working code examples - -**Good Documentation Examples:** -- `docs/index.md`: Clean feature overview, clear use case table, minimal prose -- `docs/quickstart.md`: Code-first approach, progressive complexity, practical examples -- `docs/cookbook/index.md`: Brief descriptions, clear outcomes, call-to-action - -**Anti-Patterns (avoid):** -- Long paragraphs explaining concepts before showing code -- Over-explaining obvious functionality -- Academic or overly formal tone -- Excessive background before getting to the practical content - -**Structure:** -- Lead with executable code examples -- Add brief context only where needed -- Use tables for feature comparisons -- Include links to full docs for deep dives -- Keep cookbook examples focused on one task - -**Technical Details:** -- MkDocs with Material theme -- API reference auto-generated from docstrings using mkdocstrings -- Cookbook examples for common use cases -- Follow existing docs/ structure for consistency - -## Recent Changes & Context - -Based on recent commits: -- **FHIR Helper Module**: Refactored for clearer separation of utilities -- **I/O Module**: Refactored for better organization -- **Test Consolidation**: Tests reorganized for clarity -- **MIMIC Loader**: Added support for loading as dict for ML workflows -- **Bundle Conversion**: Config-based conversion instead of params - -## Important Workflows - -### Adding a New Gateway -1. Create class in `healthchain/gateway/` extending base gateway -2. Implement required protocol methods -3. Add configuration in `configs/` -4. Create sandbox test in `healthchain/sandbox/` -5. Add cookbook example in `cookbook/` - -### Adding FHIR Resource Support -1. Use `fhir.resources` models -2. Add helper methods in `healthchain/fhir/` if needed -3. Update type hints and validation -4. Add tests with synthetic FHIR data - -### Adding Data Conversion Templates -1. Create Liquid template in `configs/` -2. Add configuration YAML -3. Implement in `healthchain/interop/` -4. Test with real healthcare data examples - -## Common Gotchas - -1. **Pydantic v2**: Use v2 patterns, but stay <2.11.0 for compatibility -2. **NumPy**: Locked to <2.0.0 for spaCy compatibility -3. **FHIR Validation**: Always validate resources before serialization -4. **Async/Sync**: Gateway operations are async, pipeline operations are sync -5. **Healthcare Standards**: Follow HL7 FHIR R4 and CDS Hooks specifications - -## Testing with Real Data - -- **Synthea**: Synthetic patient generator for realistic test data -- **MIMIC**: Medical Information Mart for Intensive Care dataset support -- **Sandbox**: Use `SandboxClient` for end-to-end testing without real EHR - -## Security & Compliance - -- OAuth2 authentication support for FHIR endpoints -- Audit trails and data provenance (roadmap item) -- HIPAA compliance features (roadmap item) -- No PHI in tests - use synthetic data only - -## Deployment - -- Docker/Kubernetes support (enhanced support on roadmap) -- FastAPI apps with Uvicorn -- OpenAPI/Swagger documentation auto-generated -- Environment-based configuration - -## Resources - -- Documentation: https://dotimplement.github.io/HealthChain/ -- Repository: https://github.com/dotimplement/HealthChain -- Discord: https://discord.gg/UQC6uAepUz -- Standards: HL7 FHIR R4, CDS Hooks +### Key Modules (When to Use What) + +| Module | Purpose | +|--------|---------| +| `pipeline/` | Document/patient NLP with `Pipeline[T]` generics | +| `gateway/` | EHR connectivity and protocol handling (CDS Hooks, FHIR APIs, SOAP/CDA) | +| `fhir/` | FHIR resource utilities (fhir.resources models) and helpers | +| `interop/` | Format conversion with Liquid templates + YAML (FHIR ↔ CDA, etc.) | +| `io/` | **Containers**: FHIR+AI native structures
**Mappers**: semantic mapping (ML features, OMOP)
**Adapters**: interface with external formats (CDA, CSV) | +| `sandbox/` | Testing client for healthcare services (CDS Hooks, SOAP) & dataset loaders for common test datasets (MIMIC-IV on FHIR, Synthea, etc.) | + +### Key File References + +**FHIR Utilities Pattern**: @healthchain/fhir/ +**Adapter Pattern**: @healthchain/io/adapters/ +**Container Pattern**: @healthchain/io/containers/ +**Mapper Pattern**: @healthchain/io/mappers/ +**Pipeline Pattern**: @healthchain/pipeline/ +**Gateway Pattern**: @healthchain/gateway/ + +--- + +## 6. Common Workflows + +### AI Assistant Workflow + +When responding to user instructions, follow this process: + +1. **Consult Relevant Guidance**: Review this CLAUDE.md and relevant patterns in @healthchain/ for the request. Look up relevant files, information, best practices, etc. using the internet or tools if necessary. +2. **Clarify Ambiguities**: If anything is unclear, ask targeted questions before proceeding. Don't make assumptions about business logic or domain requirements. +3. **Break Down & Plan**: + - Break down, think through the problem, and create a rough plan + - Reference project conventions and best practices + - **Trivial tasks**: Start immediately + - **Non-trivial tasks** (>200 LOC or >3 files): Present plan → wait for user confirmation +4. **Execute**: + - Make small, focused diffs + - Prefer existing abstractions over new ones + - Run: `uv run ruff check . --fix && uv run ruff format .` + - If stuck, return to step 3 to re-plan +5. **Review**: Summarize files changed, key design decisions, and any follow-ups or TODOs +6. **Session Boundaries**: If request isn't related to current context, suggest starting fresh to avoid confusion + +### Adding New FHIR Resource Utilities + +1. Check for existing utilities in @healthchain/fhir/ +2. If missing, ask: "Create utility function for [ResourceType]?" +3. Follow pattern: MINIMUM VIABLE resource, all variable data as parameters +4. Avoid overly specific utilities; prefer generic +--- + +## 7. Common Pitfalls + +**Do:** +- Use `uv run` to run commands instead of directly running files in the environment + +**Don't:** +- Commit secrets (use environment variables or `.env` file) +- Make drive-by refactors +- Write code before planning +- Write tests during design phase + +--- + +**Last updated**: 2025-12-17 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 01365de4..ff01678e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,103 +1,223 @@ # Contributing -First of all, thank you for being interested in contributing to HealthChain, we welcome contributions of all kinds! Listed below are some of the ways you can get involved. +Thank you for your interest in contributing to HealthChain! -## Reporting Issues +Before you start, please read this guide to understand how to propose changes, open pull requests, and collaborate effectively. + +## ✅ Before you open a pull request +To keep reviews efficient and maintain project quality, PRs must meet these basics (or may be closed without in‑depth review): + +- [ ] Small, focused on a single change or issue +- [ ] Links to at least one [`GitHub Issue`](https://github.com/dotimplement/HealthChain/issues) or [`RFC`](https://github.com/dotimplement/HealthChain/tree/main/docs/rfcs) (Request for Comments) with context and trade‑offs explained in the description +- [ ] All tests pass locally; new functionality has tests and docs +- [ ] For `core`, `Stage: Research 🔬`, or `Stage: Design 🎨` labels: has accepted RFC +- [ ] Not sure about scope? Open a [GitHub Discussion](https://github.com/dotimplement/HealthChain/discussions) first + +## Contributing health & domain expertise + +Real‑world experience from healthcare, public health, and digital health products is crucial for making HealthChain useful and safe. + +You can contribute domain expertise by: + +- Opening [`Issues`](https://github.com/dotimplement/HealthChain/issues) or [`Discussions`](https://github.com/dotimplement/HealthChain/discussions) that describe real workflows, data models (e.g. FHIR resources), regulatory or security constraints, and integration needs. +- Commenting on `Stage: Research 🔬` and `Stage: Design 🎨` issues with context from clinical practice, informatics, or implementation experience. +- Co‑authoring RFCs that capture requirements for consent, auditing, interoperability, and safety‑related behaviors. + +When you open a domain‑focused issue, please include: + +- Context (setting, jurisdiction, type of organization). +- The problem you are trying to solve. +- Any relevant standards (FHIR profiles, policies, regulations) and links. + +## 🤝 For integrators, companies, and partners + +If you are exploring HealthChain for use in your product or organization, or want to co‑design an integration or partnership: + +**For substantial partnerships or integrations:** +- Shoot me an [email](mailto:jenniferjiangkells@gmail.com?subject=HealthChain) +- Join our [weekly office hours](https://meet.google.com/zwh-douu-pky) (Thursdays 4.30pm - 5.30pm GMT) for direct Q&A +- Join the [Discord](https://discord.gg/UQC6uAepUz) `#production-users` channel + +**For feature collaborations:** +Once we've aligned on a collaboration, we'll track it using GitHub issues with stage labels: +- **Stage: Research 🔬** = Gathering requirements and exploring the problem space +- **Stage: Design 🎨** = Designing the solution (often via RFC for core features) +- Co-authored RFCs welcome for features you're willing to help build/maintain + +**For exploratory technical discussions:** +Use [GitHub Discussions](https://github.com/dotimplement/HealthChain/discussions) to brainstorm architecture options and gather community input. + +**We're particularly interested in:** +- Pilot deployments and production integrations +- Co-maintained adapters for specific EHR systems +- Sponsored features with committed engineering resources +- Research collaborations and case studies + +## 🐛 Reporting Issues Found a bug? Have a suggestion for a new feature? You can help us improve by: -- **Submitting Bug Reports**: Clearly describe the issue, including steps to reproduce it, the expected outcome, and any relevant screenshots or logs. -- **Suggesting Enhancements**: Share your ideas for new features or improvements. Please provide as much detail as possible to help us understand your vision. +- **Submitting Bug Reports**: Clearly describe the issue, steps to reproduce, expected outcome, actual outcome, and any relevant logs or screenshots. +- **Suggesting Enhancements**: Describe the problem you face, not only your proposed solution. Include user stories, constraints, and any alternatives considered. + +For broad, exploratory ideas or "is this a good idea?" questions, please prefer [GitHub Discussions](https://github.com/dotimplement/HealthChain/discussions) over large PRs. + +- Use the `Ideas` category for high‑level proposals. +- Link any related Discussion from the corresponding issue if applicable. +- Once there is a concrete proposal, move to an RFC PR so we have a stable, version‑controlled record of the design. + +## 📚 Improving Documentation + +Good documentation is critical in healthcare. You can help by: + +- **Updating Existing Documentation**: Fixing inaccuracies, clarifying concepts, and keeping examples and setup instructions current. +- **Creating New Documentation**: Writing guides, tutorials, implementation notes, or health‑domain explainers that help others adopt and safely operate HealthChain. + +When writing docs: + +- Prefer clear, concise language and use headings and lists for structure. +- Include code snippets or configuration examples where helpful. +- Call out assumptions, limitations, and safety‑relevant behaviour explicitly. + +## 💻 Writing Code + +>**New to HealthChain?** Look for [`good first issue`](https://github.com/dotimplement/HealthChain/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) and [`help wanted`](https://github.com/dotimplement/HealthChain/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22) labels. + +**Check the [project board](https://github.com/orgs/dotimplement/projects/1/views/1)** to see current priorities and what's actively being worked on. -## Improving Documentation +You can contribute code by: -Good documentation helps others understand and use our project. You can contribute by: +- **Fixing Bugs**: Pick issues labelled [`Issue: Bug 🐛`](https://github.com/dotimplement/HealthChain/issues?q=is%3Aissue+is%3Aopen+label%3A%22Issue%3A+Bug+%F0%9F%90%9B%22) and reference the issue number in your commits and PR. +- **Implementing Features**: For non‑trivial features, start with an issue or Discussion to confirm scope and fit, and use the RFC process for anything touching core areas. +- **Improving Tests**: Increase coverage, add regression tests for fixed bugs, and improve reliability of existing test suites. -- **Updating Existing Documentation**: Fix typos, clarify instructions, and ensure all information is up to date. -- **Creating New Documentation**: Write new guides, tutorials, or examples that help users and developers get the most out of our project. +### Core Changes and RFCs -## Writing Code +Some changes have a large impact on security, architecture, and stability. These are gated by an RFC (Request for Comments) process and specific labels: -If you're a developer, there are many ways you can contribute code: +- `Stage: Research 🔬`: The problem and constraints are being explored; we are collecting context and options, not implementations. +- `Stage: Design 🎨`: The problem is understood and we are working towards a concrete design; implementation is not yet agreed. +- `core`: High‑impact or security‑sensitive changes (e.g. authentication, authorization, data model, API contracts, persistence, deployment architecture). -- **Fixing Bugs**: Look through the issue tracker and find bugs that you can fix. Be sure to reference the issue number in your commit messages. -- **Implementing Features**: Work on new features or enhancements. Discuss your ideas with the maintainers first to make sure they align with the project's goals. -- **Improving Tests**: Increase test coverage and ensure the codebase is robust and reliable. +For issues with any of these labels: -## Join Our Discord +- An agreed RFC is required before implementation PRs are opened. +- Implementation PRs must link to the accepted RFC and follow the agreed approach. +- PRs that bypass this process may be closed without detailed review. -Are you a domain expert with valuable insights? We encourage you to join our [Discord community](https://discord.gg/UQC6uAepUz) and share your wisdom. Your expertise can help shape the future of the project and guide us in making informed decisions. +For larger changes, especially related to authentication/authorization, persistence, public API, or deployment/operations: -We believe that every contribution, big or small, makes a difference. Thank you for being a part of our community! +- Check for an existing `Stage: Research 🔬`, `Stage: Design 🎨`, or `core` issue. +- Comment on the issue or start a [`GitHub Discussion`](https://github.com/dotimplement/HealthChain/discussions) if the problem or approach is unclear. +- Follow the [`RFC process`](#how-to-create-an-rfc) before opening an implementation PR. -## How to Contribute Code +**Quick reference:** +- 🔴 **RFC required**: Auth, specification implementation (SMART on FHIR, CDS Hooks, etc.), security, persistence, API contracts +- 🟡 **Discussion recommended**: New gateways/pipelines, significant I/O loaders, breaking changes +- 🟢 **No RFC needed**: Bug fixes, docs, tests, small refactors -This project uses `uv` for dependency management. For more information see the [uv documentation](https://docs.astral.sh/uv/). +## 📋 How to Create an RFC -1. Fork the repository to your own GitHub account. For more details check out [github documentation](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo). +For `Stage: Research 🔬`, `Stage: Design 🎨`, and `core` issues, RFCs are used to agree on the approach before writing significant code. -2. Clone the forked repository to your local machine. +RFCs live in this repository under `docs/rfcs/`. To propose an RFC: -3. Run `uv sync --all-extras --dev` to install all the necessary development dependencies. +1. Pick an open issue with a stage/core label, or open a new issue describing the problem and context. +2. Copy `docs/rfcs/000-template.md` to `docs/rfcs/NNN-short-title.md` (replace `NNN` with the next number and `short-title` with a short description). +3. Fill in the template with problem, goals, proposed design, risks, and impact. +4. Open a pull request titled `RFC: `, linking to the related issue (and any Discussions). +5. Maintainers and contributors will review, ask questions, and suggest changes. +6. Once there is consensus, a maintainer will set the `Status` to `Accepted` or `Rejected` and merge or close the PR. -4. Try running `uv run pytest` to check that all is working as expected. +### After an RFC is Accepted -5. Create a new branch for your feature or bugfix. +- You (or another contributor) can open implementation PRs that state `Implements RFC NNN: ` and link back to the RFC. +- If an implementation PR diverges from the accepted RFC in a significant way, we may ask for a follow‑up RFC or additional design discussion. + +## 💬 Join our Discord + +If you are: + +- Evaluating HealthChain for your organisation or product +- A clinician, informatician, or health data specialist +- Interested in co‑designing features, integrations, or pilots + +…join our [Discord](https://discord.gg/UQC6uAepUz) community for quick questions and discussions. This is often the easiest way to discuss integrations, deployment questions, and partnership ideas before formalizing them in issues or RFCs. + +## ⚙️ How to Contribute Code + +This project uses `uv` for dependency management. See the [uv documentation](https://docs.astral.sh/uv/) for more information. + +1. [Fork the repository to your own GitHub account](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo). +2. Clone your fork locally. +3. Run `uv sync --all-extras --dev` to install all development dependencies. +4. Run `uv run pytest` to ensure tests pass. +5. Create a new branch for your change: ```shell git checkout -b my-feature-branch ``` - -6. Pre-commit is a package for checking and auto-formatting code to have a consistent style. If you don't have pre-commit installed locally then you may need to follow the instructions [here](https://pre-commit.com/). You can then install our hooks by running: - +6. Install pre‑commit hooks (after installing [pre-commit](https://pre-commit.com/)): ```shell pre-commit install ``` - -7. Make your changes and commit them with descriptive commit messages. +7. Make your changes and commit them with descriptive messages: ```shell git commit -m "Add new feature to do X" ``` - -8. Push your changes to your forked repository. +8. Push your changes to your fork: ```shell git push origin my-feature-branch ``` - -9. Open a pull request on the original repository. +9. Open a pull request on the main repository. ### Contributing to Documentation -We use `Mkdocs` for our documentation site. To download the dependencies for documentation, run: -```shell -uv sync --group docs -``` +To work on the documentation site ([MkDocs](https://www.mkdocs.org/)): + +- Install the doc dependencies: + + ```shell + uv sync --group docs + ``` +- Run the docs site locally: + + ```shell + uv run mkdocs serve + ``` +When contributing docs: + +- Use clear headings and subheadings. +- Prefer examples and concrete scenarios, especially for health workflows and integrations. +- Keep style consistent and use active voice. + +## 🧪 Testing + +All new functionality must include tests, and all existing tests must pass. + +- Add or update unit/integration tests to cover your changes. +- Run `uv run pytest` before opening or updating a PR. +- If tests are flaky or slow, mention this in the PR so maintainers can help improve them. + + +## 🔍 Pull request expectations -To preview the docs page in development: -```shell -uv run mkdocs serve -``` -#### Writing Clear Documentation +When opening a PR: -- **Be Concise**: Use clear and concise language to explain concepts and instructions. -- **Use Headings**: Organize content with headings and subheadings to improve readability. -- **Code Examples**: Include code examples to illustrate usage and functionality. -- **Consistent Style**: Follow a consistent style and format throughout the documentation. -- **Active Voice**: Write in the active voice to make instructions direct and easy to follow. -- **Bullet Points**: Use bullet points or numbered lists for steps and key points. +- Ensure your changes follow the style guide and pass all tests. +- Use a clear, descriptive title and explain what the PR does and why. +- Link related issues and RFCs (e.g. Closes #123, Implements RFC 004). +- Describe how you tested your changes and any known limitations or follow‑ups. -## Testing -Make sure to add tests for any new functionality you add. Run all tests to ensure that your changes do not break existing functionality. +## 🤖 Tooling and AI Assistance -## Pull Request Process +We welcome and encourage the use of AI tools to support development, but contributors remain responsible for the changes they submit. -1. Ensure your changes comply with the style guide. -2. Ensure all tests pass. -3. Open a pull request with a clear title and description of your changes. -4. A project maintainer will review your pull request and may request changes. -5. Once approved, your pull request will be merged. +- Make sure you understand every line of code and can explain the design and trade‑offs. +- All code changes must be understood and reviewed by humans. +- Maintainers reserve the right to close low-context, unexplained, AI-generated PRs without detailed review. -Thank you for your contributions! +For broader project context, see the [CLAUDE.md](CLAUDE.MD) file. diff --git a/README.md b/README.md index f0c1730f..a004dda6 100644 --- a/README.md +++ b/README.md @@ -133,6 +133,18 @@ HealthChain understands healthcare protocols and data formats natively, so you d - **Built-in NLP support** - Extract structured data from clinical notes, output as FHIR - **Developer experience** - Modular and extensible architecture works across any EHR system +## 🏆 Recognition & Community + +**Featured & Presented:** +- [Featured by Medplum](https://www.medplum.com/blog/healthchain) for open source integration with Epic +- Featured in [TLDR AI Newsletter](https://tldr.tech/ai/2025-08-21) (900K+ developers) +- Presented at [NHS Python Open Source Conference](https://github.com/nhs-r-community/conference-2024/blob/main/Talks/2024-11-21_jiang-kells_building-healthchain.md) ([watch talk](https://www.youtube.com/watch?v=_ZqlPsDUdSY&t=1967s)) +- [Built from NHS AI deployment experience](https://open.substack.com/pub/jenniferjiangkells/p/healthchain-building-the-tool-i-wish) – read the origin story + +## 🤝 Partnerships & Production Use + +Exploring HealthChain for your product or organization? Drop in our [weekly office hours](https://meet.google.com/zwh-douu-pky) (Thursdays 4.30pm - 5.30pm GMT) or [get in touch](mailto:jenniferjiangkells@gmail.com) to discuss integrations, pilots, or collaborations. + ## Usage Examples ### Building a Pipeline [[Docs](https://dotimplement.github.io/HealthChain/reference/pipeline/pipeline)] @@ -215,23 +227,34 @@ responses = client.send_requests() client.save_results("./output/") ``` -## Road Map +## 🛣️ Road Map -- [ ] 🔍 Data provenance and audit trails tracking -- [ ] 🔒 HIPAA compliance and security +- [ ] 🔍 Data provenance and observability +- [ ] 🔒 Production security and compliance (Authentication, audit logging, HIPAA) - [ ] 🔄 HL7v2 parsing, FHIR profile conversion and OMOP mapping support -- [ ] 🚀 Enhanced deployment support with observability and telemetry (Docker, Kubernetes, etc.) +- [ ] 🚀 Enhanced deployment support (Docker, Kubernetes, telemetry) - [ ] 📊 Model performance monitoring with MLFlow integration - [ ] 🤖 MCP server integration -## Contribute -We are always eager to hear feedback and suggestions, especially if you are a developer or researcher working with healthcare systems! -- 💡 Let's chat! [Discord](https://discord.gg/UQC6uAepUz) -- 🛠️ [Contribution Guidelines](CONTRIBUTING.md) +## 🤝 Contributing + +HealthChain is built for production healthcare systems. We prioritize contributors with: + +- **Healthcare product experience** – shipped clinical systems, EHR integrations, or health data products +- **FHIR expertise** – designed or implemented FHIR APIs and interoperability solutions +- **Healthcare security background** – auth, privacy, compliance in regulated environments + +If that's you, we'd love your input! + +**Get started:** +- See the [project board](https://github.com/orgs/dotimplement/projects/1/views/1) for current roadmap and active work +- Read [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines and RFC process +- Discuss ideas in [GitHub Discussions](https://github.com/dotimplement/HealthChain/discussions) +- Join our [Discord](https://discord.gg/UQC6uAepUz) community -## Acknowledgements 🤗 +## 🤗 Acknowledgements This project builds on [fhir.resources](https://github.com/nazrulworld/fhir.resources) and [CDS Hooks](https://cds-hooks.org/) standards developed by [HL7](https://www.hl7.org/) and [Boston Children's Hospital](https://www.childrenshospital.org/). diff --git a/docs/community/contribution_guide.md b/docs/community/contribution_guide.md deleted file mode 100644 index 2372c899..00000000 --- a/docs/community/contribution_guide.md +++ /dev/null @@ -1 +0,0 @@ -# Contribution Guide diff --git a/docs/community/index.md b/docs/community/index.md index 241404ac..7680a8fd 100644 --- a/docs/community/index.md +++ b/docs/community/index.md @@ -1,5 +1,15 @@ # Community -## Contribute +## Get Involved -[Contributing Guidelines](https://github.com/dotimplement/HealthChain/blob/main/CONTRIBUTING.md) +- **Discord**: Join our [Discord community](https://discord.gg/UQC6uAepUz) for questions, discussions, and connecting with other users +- **Office Hours**: Weekly office hours every Thursday 4:30pm - 5:30pm GMT ([join here](https://meet.google.com/zwh-douu-pky)) +- **GitHub Discussions**: For exploratory ideas and architecture discussions +- **Contributing**: See [CONTRIBUTING.md](https://github.com/dotimplement/HealthChain/blob/main/CONTRIBUTING.md) for full guidelines + +## For Domain Experts & Partners + +If you have healthcare, FHIR, or security experience, we want your input! +See the [Contributing section](https://github.com/dotimplement/HealthChain/blob/main/CONTRIBUTING.md#contributing-health--domain-expertise) for how to get fast-track review. + +For partnerships and integrations, email [jenniferjiangkells@gmail.com](mailto:jenniferjiangkells@gmail.com). diff --git a/docs/community/resources.md b/docs/community/resources.md deleted file mode 100644 index 3c1229ee..00000000 --- a/docs/community/resources.md +++ /dev/null @@ -1 +0,0 @@ -# Resources diff --git a/docs/rfcs/000-template.md b/docs/rfcs/000-template.md new file mode 100644 index 00000000..16096c0f --- /dev/null +++ b/docs/rfcs/000-template.md @@ -0,0 +1,77 @@ +> This template is meant to be a starting point; feel free to remove any sections that you can't really fill out just yet. +> +# RFC NNN: <Short, descriptive title> + +- Author: <name or GitHub handle> +- Status: Draft | In Review | Accepted | Rejected | Superseded +- Created: <YYYY-MM-DD> +- Related Issue(s): #<issue-number> +- Related Discussion(s): <link(s) if any> + +## 1. Summary + +One or two paragraphs describing the problem and the proposed solution at a high level, focused on HealthChain’s goals and users. + +## 2. Problem statement + +- What problem are we trying to solve? +- Who is affected (e.g. API consumers, operators, patients, integrators)? +- Why is this important now? + +Include any relevant context, such as existing limitations or incidents. + +## 3. Goals and non-goals + +### Goals + +- Clear, concrete goals this RFC aims to achieve. + +### Non-goals + +- Things that are explicitly out of scope for this change to avoid scope creep. + +## 4. Background and context + +Summarize relevant existing behavior, architecture, and constraints in HealthChain. +Link to code, docs, or external standards (e.g. FHIR, SMART on FHIR, OIDC) that inform the design. + +## 5. Proposed design + +Describe the proposed solution in enough detail that another contributor could implement it: + +- High-level architecture and data flow. +- Responsibilities of each component (e.g. Gateway, services, auth provider). +- API and contract changes (endpoints, request/response shapes, error handling). +- Configuration and operational considerations. + +Diagrams are welcome but optional. + +## 6. Alternatives considered + +List alternative approaches that were considered and briefly explain why they were not chosen. +This helps future readers understand trade-offs and avoid rehashing old discussions. + +## 7. Security, privacy, and compliance + +Explain the impact on: + +- Authentication and authorization behavior. +- Data confidentiality, integrity, and availability. +- Regulatory or standards alignment (e.g. healthcare-specific concerns if applicable). + +Call out new risks and how they are mitigated. + +## 8. Migration and rollout plan + +- How will this be rolled out (flags, gradual rollout, big-bang)? +- How will existing deployments migrate, if applicable? +- How will rollback work if something goes wrong? + +## 9. Testing and observability + +- What tests are required (unit, integration, e2e)? +- Any new metrics, logs, or traces needed to operate this change? + +## 10. Open questions + +List any open questions that need to be answered before accepting the RFC, or things to be resolved during implementation. diff --git a/mkdocs.yml b/mkdocs.yml index 00d9ebc0..7737e7c2 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -78,8 +78,6 @@ nav: - api/fhir_helpers.md - Community: - community/index.md - - Contribution Guide: community/contribution_guide.md - - Resources: community/resources.md copyright: dotimplement theme: