Open Insurance API

Corporate insurance platform API for web and mobile clients — hybrid microservices in a single repository.

Architecture

Hybrid microservices, package-by-feature, one monorepo:

Component	Stack	Role
identity	Go + gRPC/HTTP	AuthN, AuthZ, permissions, sessions
application	Go + gRPC/HTTP + Temporal	Core insurance business logic
storage	Go + gRPC/HTTP	Documents, objects, metadata
gateway	Kong (declarative)	Edge routing and CORS

Supporting infrastructure: PostgreSQL, Redis, apache/kafka (KRaft), Temporal (+ UI).

                    ┌─────────────┐
   Web / Mobile ───►│ Kong Gateway│
                    └──────┬──────┘
           ┌───────────────┼───────────────┐
           ▼               ▼               ▼
      identity        application       storage
           │               │               │
           └───────────────┴───────────────┘
                   │    │    │
              Postgres Redis Kafka / Temporal

Repository layout

.
├── cmd/                      # Service entry points
│   ├── identity/
│   ├── application/
│   ├── storage/
│   └── seed-user/            # Dev utility to create a login user
├── services/                 # Package-by-feature domain code
│   ├── identity/             # authn, authz, permissions, sessions
│   ├── application/          # policies, claims, quotes, underwriting
│   └── storage/              # documents, objects, metadata
├── gateway/kong/             # Kong declarative config (bridge + host variants)
├── pkg/                      # Shared libraries (config, logger, health, grpc)
├── proto/                    # gRPC/protobuf definitions (future)
├── deployments/
│   ├── docker/               # Dockerfiles
│   └── temporal/dynamicconfig/
├── docs/
│   └── api/                  # OpenAPI spec, Redocly config, API docs guide
├── scripts/                  # Docker, seed-user, API docs tooling
│   ├── api-docs.sh           # Preview OpenAPI reference locally
│   ├── api-lint.sh           # Validate openapi.yaml
│   ├── seed-user.sh          # Seed dev login user via Docker network
│   ├── fix-docker-proxy.sh   # Permanent fix for broken Docker port publishing
│   └── lib/                  # compose.sh, port-forward-check.sh
├── docker-compose.yml
├── docker-compose.host.yml   # Override when Docker port publishing is broken
└── Makefile

Quick start

Prerequisites

• Go 1.26+
• Docker & Docker Compose
• Node.js/npx or Docker (optional, for make api-docs / make api-lint)

Local binaries

cp .env.example .env
go mod tidy
make build
make test
make run-identity      # :8080 / :9090 (set POSTGRES_HOST etc. in .env)

When running services locally, use POSTGRES_HOST=localhost and the ports from .env.example. Docker maps identity to 8081 on the host (see endpoints below).

Full stack (Docker)

cp .env.example .env
make docker-deploy
# or
./scripts/docker-deploy.sh

If localhost port mappings hang or refuse connections (Docker 29.x userland-proxy issue on some hosts), deploy auto-detects this and switches to host networking. For a permanent fix so normal bridge mode works:

make fix-docker-proxy   # adds "userland-proxy": false to /etc/docker/daemon.json (requires sudo)
make docker-deploy

To force host networking without changing Docker:

make docker-deploy-host
# or set DOCKER_HOST_NETWORK=1 in .env, then make docker-deploy

Useful endpoints after deploy:

Service	URL
Gateway proxy	http://localhost:8000
Gateway → identity login	POST http://localhost:8000/identity/auth/login
Gateway → identity health	http://localhost:8000/identity/healthz
Gateway → application health	http://localhost:8000/application/healthz
Gateway → storage health	http://localhost:8000/storage/healthz
Identity (direct)	http://localhost:8081/healthz
Identity login (direct)	POST http://localhost:8081/auth/login
Application (direct)	http://localhost:8082/healthz
Storage (direct)	http://localhost:8083/healthz
PostgreSQL	localhost:5432
Temporal UI	http://localhost:8088
Temporal server	localhost:7233
Kong admin	http://localhost:8001
API docs (local)	http://localhost:8089 (make api-docs)

Authentication

Email/password login is handled by the identity service. Passwords are stored as Argon2id hashes.

Seed a dev user (stack must be running):

make seed-user
# default: user@example.com / secret123

Log in via the gateway:

curl -s -X POST http://localhost:8000/identity/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"email":"user@example.com","password":"secret123"}'

Example response:

{
  "access_token": "<jwt>",
  "token_type": "Bearer",
  "expires_in": 3600
}

Configure signing with JWT_SECRET, JWT_ISSUER, and JWT_ACCESS_TTL in .env (see Configuration).

API documentation

The public HTTP contract lives in docs/api/openapi.yaml (gateway paths). gRPC contracts will live under proto/.

make api-docs    # interactive reference at http://localhost:8089
make api-lint    # validate the spec (run before PRs)

See docs/api/README.md for editing workflow and conventions.

Makefile

make test              # run Go tests
make api-docs          # preview OpenAPI reference (http://localhost:8089)
make api-lint          # validate openapi.yaml
make seed-user         # create dev login user in Postgres
make docker-deploy     # build and start full stack
make docker-deploy-host
make fix-docker-proxy  # fix broken Docker port publishing (sudo)

Docker scripts

./scripts/docker-build.sh          # build images
./scripts/docker-up.sh all         # start everything
./scripts/docker-up.sh infra       # postgres, redis, kafka, temporal only
./scripts/docker-up.sh services    # identity, application, storage, gateway only
./scripts/docker-down.sh           # stop
./scripts/docker-down.sh --volumes # stop and wipe volumes
./scripts/docker-deploy.sh         # build + up + smoke check
make docker-deploy-host            # deploy with host networking override
make fix-docker-proxy              # permanent Docker daemon fix (sudo)

Configuration

Copy .env.example to .env. Services read env vars from pkg/config, including:

Variable	Purpose
POSTGRES_*	Main application database
REDIS_PORT / REDIS_ADDR	Redis (addr set internally in Docker)
KAFKA_BROKERS	Kafka bootstrap servers (set in compose)
TEMPORAL_HOST_PORT	Temporal frontend address
JWT_SECRET	HMAC key for access tokens
JWT_ISSUER	JWT iss claim
JWT_ACCESS_TTL	Access token lifetime (e.g. 1h)

DOCKER_HOST_NETWORK is optional (unset = auto-detect, 0 = bridge, 1 = host). When Docker port publishing is broken, deploy falls back to docker-compose.host.yml automatically. Run make fix-docker-proxy once (sudo) to fix Docker daemon settings permanently.

Use passwords in .env without shell metacharacters (>, |, $, etc.) or always quote values when exporting them in the shell.

Contributing

See CONTRIBUTING.md and CONTRIBUTORS.md. When changing HTTP endpoints, update docs/api/openapi.yaml and run make api-lint.

License

Licensed under the Apache License 2.0.

Contributors

This list is generated automatically from GitHub repository contributors.

See CONTRIBUTORS.md for how recognition works.