initial commit

README.md

@@ -0,0 +1,173 @@
+# 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:
+
+```bash
+sudo dnf install golang podman
+```
+
+Use Taskfile as the main interface:
+
+```bash
+task --list
+```
+
+Terminal 1, start containerized Postgres, NATS, and Debezium:
+
+```bash
+task infra
+```
+
+Terminal 2, run the Go backend/frontend:
+
+```bash
+task backend
+```
+
+Then open:
+
+```text
+http://localhost:8080
+```
+
+Postgres is published to the host on:
+
+```text
+localhost:5453
+```
+
+NATS is published to the host on:
+
+```text
+localhost:4222
+```
+
+Development Debezium uses the internal compose addresses `postgres:5432` and `nats:4222`.
+
+The Go backend defaults to:
+
+```text
+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:
+
+```bash
+task prod:install
+```
+
+Start everything:
+
+```bash
+task prod:start
+```
+
+Stop everything:
+
+```bash
+task prod:down
+```
+
+Follow production logs:
+
+```bash
+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:
+
+```text
+~/.config/containers/systemd/
+```
+
+The Go backend service is installed to:
+
+```text
+~/.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:
+
+```bash
+task inspect
+```
+
+For production:
+
+```bash
+task prod:inspect
+```
+
+Generate a fresh burst of create/update/delete events:
+
+```bash
+task seed
+```
+
+For production:
+
+```bash
+task prod:seed
+```
+
+Stop development infrastructure:
+
+```bash
+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
+
+```text
+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
+```