dotimplement · jenniferjiangkells · Aug 4, 2025 · Jul 31, 2025 · Jul 31, 2025 · Jul 31, 2025
diff --git a/README.md b/README.md
@@ -38,7 +38,7 @@ First time here? Check out our [Docs](https://dotimplement.github.io/HealthChain
 
 ## HealthChainAPI
 
-The HealthChainAPI provides a secure, asynchronous integration layer that coordinates multiple healthcare systems in a single application.
+The HealthChainAPI provides a secure integration layer that coordinates multiple healthcare systems in a single application.
 
 ### Multi-Protocol Support
 
@@ -217,9 +217,9 @@ response = adapter.format(doc)
 The InteropEngine is a template-based system that allows you to convert between FHIR, CDA, and HL7v2.
 
 ```python
-from healthchain.interop import create_engine, FormatType
+from healthchain.interop import create_interop, FormatType
 
-engine = create_engine()
+engine = create_interop()
 
 with open("tests/data/test_cda.xml", "r") as f:
     cda_data = f.read()

diff --git a/dev-templates/README.md b/dev-templates/README.md
@@ -0,0 +1,36 @@
+# Developer Templates
+
+This directory contains **work-in-progress templates** for HealthChain developers.
+
+## Purpose
+
+- 🔧 **Development workspace** for new templates
+- ⚠️ **Experimental features** not ready for bundling
+- 🧪 **Testing ground** before promoting to `healthchain/configs/`
+
+## Workflow
+
+1. **Develop here** - Create/fix templates in subdirectories
+2. **Test thoroughly** - Use integration tests and real data
+3. **Promote when stable** - Move to `healthchain/configs/` for bundling
+4. **Update docs** - Move from "experimental" to "stable" in docs
+
+## Current Templates
+
+- `allergies/` - Allergy templates with known bugs (see README)
+
+## Guidelines
+
+- Each template type gets its own subdirectory
+- Include README with known issues and usage
+- Test with example CDAs in `resources/`
+- Follow existing template patterns
+
+## Not for End Users
+
+End users should use:
+```bash
+healthchain init-configs my_configs  # Gets stable bundled templates
+```
+
+This directory is for **HealthChain contributors only**.
diff --git a/dev-templates/allergies/README.md b/dev-templates/allergies/README.md
@@ -0,0 +1,48 @@
+# Experimental Allergy Templates
+
+⚠️ **Warning: These templates are experimental and contain known bugs.**
+
+This directory contains allergy-related configuration and templates that were removed from the default bundled configs due to reliability issues.
+
+📖 **For full documentation on experimental templates, see:** [docs/reference/interop/experimental.md](../docs/reference/interop/experimental.md)
+
+## Contents
+
+- `allergies.yaml` - Section configuration for allergy processing
+- `allergy_entry.liquid` - Template for converting FHIR AllergyIntolerance to CDA
+- `allergy_intolerance.liquid` - Template for converting CDA allergies to FHIR
+
+## Known Issues
+
+- Clinical status parsing has bugs (see integration test comments)
+- Round-trip conversion may not preserve all data correctly
+- Template logic is fragile and may fail with edge cases
+
+## Usage
+
+If you need allergy support despite the bugs:
+
+1. Copy these files to your custom config directory:
+   ```bash
+   # After running: healthchain init-configs my_configs
+   cp cookbook/experimental_templates/allergies/* my_configs/interop/cda/sections/
+   cp cookbook/experimental_templates/allergies/allergy_*.liquid my_configs/templates/cda_fhir/
+   cp cookbook/experimental_templates/allergies/allergy_*.liquid my_configs/templates/fhir_cda/
+   ```
+
+2. Add "allergies" to your CCD document config:
+   ```yaml
+   # my_configs/interop/cda/document/ccd.yaml
+   body:
+     include_sections:
+       - "allergies"  # Add this
+       - "medications"
+       - "problems"
+       - "notes"
+   ```
+
+3. Test thoroughly with your specific data before using in production.
+
+## Contributing
+
+If you fix the bugs in these templates, please consider contributing back to the main project!
diff --git a/configs/interop/cda/sections/allergies.yaml → dev-templates/allergies/allergies.yaml b/configs/interop/cda/sections/allergies.yaml → dev-templates/allergies/allergies.yaml
diff --git a/...s/templates/fhir_cda/allergy_entry.liquid → dev-templates/allergies/allergy_entry.liquid b/...s/templates/fhir_cda/allergy_entry.liquid → dev-templates/allergies/allergy_entry.liquid
diff --git a/...lates/cda_fhir/allergy_intolerance.liquid → ...ates/allergies/allergy_intolerance.liquid b/...lates/cda_fhir/allergy_intolerance.liquid → ...ates/allergies/allergy_intolerance.liquid
diff --git a/docs/api/interop.md b/docs/api/interop.md
@@ -1,15 +1,9 @@
 # Interoperability Engine
 
 ::: healthchain.interop.engine
-
 ::: healthchain.interop.config_manager
-
 ::: healthchain.interop.template_registry
-
 ::: healthchain.interop.parsers.cda
-
 ::: healthchain.interop.generators.cda
-
 ::: healthchain.interop.generators.fhir
-
 ::: healthchain.config.validators
diff --git a/docs/cookbook/interop/basic_conversion.md b/docs/cookbook/interop/basic_conversion.md
@@ -13,12 +13,12 @@ This tutorial demonstrates how to use the HealthChain interoperability module to
 First, let's import the required modules and create an interoperability engine:
 
 ```python
-from healthchain.interop import create_engine, FormatType
+from healthchain.interop import create_interop, FormatType
 from pathlib import Path
 import json
 
 # Create an engine
-engine = create_engine()
+engine = create_interop()
 ```
 
 ## Converting CDA to FHIR

diff --git a/docs/index.md b/docs/index.md
@@ -1,6 +1,6 @@
 # Welcome to HealthChain 💫 🏥
 
-HealthChain is an open-source Python framework for building real-time AI applications in a healthcare context.
+HealthChain is an open-source Python framework that makes it easier to connect your AI/ML pipelines to healthcare systems.
 
 [ :fontawesome-brands-discord: Join our Discord](https://discord.gg/UQC6uAepUz){ .md-button .md-button--primary }
 &nbsp;&nbsp;&nbsp;&nbsp;

diff --git a/docs/quickstart.md b/docs/quickstart.md
@@ -154,11 +154,15 @@ The HealthChain Interoperability module provides tools for converting between di
 
 [(Full Documentation on Interoperability Engine)](./reference/interop/interop.md)
 
+
+**Choose your setup based on your needs:**
+
+✅ **Default configs** - For basic testing and prototyping only:
 ```python
-from healthchain.interop import create_engine, FormatType
+from healthchain.interop import create_interop, FormatType
 
-# Create an interoperability engine
-engine = create_engine()
+# Uses bundled configs - basic CDA ↔ FHIR conversion
+engine = create_interop()
 
 # Load a CDA document
 with open("tests/data/test_cda.xml", "r") as f:
@@ -171,16 +175,31 @@ fhir_resources = engine.to_fhir(cda_xml, src_format=FormatType.CDA)
 cda_document = engine.from_fhir(fhir_resources, dest_format=FormatType.CDA)
 ```
 
-The interop module provides a flexible, template-based approach to healthcare format conversion:
+> ⚠️ **Default configs are limited** - Only supports problems, medications, and notes. No allergies, custom mappings, or organization-specific templates.
+
+🛠️ **Custom configs** - **Required for real-world use**:
+```bash
+# Create editable configuration templates
+healthchain init-configs ./my_configs
+```
 
-| Feature | Description |
-|---------|-------------|
-| Format conversion | Convert legacy formats (CDA, HL7v2) to FHIR resources and back |
-| Template-based generation | Customize syntactic output using [Liquid](https://shopify.github.io/liquid/) templates |
-| Configuration | Configure terminology mappings, validation rules, and environments |
-| Extension | Register custom parsers, generators, and validators |
+```python
+# Use your customized configs
+engine = create_interop(config_dir="./my_configs")
+
+# Now you can customize:
+# • Add experimental features (allergies, procedures)
+# • Modify terminology mappings (SNOMED, LOINC codes)
+# • Customize templates for your organization's CDA format
+# • Configure validation rules and environments
+```
 
-For more details, see the [conversion examples](cookbook/interop/basic_conversion.md).
+**When you need custom configs:**
+- 🏥 **Production healthcare applications**
+- 🔧 **Organization-specific CDA templates**
+- 🧪 **Experimental features** (allergies, procedures)
+- 🗺️ **Custom terminology mappings**
+- 🛡️ **Specific validation requirements**
 
 
 ## Utilities ⚙️
@@ -189,7 +208,7 @@ For more details, see the [conversion examples](cookbook/interop/basic_conversio
 
 Test your AI applications in realistic healthcare contexts with sandbox environments for CDS Hooks and clinical documentation workflows.
 
-[(Full Documentation on Sandbox)](./reference/sandbox/sandbox.md)
+[(Full Documentation on Sandbox)](./reference/utilities/sandbox.md)
 
 ```python
 import healthchain as hc

diff --git a/docs/reference/index.md b/docs/reference/index.md
@@ -4,6 +4,6 @@
 
 - [Gateway](gateway/gateway.md): Connect to multiple healthcare systems and services.
 - [Pipeline](pipeline/pipeline.md): Build and manage processing pipelines for healthcare NLP and ML tasks.
-- [Sandbox](sandbox/sandbox.md): Test your pipelines in a simulated healthcare environment.
+- [Sandbox](utilities/sandbox.md): Test your pipelines in a simulated healthcare environment.
 - [Interoperability](interop/interop.md): Convert between healthcare data formats like FHIR, CDA, and HL7v2.
 - [Utilities](utilities/fhir_helpers.md): Additional tools for development and testing.