From 39c1d3a7c51e84ad4ad92465559d4f8ad0e734cd Mon Sep 17 00:00:00 2001 From: jenniferjiangkells Date: Fri, 28 Nov 2025 15:07:43 +0000 Subject: [PATCH 1/5] Add CLAUDE.md --- .gitignore | 4 ++ CLAUDE.MD | 193 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 197 insertions(+) create mode 100644 CLAUDE.MD diff --git a/.gitignore b/.gitignore index 7e413875..8709beb5 100644 --- a/.gitignore +++ b/.gitignore @@ -160,6 +160,7 @@ cython_debug/ #.idea/ output/ +models/ scrap/ .DS_Store .vscode/ @@ -168,3 +169,6 @@ scrap/ .cursor/ .private/ .idea/ + +# Personal AI context (keep local) +CLAUDE.LOCAL.MD diff --git a/CLAUDE.MD b/CLAUDE.MD new file mode 100644 index 00000000..1f199cfb --- /dev/null +++ b/CLAUDE.MD @@ -0,0 +1,193 @@ +# HealthChain - Claude Code Context + +## Project Overview + +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. + +**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. + +**Target Users**: +- HealthTech engineers building clinical workflow integrations +- LLM/GenAI developers aggregating multi-EHR data +- ML researchers deploying models as healthcare APIs + +## Architecture & Structure + +``` +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 +``` + +## 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 From 4dd1b5259f7618c962e1b3a2e7128b05c7a89431 Mon Sep 17 00:00:00 2001 From: jenniferjiangkells Date: Fri, 28 Nov 2025 15:11:17 +0000 Subject: [PATCH 2/5] Add badge --- README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/README.md b/README.md index 9ef165b1..7b5238b0 100644 --- a/README.md +++ b/README.md @@ -15,6 +15,7 @@ [![Substack][substack-badge]][substack] [![Discord][discord-badge]][discord] +![AI-Assisted Development][ai-badge] @@ -242,6 +243,7 @@ This project builds on [fhir.resources](https://github.com/nazrulworld/fhir.reso [build-badge]: https://img.shields.io/github/actions/workflow/status/dotimplement/healthchain/ci.yml?branch=main&style=flat-square&color=%2379a8a9 [discord-badge]: https://img.shields.io/badge/chat-%235965f2?style=flat-square&logo=discord&logoColor=white [substack-badge]: https://img.shields.io/badge/Cool_Things_In_HealthTech-%23c094ff?style=flat-square&logo=substack&logoColor=white +[ai-badge]: https://img.shields.io/badge/AI--Assisted_Development_Friendly-CLAUDE.MD-%23FF6B6B?style=flat-square&logo=anthropic&logoColor=white [pypi]: https://pypi.org/project/healthchain/ [pypistats]: https://pepy.tech/project/healthchain From b7544ade8503f1b57763df889c599779b7c834ef Mon Sep 17 00:00:00 2001 From: jenniferjiangkells Date: Fri, 28 Nov 2025 15:18:24 +0000 Subject: [PATCH 3/5] Badge style adjustments --- README.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 7b5238b0..b3e0ecea 100644 --- a/README.md +++ b/README.md @@ -15,7 +15,8 @@ [![Substack][substack-badge]][substack] [![Discord][discord-badge]][discord] -![AI-Assisted Development][ai-badge] + +[![AI-Assisted Development][ai-badge]][claude-md] @@ -243,7 +244,7 @@ This project builds on [fhir.resources](https://github.com/nazrulworld/fhir.reso [build-badge]: https://img.shields.io/github/actions/workflow/status/dotimplement/healthchain/ci.yml?branch=main&style=flat-square&color=%2379a8a9 [discord-badge]: https://img.shields.io/badge/chat-%235965f2?style=flat-square&logo=discord&logoColor=white [substack-badge]: https://img.shields.io/badge/Cool_Things_In_HealthTech-%23c094ff?style=flat-square&logo=substack&logoColor=white -[ai-badge]: https://img.shields.io/badge/AI--Assisted_Development_Friendly-CLAUDE.MD-%23FF6B6B?style=flat-square&logo=anthropic&logoColor=white +[ai-badge]: https://img.shields.io/badge/AI--Assisted_Development_Friendly-CLAUDE.MD-%23e59875?style=flat-square&logo=anthropic&logoColor=white [pypi]: https://pypi.org/project/healthchain/ [pypistats]: https://pepy.tech/project/healthchain @@ -252,3 +253,4 @@ This project builds on [fhir.resources](https://github.com/nazrulworld/fhir.reso [build]: https://github.com/dotimplement/HealthChain/actions?query=branch%3Amain [discord]: https://discord.gg/UQC6uAepUz [substack]: https://jenniferjiangkells.substack.com/ +[claude-md]: CLAUDE.MD From 44e7c061e41e30e442e9892b04beb369fdee014e Mon Sep 17 00:00:00 2001 From: jenniferjiangkells Date: Fri, 28 Nov 2025 15:23:50 +0000 Subject: [PATCH 4/5] style --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index b3e0ecea..33063d58 100644 --- a/README.md +++ b/README.md @@ -244,7 +244,7 @@ This project builds on [fhir.resources](https://github.com/nazrulworld/fhir.reso [build-badge]: https://img.shields.io/github/actions/workflow/status/dotimplement/healthchain/ci.yml?branch=main&style=flat-square&color=%2379a8a9 [discord-badge]: https://img.shields.io/badge/chat-%235965f2?style=flat-square&logo=discord&logoColor=white [substack-badge]: https://img.shields.io/badge/Cool_Things_In_HealthTech-%23c094ff?style=flat-square&logo=substack&logoColor=white -[ai-badge]: https://img.shields.io/badge/AI--Assisted_Development_Friendly-CLAUDE.MD-%23e59875?style=flat-square&logo=anthropic&logoColor=white +[ai-badge]: https://img.shields.io/badge/AI--dev_friendly-CLAUDE.MD-%23e59875?style=flat-square&logo=anthropic&logoColor=white [pypi]: https://pypi.org/project/healthchain/ [pypistats]: https://pepy.tech/project/healthchain From acd07528677ca44f0d6aa745d051a706b2a27ddd Mon Sep 17 00:00:00 2001 From: jenniferjiangkells Date: Fri, 28 Nov 2025 15:25:47 +0000 Subject: [PATCH 5/5] Fidgeting with positions --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 33063d58..f0c1730f 100644 --- a/README.md +++ b/README.md @@ -12,11 +12,11 @@ [![License][license-badge]][license] [![Python Versions][python-versions-badge]][pypi] [![Build Status][build-badge]][build] +[![AI-Assisted Development][ai-badge]][claude-md] [![Substack][substack-badge]][substack] [![Discord][discord-badge]][discord] -[![AI-Assisted Development][ai-badge]][claude-md]