Metadata-Version: 2.4
Name: healthcare-sdk
Version: 0.1.0
Summary: Healthcare interoperability framework SDK
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: fastapi>=0.100.0
Requires-Dist: uvicorn>=0.23.0
Requires-Dist: psycopg2>=2.9.0

# HealthCare Interoperability framework

Small SDK project to host interoperability services and adapters.

## Folder Architecture

```text
documentation/
└─ frameworkClassDiagram.png
src/
└─ healthcare_sdk/
   ├─ app.py
   ├─ __init__.py
   ├─ transportLayer/
   │  ├─ adapter.py
   │  ├─ restController.py
   │  └─ __init__.py
   ├─ repositories/
   │  ├─ postgreSqlStorage.py
   │  ├─ storage.py
   │  └─ __init__.py
   ├─ usecases/
   │  ├─ healthCareUsecase.py
   │  └─ __init__.py
   └─ tools/
      ├─ aiHelper.py
      ├─ decoder.py
      ├─ normalizer.py
      ├─ validator.py
      └─ __init__.py
```

## Proposed Class Diagram

![Framework class diagram](documentation/frameworkClassDiagram.png)

Folder responsibilities:

- transportLayer/: Transport adapters and server launchers (e.g., REST, HL7 over MLLP). 
- repositories/: Database providers and external data sources used by implementations.
- usecases/: Application use cases and orchestration logic.
- tools/: Shared helpers for decoding, validation, and normalization.

## Setup (uv)

```powershell
uv venv
uv add fastapi uvicorn
```

## Run

```powershell
$env:PYTHONPATH = "src"
python -m healthcare_sdk.app
```

Then open: http://127.0.0.1:8000/health

## Install

```powershell
pip install -e .
```

## SDK Entry Point

The framework provides a registration helper to import arrays of components that
implement the SDK Protocols.

```python
from healthcare_sdk import register_components

components = register_components(
    adapters=[...],
    usecases=[...],
    validators=[...],
    decoders=[...],
    normalizers=[...],
    aihelpers=[...],
    storages=[...],
)
```

## SDK Contracts

This document defines the generic envelope and component contracts for the SDK framework.

### Envelope

The framework standardizes a generic envelope that can carry HL7v2, FHIR, or other protocols.

```text
MessageEnvelope
  id: str
  protocol: str
  message_type: str
  raw_payload: str | bytes
  decoded_payload: dict | None
  normalized_payload: dict | None
  metadata: dict
  errors: list[ErrorDetail]
  status: str
```

#### Status values

- received
- decoded
- validated
- normalized
- stored
- error

### Types

```text
RawMessage
  id: str
  protocol: str
  raw_payload: str | bytes
  metadata: dict
  message_type: str | None

ErrorDetail
  code: str
  message: str
  stage: str
  context: dict | None

ValidationResult
  is_valid: bool
  errors: list[ErrorDetail]
```

### Component contracts

```text
Adapter
  executeServer(port=8000)
  receive() -> RawMessage

Decoder
  decode(raw_message: RawMessage) -> DecodedPayload

Validator
  validate(decoded_payload: DecodedPayload) -> ValidationResult

Normalizer
  normalizeData(decoded_payload: DecodedPayload) -> NormalizedPayload

Usecase
  execute(raw_message: RawMessage) -> MessageEnvelope

Storage
  save(envelope: MessageEnvelope) -> str
  connection() -> Any
  read(query: dict) -> dict
  delete(query: dict) -> bool
  update(query: dict, data: dict) -> bool
```

### Errors

```text
SdkError
  code: str
  message: str
  stage: str
  context: dict

DecodeError
ValidationError
NormalizationError
StorageError
```

## Hl7 v2 examples

ALl the examples were taken of this repository
```
https://github.com/Work-In-Progress-For-Health/hl7-v2-examples
```
## TO DO

- Definir tipo de entidades a se armazenar
- ORM?
- setup postgreSql to test
