fi-fhir docs

fi-fhir Developer Guide

This guide is for developers contributing to fi-fhir or building extensions and integrations.

Quick Links

I want to...	Read...
Set up my development environment	Development Setup
Understand the architecture	Architecture Overview
Add support for a new format	Adding a Format Parser
Create a new event type	Adding Event Types
Build a custom workflow action	Adding Actions
Write effective tests	Testing Guidelines
Contribute to the TypeScript SDK	TypeScript SDK Development

Project Structure

fi-fhir/
├── cmd/fi-fhir/              # CLI entry point
│   └── main.go               # Command definitions
├── internal/                  # Private packages
│   ├── api/graphql/          # GraphQL API layer
│   ├── parser/               # Format parsers
│   │   ├── hl7v2/            # HL7v2 parser
│   │   ├── csv/              # CSV parser
│   │   ├── edi/              # EDI X12 parser
│   │   ├── cda/              # CDA/CCDA parser
│   │   └── fhir/             # FHIR parser
│   ├── fhir/subscription/    # FHIR subscriptions
│   ├── workflow/             # Workflow engine
│   └── semantic/             # Event transformation
├── pkg/                       # Public packages
│   ├── events/               # Canonical event types
│   ├── profile/              # Source profile system
│   ├── config/               # Configuration
│   ├── fhir/                 # FHIR mapping
│   ├── validate/             # Identifier validators
│   ├── eventsourcing/        # Event store, projections
│   ├── matching/             # Patient matching
│   └── terminology/          # Code system mapping
├── api/                       # OpenAPI specification
├── sdk/typescript/            # TypeScript SDK
├── ui/                        # SvelteKit Mapping Studio
├── deploy/                    # Deployment configs
│   ├── helm/                 # Helm chart
│   └── kubernetes/           # Kustomize manifests
├── dashboards/                # Grafana dashboards
├── examples/                  # Example workflows
├── profiles/                  # Profile templates
├── testdata/                  # Test data
└── test/e2e/                  # End-to-end tests

Key Design Decisions

1. internal/ vs pkg/

pkg/: Public API - stable, documented, intended for external use
internal/: Implementation details - can change without notice

2. Dependency Injection

The codebase uses explicit dependency injection rather than globals:

// Good: Explicit dependencies
type Parser struct {
    profile  *profile.Profile
    logger   Logger
    metrics  Metrics
}

// Bad: Global state
var globalLogger = log.Default()

3. Error Handling

Use wrapped errors with context:

if err := parser.Parse(msg); err != nil {
    return fmt.Errorf("parsing message %s: %w", msg.ID, err)
}

4. Warnings Over Errors

Healthcare data is messy. Record warnings, don't fail:

// Good: Continue with warning
if field == "" {
    p.addWarning("MISSING_FIELD", path)
    return defaultValue, nil
}

// Bad: Fail on recoverable issue
if field == "" {
    return nil, errors.New("missing field")
}

Development Workflow

1. Fork and Clone

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

2. Install Dependencies

make dev-setup

3. Make Changes

# Create branch
git checkout -b feature/my-feature

# Make changes...

# Run tests
make test

# Run linter
make lint

4. Submit Changes

git commit -m "feat: add my feature"
git push origin feature/my-feature
# Create merge request

Code Style

Go Style

Follow Effective Go
Run gofmt and golangci-lint
Table-driven tests
Meaningful variable names

Commit Messages

Follow Conventional Commits:

feat: add MDM message parsing
fix: handle missing PV1 segment
docs: update workflow DSL reference
test: add integration tests for EDI parser
refactor: simplify identifier extraction

Table of Contents