Client → Spring Boot API → PostgreSQL → simulated provider
The worker reads UNKNOWN records, checks the provider, and writes the final state to PostgreSQL.01 / SYSTEM DESIGN
How PayGuard works.
Trace one payment from the HTTP request through durable state, simulated provider uncertainty, recovery, and monitoring.
COMPONENT MAP
Follow the data.
Spring Boot / Micrometer → Prometheus → Grafana
Prometheus evaluates the SLI and alert rules; the hosted runner exports a dated view.PayGuard containers → Alloy → Loki → Grafana
Alloy selects only PayGuard Compose containers before forwarding their log events.REQUEST FLOW
Five states in one story.
01POSTClient supplies Idempotency-Key and payment body.
02PersistAPI creates the payment in PostgreSQL.
03TimeoutFake provider stores SUCCESS but throws an exception.
04UNKNOWNAPI records uncertainty and schedules reconciliation.
05SUCCESSWorker checks provider; retry uses the same ID.
Follow PaymentService.java ↗, FakePaymentProvider.java ↗, and PaymentReconciliationWorker.java ↗.
PERSISTENCE
State survives the process.
PostgreSQL holds payments and the idempotency key. Flyway applies V1–V3 migrations; JPA validates the schema instead of changing it. Reconciliation metadata records attempts and the next check. Kubernetes uses a PVC for PostgreSQL. Read the table migration ↗
DEPLOYMENT MAP
Local containers to orchestration.
One workstation
Starts PostgreSQL, API, a Go health companion, Prometheus, Grafana, Loki, and Alloy. Python checks the hosted demo and exports dated evidence. Only the fake provider is used.
Compose file ↗Minikube lab
Startup, readiness and liveness probes; replica scaling, PVC durability, restart, rollout and rollback.
Deployment ↗Declared resources
Manages an isolated payguard-iac namespace; a second plan returned no changes.
Terraform resources ↗Operational checks
Verifies live namespace, deployments, PVC, and pods from the control host; runtime checked locally.
Playbook ↗