Skip to content

Architecture Overview

flowchart LR
  ERP[ERP Systems] -->|POST /api/v1/inbound/work-orders| API[iqv-integration-api serve]
  API --> Mongo[(Customer MongoDB)]
  API --> IQV[IQV platform / domain data]
  Worker[iqv-integration-api worker] -.->|planned outbound| External[External APIs]
  Worker -.-> Mongo
  API --> Health[GET /health/live /ready /details]

The service is a single binary. serve is the production HTTP process. worker is a scaffold and does not run outbound business jobs.

Package boundaries

Package Responsibility
cmd/iqv-integration-api Process entrypoint
internal/command CLI dispatch
internal/app Runtime wiring and lifecycle
internal/config Typed configuration
internal/logging Structured slog to stdout
internal/database/mongodb MongoDB client and health
internal/httpserver HTTP server and routes
internal/middleware Request ID, logging, limits, recover
internal/health Liveness / readiness / details
internal/response / httperror Standard envelopes and codes
internal/inbound/workorder Decode, validate, actor, persist
internal/idempotency Idempotency-Key store
internal/outbound/* Read APIs for events and performance
internal/worker Worker scaffold
internal/migration Migration runner
internal/windowsservice Native Windows Service host
internal/security Reserved package name; auth lives in internal/auth
internal/telemetry Reserved for metrics/push

Handlers must not read environment variables or construct MongoDB clients directly.

Deployment layer

Installers and update scripts sit outside the Go binary:

  • Windows Native: scripts/windows/service
  • Windows Docker: scripts/windows/docker
  • Linux Native: scripts/linux/service (offline package copies these to scripts/)
  • Linux Docker: scripts/linux/docker

They manage service/container lifecycle, backups, health gates, and deployment metadata. They never install or roll back MongoDB.

Health endpoints

Path Meaning
GET / Service name, version, environment
GET /health/live Process liveness (no MongoDB)
GET /health/ready MongoDB ping
GET /health/details Extended details when HEALTH_DETAILS_ENABLED=true