Skip to content
intu.dev

Getting Started

What is intu?

Section titled “What is intu?”

intu is a Git-native healthcare interoperability framework. It provides a Go-based CLI that combines YAML configuration with TypeScript transformers to build, validate, and manage healthcare integration channels.

Projects are plain directories tracked in Git, making collaboration, code review, and version control natural parts of your integration workflow. intu is AI-friendly by design — structured schemas and declarative config make it straightforward for AI assistants to generate and modify pipelines.

Install

Section titled “Install”
Terminal window
npm install -g intu-dev

Quick Start

Section titled “Quick Start”

Scaffold a new project and start running in two commands:

1. Create a new project

Section titled “1. Create a new project”
Terminal window
intu init my-project

intu init scaffolds the project and runs npm install automatically.

2. Start the engine

Section titled “2. Start the engine”
Terminal window
cd my-project
npm run dev

intu serve auto-compiles TypeScript before starting. No separate build step is needed.

3. Add a channel (optional)

Section titled “3. Add a channel (optional)”
Terminal window
intu c my-channel

4. Validate configuration (optional)

Section titled “4. Validate configuration (optional)”
Terminal window
intu validate

Project Structure

Section titled “Project Structure”

After running intu init, your project directory looks like this:

my-project/
├── intu.yaml              # Root config + named destinations
├── intu.dev.yaml          # Dev profile overrides
├── intu.prod.yaml         # Production profile
├── .env                   # Environment variables
├── package.json           # npm scripts + dependencies
├── tsconfig.json          # TypeScript compiler config
├── src/
│   ├── types/
│   │   └── intu.d.ts      # IntuMessage & IntuContext type declarations
│   └── channels/
│       ├── http-to-file/  # JSON pass-through channel
│       │   ├── channel.yaml
│       │   ├── transformer.ts
│       │   └── validator.ts
│       └── fhir-to-adt/   # FHIR Patient → HL7 ADT channel
│           ├── channel.yaml
│           ├── transformer.ts
│           └── validator.ts
├── Dockerfile
├── docker-compose.yml
└── README.md
File / DirectoryPurpose
intu.yamlRoot configuration — runtime settings, destinations, and global options
intu.dev.yaml / intu.prod.yamlProfile-specific overrides layered on top of the base config
.envEnvironment variables referenced by ${VAR} in YAML files
package.jsonnpm scripts (dev, serve, start, build) and dependencies
tsconfig.jsonTypeScript compiler configuration
src/types/TypeScript type declarations — intu.d.ts (IntuMessage, IntuContext)
src/channels/Channel directories (any nesting depth), each containing its own YAML config and TypeScript files

Core Concepts

Section titled “Core Concepts”

Channels — A channel is a complete processing pipeline that receives messages from a source, transforms and validates them, then delivers them to one or more destinations. Each channel lives in its own directory under src/channels/, and channels can be organized in subdirectories at any depth.

Sources / Listeners — Sources define where messages originate. intu supports HTTP, TCP/MLLP, Kafka, file, database, SFTP, DICOM, FHIR, and more. Each channel has exactly one source configured in its channel.yaml.

Transformers — Transformers are TypeScript functions that manipulate messages as they flow through a channel. They are auto-compiled when the engine starts.

Validators — Validators are TypeScript functions that check whether a message conforms to expected schemas or business rules before it reaches its destination.

Destinations — Destinations define where processed messages are delivered. Named destinations are declared at the root level in intu.yaml and referenced by channels. Supported types include Kafka, HTTP, TCP, file, database, SFTP, SMTP, DICOM, FHIR, and more.

Profiles — Profiles provide environment-specific configuration layering. The base intu.yaml is merged with a profile file such as intu.dev.yaml or intu.prod.yaml, allowing you to vary settings per environment without duplicating configuration.

Runtime Features

Section titled “Runtime Features”

Hot Reload — Edit channel.yaml or .ts files and the affected channel restarts automatically. TypeScript is recompiled on the fly — no manual rebuild needed.

Retry & Dead-Letter Queue — Configurable retry policies (fixed, linear, exponential backoff) per destination. Messages that exhaust retries are routed to a dead-letter queue for later inspection.

Metrics & Alerting — Track message counts (received, processed, filtered, errored) and latency per channel. Configure alerts on error count or queue depth thresholds.

Message Storage — Persist messages at each pipeline stage (received, transformed, sent, error) for audit, debugging, and replay. Browse stored messages with intu message list.

Map Variables — Share data across pipeline stages using globalMap, channelMap, responseMap, and connectorMap — available in every transformer and filter context.

Batch Processing — Split inbound messages using HL7 batch, FHIR bundle, newline, or XML root splitters. Each sub-message is processed independently through the pipeline.

Code Template Libraries — Define shared TypeScript functions in code_templates directories and reference them across channels for consistent reuse of mapping logic.

Next Steps

Section titled “Next Steps”