# chandanvura/payguard architecture

> Architecture diagram of the GitHub repository chandanvura/payguard, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/chandanvura/payguard
- Repository: https://github.com/chandanvura/payguard

## Overview

PayGuard’s central workflow accepts an idempotent payment request, persists it before calling a simulated provider, and records a definitive result or UNKNOWN; retries reuse the payment ID. A Java reconciliation worker checks uncertain outcomes and updates payment state. The repository also documents a Go health observer and Prometheus/Grafana and Alloy/Loki observability paths, plus SRE rules. Source excerpts establish Java call ownership; README statements support the wider monitoring relationships. Unsampled infrastructure wiring is represented only where the README documents it.

Main entry points: [`payment-service/src/main/java/com/payguard/payment_service/payment/PaymentService.java`](https://github.com/chandanvura/payguard/blob/main/payment-service/src/main/java/com/payguard/payment_service/payment/PaymentService.java) (Payment Service), [`payment-service/src/main/java/com/payguard/payment_service/payment/PaymentController.java`](https://github.com/chandanvura/payguard/blob/main/payment-service/src/main/java/com/payguard/payment_service/payment/PaymentController.java) (Payment Controller), [`observability/prometheus/prometheus.yml`](https://github.com/chandanvura/payguard/blob/main/observability/prometheus/prometheus.yml) (Prometheus), [`payment-service/src/main/java/com/payguard/payment_service/payment/PaymentReconciliationWorker.java`](https://github.com/chandanvura/payguard/blob/main/payment-service/src/main/java/com/payguard/payment_service/payment/PaymentReconciliationWorker.java) (Reconciliation Worker)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Payment API"]
  node_controller["Payment Controller"]
  node_payment_service["Payment Service"]
  node_api_response["Payment Response"]
end

subgraph group_reliability["Payment Reliability"]
  node_transaction["Transaction Service"]
  node_repository["Payment Repository"]
  node_payment_record["Payment State<br/>[Payment.java]"]
  node_provider["Simulated Provider"]
  node_provider_contract["Provider Contract"]
  node_worker["Reconciliation Worker"]
  node_postgres[("PostgreSQL")]
end

subgraph group_platform["Health Companion"]
  node_go_companion["Go Health Observer<br/>[main.go]"]
end

subgraph group_observability["Observability"]
  node_prometheus[("Prometheus<br/>[prometheus.yml]")]
  node_grafana["Grafana"]
  node_alloy["Alloy Log Collector<br/>[config.alloy]"]
  node_loki[("Loki<br/>[loki-config.yml]")]
end

subgraph group_operations["SRE Operations"]
  node_slo_rules["SLI SLO Rules<br/>[payguard-slo.yml]"]
  node_terraform["Terraform Setup<br/>[main.tf]"]
  node_ansible["Operational Verification"]
end

node_client(("API Client"))

node_client -->|"submits request"| node_controller
node_controller -->|"calls"| node_payment_service
node_controller -->|"maps result"| node_api_response
node_payment_service -->|"looks up"| node_repository
node_payment_service -->|"creates or updates"| node_transaction
node_payment_service -->|"charges and checks"| node_provider_contract
node_provider -->|"implements"| node_provider_contract
node_transaction -->|"saves"| node_repository
node_repository -->|"loads and stores"| node_payment_record
node_payment_service -->|"persists payment"| node_postgres
node_worker -->|"reconciles through"| node_payment_service
node_worker -->|"loads and updates"| node_postgres
node_worker -->|"checks status"| node_provider_contract
node_go_companion -->|"probes health"| node_controller
node_controller -->|"exports metrics"| node_prometheus
node_go_companion -->|"exposes metrics"| node_prometheus
node_prometheus -->|"feeds dashboards"| node_grafana
node_alloy -->|"ships logs"| node_loki
node_loki -->|"feeds log views"| node_grafana
node_slo_rules -->|"defines rules"| node_prometheus
node_terraform -.->|"isolated setup only"| node_postgres
node_ansible -.->|"verifies operations"| node_postgres

click node_controller "https://github.com/chandanvura/payguard/blob/main/payment-service/src/main/java/com/payguard/payment_service/payment/PaymentController.java"
click node_payment_service "https://github.com/chandanvura/payguard/blob/main/payment-service/src/main/java/com/payguard/payment_service/payment/PaymentService.java"
click node_api_response "https://github.com/chandanvura/payguard/blob/main/payment-service/src/main/java/com/payguard/payment_service/payment/PaymentResponse.java"
click node_transaction "https://github.com/chandanvura/payguard/blob/main/payment-service/src/main/java/com/payguard/payment_service/payment/PaymentTransactionService.java"
click node_repository "https://github.com/chandanvura/payguard/blob/main/payment-service/src/main/java/com/payguard/payment_service/payment/PaymentRepository.java"
click node_payment_record "https://github.com/chandanvura/payguard/blob/main/payment-service/src/main/java/com/payguard/payment_service/payment/Payment.java"
click node_provider "https://github.com/chandanvura/payguard/blob/main/payment-service/src/main/java/com/payguard/payment_service/provider/FakePaymentProvider.java"
click node_provider_contract "https://github.com/chandanvura/payguard/blob/main/payment-service/src/main/java/com/payguard/payment_service/provider/PaymentProvider.java"
click node_worker "https://github.com/chandanvura/payguard/blob/main/payment-service/src/main/java/com/payguard/payment_service/payment/PaymentReconciliationWorker.java"
click node_go_companion "https://github.com/chandanvura/payguard/blob/main/sidecar/main.go"
click node_prometheus "https://github.com/chandanvura/payguard/blob/main/observability/prometheus/prometheus.yml"
click node_grafana "https://github.com/chandanvura/payguard/tree/main/observability/grafana"
click node_alloy "https://github.com/chandanvura/payguard/blob/main/observability/alloy/config.alloy"
click node_loki "https://github.com/chandanvura/payguard/blob/main/observability/loki/loki-config.yml"
click node_slo_rules "https://github.com/chandanvura/payguard/blob/main/observability/prometheus/rules/payguard-slo.yml"
click node_terraform "https://github.com/chandanvura/payguard/blob/main/terraform/main.tf"
click node_ansible "https://github.com/chandanvura/payguard/blob/main/ansible/playbooks/verify-payguard.yml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_controller,node_payment_service,node_api_response,node_client toneBlue
class node_transaction,node_repository,node_payment_record,node_provider,node_provider_contract,node_worker,node_postgres toneAmber
class node_go_companion toneMint
class node_prometheus,node_grafana,node_alloy,node_loki toneRose
class node_slo_rules,node_terraform,node_ansible toneIndigo
```

## Components

### Payment API

- [Payment Controller](https://github.com/chandanvura/payguard/blob/main/payment-service/src/main/java/com/payguard/payment_service/payment/PaymentController.java): `payment-service/src/main/java/com/payguard/payment_service/payment/PaymentController.java`
- [Payment Service](https://github.com/chandanvura/payguard/blob/main/payment-service/src/main/java/com/payguard/payment_service/payment/PaymentService.java): `payment-service/src/main/java/com/payguard/payment_service/payment/PaymentService.java`
- [Payment Response](https://github.com/chandanvura/payguard/blob/main/payment-service/src/main/java/com/payguard/payment_service/payment/PaymentResponse.java): `payment-service/src/main/java/com/payguard/payment_service/payment/PaymentResponse.java`

### Payment Reliability

- [Transaction Service](https://github.com/chandanvura/payguard/blob/main/payment-service/src/main/java/com/payguard/payment_service/payment/PaymentTransactionService.java): `payment-service/src/main/java/com/payguard/payment_service/payment/PaymentTransactionService.java`
- [Payment Repository](https://github.com/chandanvura/payguard/blob/main/payment-service/src/main/java/com/payguard/payment_service/payment/PaymentRepository.java): `payment-service/src/main/java/com/payguard/payment_service/payment/PaymentRepository.java`
- [Payment State](https://github.com/chandanvura/payguard/blob/main/payment-service/src/main/java/com/payguard/payment_service/payment/Payment.java): `payment-service/src/main/java/com/payguard/payment_service/payment/Payment.java`
- [Simulated Provider](https://github.com/chandanvura/payguard/blob/main/payment-service/src/main/java/com/payguard/payment_service/provider/FakePaymentProvider.java): `payment-service/src/main/java/com/payguard/payment_service/provider/FakePaymentProvider.java`
- [Provider Contract](https://github.com/chandanvura/payguard/blob/main/payment-service/src/main/java/com/payguard/payment_service/provider/PaymentProvider.java): `payment-service/src/main/java/com/payguard/payment_service/provider/PaymentProvider.java`
- [Reconciliation Worker](https://github.com/chandanvura/payguard/blob/main/payment-service/src/main/java/com/payguard/payment_service/payment/PaymentReconciliationWorker.java): `payment-service/src/main/java/com/payguard/payment_service/payment/PaymentReconciliationWorker.java`
- **PostgreSQL**

### Health Companion

- [Go Health Observer](https://github.com/chandanvura/payguard/blob/main/sidecar/main.go): `sidecar/main.go`

### Observability

- [Prometheus](https://github.com/chandanvura/payguard/blob/main/observability/prometheus/prometheus.yml): `observability/prometheus/prometheus.yml`
- [Grafana](https://github.com/chandanvura/payguard/tree/main/observability/grafana): `observability/grafana`
- [Alloy Log Collector](https://github.com/chandanvura/payguard/blob/main/observability/alloy/config.alloy): `observability/alloy/config.alloy`
- [Loki](https://github.com/chandanvura/payguard/blob/main/observability/loki/loki-config.yml): `observability/loki/loki-config.yml`

### SRE Operations

- [SLI SLO Rules](https://github.com/chandanvura/payguard/blob/main/observability/prometheus/rules/payguard-slo.yml): `observability/prometheus/rules/payguard-slo.yml`
- [Terraform Setup](https://github.com/chandanvura/payguard/blob/main/terraform/main.tf): `terraform/main.tf`
- [Operational Verification](https://github.com/chandanvura/payguard/blob/main/ansible/playbooks/verify-payguard.yml): `ansible/playbooks/verify-payguard.yml`

### Other components

- **API Client**

## Connections

- API Client → Payment Controller: submits request (evidence: `README.md`)
- Payment Controller → Payment Service: calls (evidence: `payment-service/src/main/java/com/payguard/payment_service/payment/PaymentController.java`)
- Payment Controller → Payment Response: maps result (evidence: `payment-service/src/main/java/com/payguard/payment_service/payment/PaymentController.java`)
- Payment Service → Payment Repository: looks up (evidence: `payment-service/src/main/java/com/payguard/payment_service/payment/PaymentService.java`)
- Payment Service → Transaction Service: creates or updates (evidence: `payment-service/src/main/java/com/payguard/payment_service/payment/PaymentService.java`)
- Payment Service → Provider Contract: charges and checks (evidence: `payment-service/src/main/java/com/payguard/payment_service/payment/PaymentService.java`)
- Simulated Provider → Provider Contract: implements (evidence: `payment-service/src/main/java/com/payguard/payment_service/provider/FakePaymentProvider.java`)
- Transaction Service → Payment Repository: saves (evidence: `payment-service/src/main/java/com/payguard/payment_service/payment/PaymentTransactionService.java`)
- Payment Repository → Payment State: loads and stores (evidence: `payment-service/src/main/java/com/payguard/payment_service/payment/PaymentRepository.java`)
- Payment Service → PostgreSQL: persists payment (evidence: `README.md`)
- Reconciliation Worker → Payment Service: reconciles through (evidence: `payment-service/src/main/java/com/payguard/payment_service/payment/PaymentReconciliationWorker.java`)
- Reconciliation Worker → PostgreSQL: loads and updates (evidence: `README.md`)
- Reconciliation Worker → Provider Contract: checks status (evidence: `README.md`)
- Go Health Observer → Payment Controller: probes health (evidence: `README.md`)
- Payment Controller → Prometheus: exports metrics (evidence: `README.md`)
- Go Health Observer → Prometheus: exposes metrics (evidence: `README.md`)
- Prometheus → Grafana: feeds dashboards (evidence: `README.md`)
- Alloy Log Collector → Loki: ships logs (evidence: `README.md`)
- Loki → Grafana: feeds log views (evidence: `README.md`)
- SLI SLO Rules → Prometheus: defines rules (evidence: `README.md`)
- Terraform Setup → PostgreSQL: isolated setup only (evidence: `README.md`)
- Operational Verification → PostgreSQL: verifies operations (evidence: `README.md`)
