Configuration

Overview

Every intu project is configured through YAML files at the project root and inside channel directories. The root intu.yaml defines runtime behaviour, destinations, storage, logging, and metrics. Each channel has its own channel.yaml that describes a single integration pipeline.

my-project/
├── intu.yaml              # root config (base profile)
├── intu.dev.yaml          # dev overrides
├── intu.prod.yaml         # production overrides
└── channels/
    └── adt-to-fhir/
        └── channel.yaml   # channel config

Profile Layering

intu supports profile-based configuration layering. At startup the engine loads files in order and deep-merges them:

1. intu.yaml — base configuration (always loaded)
2. intu.<profile>.yaml — profile overlay (e.g. intu.dev.yaml, intu.prod.yaml)

The active profile is set with the --profile flag or the INTU_PROFILE environment variable:

intu serve --profile prod
# or
INTU_PROFILE=prod intu serve

Keys in the profile file override the same keys in the base file. Nested maps are merged recursively; arrays are replaced entirely.

Tip

Keep secrets and environment-specific values (ports, hostnames, credentials) in profile files and commit only intu.yaml with safe defaults. Add intu.prod.yaml to .gitignore if it contains sensitive data.

Environment Variable Expansion

Any value in YAML can reference an environment variable with ${VAR} syntax. An optional default is supported with ${VAR:-default}:

destinations:
  epic:
    type: http
    url: ${EPIC_BASE_URL:-https://sandbox.epic.com/api}
    auth:
      client_secret: ${EPIC_CLIENT_SECRET}

Variables are resolved at startup. A missing variable with no default causes a fatal error.

Caution

Never hard-code credentials in YAML. Always use ${VAR} references so secrets can be injected through your deployment environment, CI pipeline, or a secrets manager.

Root Configuration — intu.yaml

Runtime Settings

runtime:
  mode: standalone        # standalone | cluster
  workers: 4              # concurrent pipeline workers
  hot_reload: true        # watch for config/code changes

Key	Type	Default	Description
mode	standalone | cluster	standalone	Single-process or distributed mode
workers	integer	CPU count	Number of concurrent workers per channel
hot_reload	boolean	true	Restart affected channels on file change

Destinations

Destinations are declared at the root level and referenced by name in channel configs:

destinations:
  epic_fhir:
    type: http
    http:
      url: https://fhir.epic.com/R4
      auth:
        type: oauth2
        token_url: https://fhir.epic.com/oauth2/token
        client_id: ${EPIC_CLIENT_ID}
        client_secret: ${EPIC_CLIENT_SECRET}
        scopes:
          - system/*.read
          - system/*.write

  warehouse:
    type: database
    database:
      driver: postgres
      dsn: postgres://${PG_USER}:${PG_PASSWORD}@${PG_HOST:-localhost}:5432/integration_db?sslmode=require
      statement: "INSERT INTO messages (channel_id, payload) VALUES ($1, $2)"

  archive:
    type: file
    file:
      directory: /data/archive/hl7
      filename_pattern: "{{channelId}}_{{messageId}}.hl7"

Each destination has a type and type-specific settings. Supported types include http, tcp, kafka, file, database, sftp, smtp, channel, dicom, jms, fhir, and direct. Use type: database with driver: postgres (or mysql, mssql) for database destinations.

Message Storage

message_storage:
  driver: postgres         # memory | postgres | mysql | mssql | sqlite | s3
  mode: full               # none | status | full
  postgres:
    dsn: postgres://${PG_USER}:${PG_PASSWORD}@${PG_HOST:-localhost}:5432/intu_messages

Mode	Stored Data
none	Nothing — fire-and-forget
status	Message ID, status, timestamps, error info
full	Everything in status plus the complete message body

Note

memory storage is useful for development and testing but is not persisted across restarts. Use postgres or s3 for production workloads.

Logging

logging:
  level: info              # debug | info | warn | error
  format: json             # json | text
  transports:
    - type: console
    - type: file
      path: ./logs/intu.log
      max_size_mb: 100
      max_backups: 5
    - type: cloudwatch
      log_group: /intu/prod
      region: us-east-1
    - type: datadog
      api_key: ${DD_API_KEY}
      site: datadoghq.com
    - type: sumologic
      endpoint: ${SUMO_ENDPOINT}
    - type: elasticsearch
      url: ${ES_URL}
      index: intu-logs

Multiple transports can run simultaneously. Each transport inherits the root level unless overridden.

Metrics

metrics:
  prometheus:
    enabled: true
    port: 9090
    path: /metrics
  opentelemetry:
    enabled: true
    endpoint: ${OTEL_ENDPOINT}
    protocol: grpc          # grpc | http
    service_name: intu

Channel Configuration — channel.yaml

Each channel directory contains a channel.yaml that defines a single pipeline:

id: adt-to-fhir
enabled: true
group: admissions

listener:
  type: tcp
  tcp:
    port: 6661
    mode: mllp

validator:
  entrypoint: validator.ts

transformer:
  entrypoint: transformer.ts

destinations:
  - epic_fhir
  - warehouse

tags:
  - admissions
  - high-priority

Key	Required	Description
id	yes	Unique channel identifier
enabled	no	true (default) or false to disable without deleting
listener	yes	Inbound connector: type plus a type-specific block (e.g. tcp.port, http.port)
validator	no	Object with entrypoint pointing to a TypeScript validator file
transformer	no	Object with entrypoint pointing to a TypeScript transformer file
destinations	yes	List of destination names declared in intu.yaml
tags	no	Array of tags for filtering and grouping
group	no	Logical channel group for batch operations

Retry is configured per destination in intu.yaml or inline in the channel; channel-level error handling uses error_handling (e.g. dlq, on_error).

Full Example — intu.yaml

runtime:
  mode: standalone
  workers: 4
  hot_reload: true

message_storage:
  driver: memory
  mode: status

logging:
  level: info
  format: json
  transports:
    - type: console

metrics:
  prometheus:
    enabled: true
    port: 9090
    path: /metrics

destinations:
  epic_fhir:
    type: http
    url: ${EPIC_FHIR_URL:-https://sandbox.epic.com/R4}
    auth:
      type: oauth2_client_credentials
      token_url: ${EPIC_TOKEN_URL}
      client_id: ${EPIC_CLIENT_ID}
      client_secret: ${EPIC_CLIENT_SECRET}

  local_file:
    type: file
    path: ./output/
    naming: "{{.ChannelID}}_{{.Timestamp}}.json"

Full Example — intu.prod.yaml

runtime:
  mode: cluster
  workers: 8
  hot_reload: false

message_storage:
  driver: postgres
  mode: full
  postgres:
    dsn: postgres://${PG_USER}:${PG_PASSWORD}@${PG_HOST}:5432/intu_prod?sslmode=require

logging:
  level: warn
  format: json
  transports:
    - type: console
    - type: datadog
      api_key: ${DD_API_KEY}
      site: datadoghq.com

metrics:
  prometheus:
    enabled: true
    port: 9090
    path: /metrics
  opentelemetry:
    enabled: true
    endpoint: ${OTEL_ENDPOINT}
    protocol: grpc
    service_name: intu-prod

destinations:
  epic_fhir:
    type: http
    url: ${EPIC_FHIR_URL}
    auth:
      type: oauth2_client_credentials
      token_url: ${EPIC_TOKEN_URL}
      client_id: ${EPIC_CLIENT_ID}
      client_secret: ${EPIC_CLIENT_SECRET}
      scopes:
        - system/*.read
        - system/*.write

Profile Layering in Practice

Given the two files above and --profile prod, the merged result at startup is:

Key	Base (intu.yaml)	Prod Override	Effective Value
runtime.mode	standalone	cluster	cluster
runtime.workers	4	8	8
runtime.hot_reload	true	false	false
message_storage.driver	memory	postgres	postgres
message_storage.mode	status	full	full
logging.level	info	warn	warn
metrics.prometheus	enabled	enabled	enabled (merged)
metrics.opentelemetry	—	enabled	enabled (added)

Tip

Use intu serve --profile prod to run with the merged configuration. Run intu validate to check YAML and schemas before starting.