Add OSS hygiene scaffolding

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,61 @@
+name: Bug report
+description: Report a defect, regression, or incorrect behavior
+title: "[Bug]: "
+labels:
+  - bug
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for filing a bug report. Please provide enough detail for someone
+        else to reproduce the issue locally.
+  - type: textarea
+    id: summary
+    attributes:
+      label: Summary
+      description: What happened, and why is it a bug?
+      placeholder: A short description of the problem.
+    validations:
+      required: true
+  - type: textarea
+    id: steps
+    attributes:
+      label: Steps to reproduce
+      description: List the exact steps needed to reproduce the issue.
+      placeholder: |
+        1. Run ...
+        2. Configure ...
+        3. Observe ...
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected behavior
+      placeholder: What should have happened instead?
+    validations:
+      required: true
+  - type: textarea
+    id: actual
+    attributes:
+      label: Actual behavior
+      placeholder: What happened instead?
+    validations:
+      required: true
+  - type: input
+    id: python
+    attributes:
+      label: Python version
+      placeholder: "3.12.2"
+  - type: input
+    id: environment
+    attributes:
+      label: Environment
+      description: OS, Databricks runtime, CI runner, or other relevant environment info
+      placeholder: macOS 15 / Ubuntu 24.04 / Databricks Runtime 14.3
+  - type: textarea
+    id: context
+    attributes:
+      label: Additional context
+      description: Relevant logs, screenshots, stack traces, or links
+      render: shell

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Security issue
+    url: https://github.com/slusset/databricks-ehr-integration-core/security/advisories/new
+    about: Please report security issues privately through GitHub Security Advisories.

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,52 @@
+name: Feature request
+description: Propose a new capability or improvement
+title: "[Feature]: "
+labels:
+  - enhancement
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Use this template for feature requests, product ideas, and workflow improvements.
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem statement
+      description: What user or operator problem are you trying to solve?
+      placeholder: Today it is difficult to ...
+    validations:
+      required: true
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed solution
+      description: Describe the feature or behavior you want.
+      placeholder: Add support for ...
+    validations:
+      required: true
+  - type: textarea
+    id: acceptance
+    attributes:
+      label: Acceptance criteria
+      description: What would make this feature complete?
+      placeholder: |
+        - [ ] ...
+        - [ ] ...
+  - type: dropdown
+    id: area
+    attributes:
+      label: Area
+      options:
+        - Core domain
+        - Epic adapter
+        - Cerner adapter
+        - Generic FHIR adapter
+        - Databricks pipelines
+        - Documentation
+        - CI/CD
+        - Other
+  - type: textarea
+    id: context
+    attributes:
+      label: Additional context
+      description: Links to prior art, specs, or related issues

.github/workflows/docs.yml

@@ -0,0 +1,71 @@
+name: Docs
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "docs/**"
+      - "mkdocs.yml"
+      - ".github/workflows/docs.yml"
+      - "README.md"
+      - "CONTRIBUTING.md"
+      - "CODE_OF_CONDUCT.md"
+      - "pyproject.toml"
+      - "uv.lock"
+  pull_request:
+    branches: [main]
+    paths:
+      - "docs/**"
+      - "mkdocs.yml"
+      - ".github/workflows/docs.yml"
+      - "README.md"
+      - "CONTRIBUTING.md"
+      - "CODE_OF_CONDUCT.md"
+      - "pyproject.toml"
+      - "uv.lock"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: docs-pages
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout source
+        uses: actions/checkout@v4
+
+      - name: Configure GitHub Pages
+        uses: actions/configure-pages@v5
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v6
+
+      - name: Sync docs dependencies
+        run: uv sync --locked --group docs
+
+      - name: Build site
+        run: uv run --group docs mkdocs build --strict
+
+      - name: Upload Pages artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: site/
+
+  deploy:
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -51,3 +51,4 @@ Thumbs.db
 htmlcov/
 .pytest_cache/
 .mypy_cache/
+site/

CODE_OF_CONDUCT.md

@@ -0,0 +1,58 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and maintainers pledge to make participation in the
+`ehr-writeback` community a harassment-free experience for everyone, regardless
+of age, body size, visible or invisible disability, ethnicity, sex
+characteristics, gender identity and expression, level of experience,
+education, socio-economic status, nationality, personal appearance, race,
+religion, or sexual identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment include:
+
+- Demonstrating empathy and kindness toward other people
+- Being respectful of differing opinions, viewpoints, and experiences
+- Giving and gracefully accepting constructive feedback
+- Taking responsibility for mistakes and learning from them
+- Focusing on what is best for the community and the project
+
+Examples of unacceptable behavior include:
+
+- The use of sexualized language or imagery, and sexual attention or advances
+- Trolling, insulting or derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information without explicit permission
+- Other conduct that could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Project maintainers are responsible for clarifying and enforcing our standards
+of acceptable behavior. They may take any action they deem appropriate and fair
+in response to behavior they consider inappropriate, threatening, offensive, or
+harmful.
+
+## Scope
+
+This Code of Conduct applies within all project spaces and in public spaces when
+an individual is officially representing the project or its community.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the project maintainers by opening a private security report or by
+contacting the repository owner through GitHub. All reports will be reviewed and
+investigated promptly and fairly.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1.
+
+[homepage]: https://www.contributor-covenant.org/version/2/1/code_of_conduct/

docs/architecture.md

@@ -0,0 +1,20 @@
+# Architecture
+
+The repository follows a hexagonal architecture:
+
+- `src/ehr_writeback/core/` contains the domain models, ports, and orchestration logic
+- `src/ehr_writeback/adapters/` contains EHR-specific adapter implementations
+- `src/ehr_writeback/infrastructure/` contains persistence and dead-letter support
+- `src/ehr_writeback/pipelines/` contains Databricks-oriented pipeline code
+
+## Design intent
+
+The core orchestrator coordinates:
+
+- idempotency checks before write-back
+- retry behavior for transient failures
+- circuit breaker behavior for unhealthy endpoints
+- dead-letter handling after retry exhaustion
+
+Adapters are responsible for translating the core model into each EHR's API
+shape without leaking adapter-specific behavior back into the domain layer.

docs/getting-started.md

@@ -0,0 +1,31 @@
+# Getting Started
+
+## Install from PyPI
+
+```bash
+pip install ehr-writeback
+```
+
+## Local development setup
+
+```bash
+git clone git@github.com:slusset/databricks-ehr-integration-core.git
+cd databricks-ehr-integration-core
+uv sync
+```
+
+## Run the standard checks
+
+```bash
+uv run pytest tests/unit -v --tb=short
+uv run ruff check src/ tests/
+uv run ruff format --check src/ tests/
+uv run mypy src/ehr_writeback/core/
+```
+
+## Build the docs site locally
+
+```bash
+uv sync --group docs
+uv run --group docs mkdocs serve
+```

docs/index.md

@@ -0,0 +1,21 @@
+# ehr-writeback
+
+`ehr-writeback` closes the loop from analytics outputs back into clinical
+workflow by writing observations into EHR systems through FHIR.
+
+## What it covers
+
+- Core write-back orchestration with idempotency, retries, and dead-lettering
+- Adapters for Epic, Cerner/Oracle Health, and generic FHIR R4 endpoints
+- Databricks-oriented pipeline support for operational deployments
+
+## Project goals
+
+- Keep business logic in the core domain layer
+- Isolate EHR-specific behavior inside adapters
+- Support production-safe write-back patterns such as retries and exactly-once semantics
+
+## Contributing
+
+See `CONTRIBUTING.md` for development setup, pull request expectations, and the
+local verification commands used in CI.

mkdocs.yml

@@ -0,0 +1,19 @@
+site_name: ehr-writeback
+site_description: Open-source EHR write-back integration framework for FHIR-based clinical workflows
+site_url: https://slusset.github.io/databricks-ehr-integration-core/
+repo_url: https://github.com/slusset/databricks-ehr-integration-core
+repo_name: slusset/databricks-ehr-integration-core
+theme:
+  name: material
+  features:
+    - navigation.sections
+    - navigation.expand
+    - content.code.copy
+nav:
+  - Overview: index.md
+  - Getting Started: getting-started.md
+  - Architecture: architecture.md
+markdown_extensions:
+  - admonition
+  - attr_list
+  - tables

pyproject.toml

@@ -38,9 +38,13 @@ dev = [
     "ruff>=0.3",
     "mypy>=1.9",
 ]
+docs = [
+    "mkdocs-material>=9.6",
+]
 
 [project.urls]
 Repository = "https://github.com/slusset/databricks-ehr-integration-core"
+Documentation = "https://slusset.github.io/databricks-ehr-integration-core/"
 
 [build-system]
 requires = ["hatchling"]