inventory-flo-debezium-nats/README.md

Live Inventory CDC Demo

Small POC website showing browser CRUD actions flowing through Postgres, Debezium Server, NATS JetStream, a Go SSE backend, and back into the browser.

The important demo behavior is that mutation endpoints only return command accepted. The visible inventory cards are refreshed when the matching CDC event arrives over /events.

Development Run

Development uses compose.yml for Postgres, NATS JetStream, Debezium, and helper containers. The Go web app runs as a native host process.

Install the host tools:

sudo dnf install golang podman

Use Taskfile as the main interface:

task --list

Terminal 1, start containerized Postgres, NATS, and Debezium:

task infra

Terminal 2, run the Go backend/frontend:

task backend

Then open:

http://localhost:8080

Postgres is published to the host on:

localhost:5453

NATS is published to the host on:

localhost:4222

Development Debezium uses the internal compose addresses postgres:5432 and nats:4222.

The Go backend defaults to:

DATABASE_URL=postgres://postgres:postgres@localhost:5453/postgres?sslmode=disable
NATS_URL=nats://localhost:4222

Production Run

Production uses user-level Podman quadlets for containers and a user systemd service for the Go backend.

Install the production units:

task prod:install

Start everything:

task prod:start

Stop everything:

task prod:down

Follow production logs:

task prod:logs

Production Debezium uses the internal quadlet network addresses cdc-postgres:5432 and cdc-nats:4222.

Production User Units

Quadlet files are installed to:

~/.config/containers/systemd/

The Go backend service is installed to:

~/.config/systemd/user/cdc-inventory.service

The service files are:

Unit	Purpose
cdc-postgres.service	Postgres with logical replication enabled
cdc-nats.service	NATS JetStream
cdc-debezium.service	Debezium Server
cdc-inventory.service	Native Go backend/frontend
cdc-seed.service	One-shot seed helper
cdc-inspect.service	One-shot NATS inspect helper

Useful Checks

Inspect stream subjects and recent events:

task inspect

For production:

task prod:inspect

Generate a fresh burst of create/update/delete events:

task seed

For production:

task prod:seed

Stop development infrastructure:

task down

Endpoints

Method	Path	Purpose
GET	/	Demo page
GET	/health	Health check
GET	/api/inventory	Current database snapshot
POST	/api/inventory	Create inventory item
PATCH	/api/inventory/{id}/sell	Decrement quantity by 1
PATCH	/api/inventory/{id}/restock	Increment quantity
PATCH	/api/inventory/{id}	Rename, move, or set quantity
DELETE	/api/inventory/{id}	Delete item
GET	/events	Server-Sent Events from CDC stream

Pipeline

Browser action
-> Go backend writes to Postgres
-> Debezium captures the DB change
-> Debezium publishes to NATS JetStream
-> Go backend consumes the event
-> Go backend streams it to browser with SSE
-> Browser updates inventory and audit trail