Skip to main content
fi-fhir docs

Prerequisites

Development Setup

This guide walks through setting up a development environment for fi-fhir.

Prerequisites

Required

Optional (for full development)

  • Docker: For integration tests
  • Node.js 18+: For TypeScript SDK development
  • PostgreSQL 14+: For event store development
  • golangci-lint: For linting

Quick Setup

# Clone repository
git clone https://gitlab.flexinfer.ai/libs/fi-fhir.git
cd fi-fhir

# Install dependencies and build
make dev-setup

# Verify setup
./bin/fi-fhir --version
make test

Detailed Setup

1. Install Go

# macOS
brew install go

# Linux
wget https://go.dev/dl/go1.21.0.linux-amd64.tar.gz
sudo tar -C /usr/local -xzf go1.21.0.linux-amd64.tar.gz
export PATH=$PATH:/usr/local/go/bin

# Verify
go version

2. Clone and Build

# Clone
git clone https://gitlab.flexinfer.ai/libs/fi-fhir.git
cd fi-fhir

# Build CLI
make build

# Run tests
make test

3. Install Development Tools

# golangci-lint
brew install golangci-lint
# or
go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest

# gofumpt (stricter gofmt)
go install mvdan.cc/gofumpt@latest

4. Set Up Git Hooks

make setup-hooks

This installs pre-commit hooks for:

  • Code formatting
  • Linting
  • Test execution

Project Structure

After cloning, you'll see:

fi-fhir/
├── bin/                  # Built binaries
├── cmd/fi-fhir/          # CLI source
├── internal/             # Private packages
├── pkg/                  # Public packages
├── testdata/             # Test fixtures
├── sdk/typescript/       # TypeScript SDK
├── ui/                   # SvelteKit UI
├── Makefile              # Build commands
├── go.mod                # Go dependencies
└── .golangci.yml         # Linter config

Makefile Targets

# Building
make build            # Build CLI
make docker-build     # Build Docker image

# Testing
make test             # Run unit tests
make test-v           # Verbose tests
make test-cover       # Coverage report
make test-e2e         # E2E tests
make test-integration # Integration tests (requires Docker)

# Code quality
make lint             # Run linter
make lint-fix         # Auto-fix lint issues
make fmt-check        # Check formatting

# Development
make dev-setup        # Full dev environment setup
make bench            # Run benchmarks
make test-golden      # Update golden files

Running the CLI

Parse a Message

# Sample HL7v2 message
./bin/fi-fhir parse --format hl7v2 --pretty testdata/adt_a01_sample.hl7

# With verbose output
./bin/fi-fhir parse --format hl7v2 --verbose testdata/adt_a01_sample.hl7

Run Tests

# All tests
go test ./...

# Specific package
go test -v ./internal/parser/hl7v2/...

# Single test
go test -v -run TestParseADTA01 ./internal/parser/hl7v2/

Docker Development

Start Local Stack

# Start PostgreSQL, Kafka, FHIR server, Jaeger
docker-compose up -d

# Check status
docker-compose ps

# View logs
docker-compose logs -f

Services

ServicePortDescription
PostgreSQL5432Event store
Kafka9092Message queue
HAPI FHIR8090FHIR R4 server
Jaeger16686Tracing UI

Run Integration Tests

# Start dependencies
docker-compose up -d

# Run integration tests
make test-integration

# Clean up
docker-compose down

TypeScript SDK Development

Setup

cd sdk/typescript

# Install dependencies
npm install

# Build
npm run build

# Test
npm test

Watch Mode

npm run dev

UI Development

Setup

cd ui

# Install dependencies
npm install

# Start dev server
npm run dev

The UI is available at http://localhost:5173

Connect to API

# Start the API server
./bin/fi-fhir serve --port 8081

# Configure UI
VITE_API_ORIGIN=http://localhost:8081 npm run dev

IDE Setup

VS Code

Recommended extensions:

  • Go (official)
  • golangci-lint
  • EditorConfig

Settings (.vscode/settings.json):

{
  "go.lintTool": "golangci-lint",
  "go.lintFlags": ["--fast"],
  "editor.formatOnSave": true,
  "[go]": {
    "editor.defaultFormatter": "golang.go"
  }
}

GoLand / IntelliJ

  • Enable golangci-lint integration
  • Configure Go modules
  • Set test flags: -race -v

Debugging

Delve Debugger

# Install delve
go install github.com/go-delve/delve/cmd/dlv@latest

# Debug CLI
dlv debug ./cmd/fi-fhir -- parse --format hl7v2 testdata/sample.hl7

# Debug test
dlv test ./internal/parser/hl7v2/ -- -test.run TestParseADTA01

VS Code Launch Configuration

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Parse Command",
      "type": "go",
      "request": "launch",
      "mode": "debug",
      "program": "${workspaceFolder}/cmd/fi-fhir",
      "args": ["parse", "--format", "hl7v2", "testdata/adt_a01_sample.hl7"]
    }
  ]
}

Common Issues

"go: module not found"

# Ensure you're in the project root
pwd  # Should show fi-fhir directory

# Tidy modules
go mod tidy

"permission denied" on bin/fi-fhir

chmod +x bin/fi-fhir

Test failures with "timeout"

Some tests require Docker services:

# Start Docker services
docker-compose up -d

# Wait for services to be ready
sleep 10

# Re-run tests
make test-integration

Lint errors

# Auto-fix what's possible
make lint-fix

# Manual fixes needed for remaining issues
make lint

Environment Variables

For development:

# Optional: Override config file location
export FI_FHIR_CONFIG=./dev-config.yaml

# Optional: Enable debug logging
export FI_FHIR_LOG_LEVEL=debug

# For integration tests
export FI_FHIR_DATABASE_URL=postgres://postgres:postgres@localhost:5432/fi_fhir_test

Next Steps