Contributing

Prerequisites

Tool	Version
Go	1.25+
Node.js	18+
npm	(bundled)

Build from Source

git clone https://github.com/intuware/intu-dev.git
cd intu-dev
go build -o intu .

Common Commands

Task	Command
Build binary	`go build -o intu .`
Run tests	`go test ./... -v`
Lint	`go vet ./...`
Run from source	`go run . <command>`
Tidy deps	`go mod tidy`

End-to-End Demo

Walk through the full workflow from scaffolding a project to running a channel:

# Build the CLI
go build -o intu .

# Scaffold a new project
./intu init my-project
cd my-project

# Create a channel
./intu channel create adt-feed

# Validate configuration
./intu validate

# Start the engine
./intu serve

Project Structure

Package	Description
`cmd/`	Cobra CLI commands
`internal/runtime/`	Engine, channel lifecycle, pipeline, Node.js runner, hot-reload
`internal/dashboard/`	Web dashboard server and embedded SPA
`internal/storage/`	Message stores: memory, postgres, s3, composite
`internal/connector/`	Source connectors and destinations
`internal/bootstrap/`	Project and channel scaffolding templates
`internal/auth/`	OIDC, LDAP, basic auth, RBAC, audit
`internal/cluster/`	Redis coordinator, deduplication, health checks
`internal/retry/`	Retry queues, dead-letter queue
`internal/observability/`	Prometheus, OpenTelemetry metrics
`internal/datatype/`	HL7v2, FHIR, X12, CCDA, JSON, XML, CSV, binary parsers
`pkg/config/`	YAML config loading, validation
`pkg/logging/`	Structured logging, transports
`npm/`	npm package (ships prebuilt binary)
`docs/`	HTML documentation, JSON schemas

Tests

All tests are pure Go — no Docker, no running databases, no network calls.

Package	Test File(s)	Focus
`internal/runtime`	`engine_test.go`, `pipeline_test.go`	Channel lifecycle, pipeline execution
`internal/storage`	`memory_test.go`, `composite_test.go`	In-memory store, composite routing
`internal/connector`	`source_test.go`, `dest_test.go`	Connector start/stop, message delivery
`internal/auth`	`rbac_test.go`, `oidc_test.go`	Role checks, token validation
`internal/retry`	`retry_test.go`, `dlq_test.go`	Retry scheduling, dead-letter routing
`internal/datatype`	`hl7_test.go`, `fhir_test.go`	Parse/serialize healthcare data formats
`internal/cluster`	`coordinator_test.go`	Leader election, deduplication
`internal/bootstrap`	`scaffold_test.go`	Template rendering, directory structure
`pkg/config`	`config_test.go`, `validate_test.go`	YAML loading, schema validation
`pkg/logging`	`logging_test.go`	Structured output, transport switching

# Run the full suite
go test ./... -v

# Run a specific package
go test ./internal/runtime/... -v

# Run with race detector
go test -race ./...

Architecture Notes

Node.js worker pool — Transformer scripts run in a managed pool of Node.js child processes. The pool size is configurable and workers are recycled after a set number of invocations.
fsnotify hot-reload — The engine watches project files and restarts affected channels on change, without dropping in-flight messages.
Shared HTTP listeners — Multiple channels can bind to the same port. The engine multiplexes requests by path to the correct channel pipeline.
Scaffolding templates — intu init and intu channel create use Go text/template files embedded in the binary to generate project and channel boilerplate.

How to Contribute

Report bugs or request features — Open an issue on GitHub Issues.
Submit a pull request — Fork the repo, create a branch, and open a PR against main. Include tests for new functionality.
Join the discussion — Ask questions or share ideas in GitHub Discussions.

Maintainer contact: ramnish@intuware.com