# sriramv1212/real-time-event-driven-payment-processing-backend architecture

> Architecture diagram of the GitHub repository sriramv1212/real-time-event-driven-payment-processing-backend, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sriramv1212/real-time-event-driven-payment-processing-backend
- Repository: https://github.com/sriramv1212/real-time-event-driven-payment-processing-backend

## Overview

This is a FastAPI payment backend that accepts idempotent payment requests, records payment state and publication intent atomically in PostgreSQL, then processes events asynchronously through Kafka. The relay publishes outbox events; the payment consumer applies payment side effects with duplicate protection and hands failures to a dead-letter topic for inspection. An expiry worker cleans up API idempotency records. The graph reflects the documented architecture and sampled source; database schema details and some subsystem behavior are documented rather than fully sampled.

Main entry points: [`api/main.py`](https://github.com/sriramv1212/real-time-event-driven-payment-processing-backend/blob/main/api/main.py) (Payment API), [`consumer/payment_consumer.py`](https://github.com/sriramv1212/real-time-event-driven-payment-processing-backend/blob/main/consumer/payment_consumer.py) (Payment Consumer), [`outbox_relay.py`](https://github.com/sriramv1212/real-time-event-driven-payment-processing-backend/blob/main/outbox_relay.py) (Outbox Relay), [`api/producer.py`](https://github.com/sriramv1212/real-time-event-driven-payment-processing-backend/blob/main/api/producer.py) (Kafka Producer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Payment API"]
  node_api["Payment API<br/>[main.py]"]
  node_validation["Request Validation<br/>[models.py]"]
end

subgraph group_state["Durable State"]
  node_db[("PostgreSQL<br/>[schema.sql]")]
  node_payments["Payment Records<br/>[schema.sql]"]
  node_outbox["Outbox Records<br/>[schema.sql]"]
  node_idempotency["Idempotency Records<br/>[schema.sql]"]
  node_processed["Processed Events<br/>[schema.sql]"]
end

subgraph group_processing["Event Processing"]
  node_relay["Outbox Relay<br/>[outbox_relay.py]"]
  node_producer["Kafka Producer<br/>[producer.py]"]
  node_payment_topic["Payment Topic"]
  node_consumer["Payment Consumer"]
  node_dlq_topic["DLQ Topic"]
  node_dlq_consumer["DLQ Inspector<br/>[dlq_consumer.py]"]
end

subgraph group_operations["Operations"]
  node_cleanup["Idempotency Cleanup"]
  node_config["Runtime Configuration<br/>[config.py]"]
end

node_client(("Client"))

node_client -->|"submits request"| node_api
node_api -->|"validates with"| node_validation
node_api -->|"checks and records"| node_idempotency
node_api -->|"creates and reads"| node_payments
node_api -->|"writes atomically"| node_outbox
node_api -->|"returns response"| node_client
node_relay -->|"claims and marks"| node_outbox
node_relay -->|"publishes through"| node_producer
node_producer -->|"sends events"| node_payment_topic
node_payment_topic -->|"delivers events"| node_consumer
node_consumer -->|"deduplicates in"| node_processed
node_consumer -->|"updates status"| node_payments
node_consumer -->|"updates balance"| node_db
node_consumer -->|"hands off failures"| node_dlq_topic
node_dlq_topic -->|"feeds inspection"| node_dlq_consumer
node_cleanup -->|"deletes expired"| node_idempotency
node_api -.->|"uses settings"| node_config
node_relay -->|"connects through helper"| node_db

click node_api "https://github.com/sriramv1212/real-time-event-driven-payment-processing-backend/blob/main/api/main.py"
click node_validation "https://github.com/sriramv1212/real-time-event-driven-payment-processing-backend/blob/main/api/models.py"
click node_db "https://github.com/sriramv1212/real-time-event-driven-payment-processing-backend/blob/main/db/schema.sql"
click node_payments "https://github.com/sriramv1212/real-time-event-driven-payment-processing-backend/blob/main/db/schema.sql"
click node_outbox "https://github.com/sriramv1212/real-time-event-driven-payment-processing-backend/blob/main/db/schema.sql"
click node_idempotency "https://github.com/sriramv1212/real-time-event-driven-payment-processing-backend/blob/main/db/schema.sql"
click node_processed "https://github.com/sriramv1212/real-time-event-driven-payment-processing-backend/blob/main/db/schema.sql"
click node_relay "https://github.com/sriramv1212/real-time-event-driven-payment-processing-backend/blob/main/outbox_relay.py"
click node_producer "https://github.com/sriramv1212/real-time-event-driven-payment-processing-backend/blob/main/api/producer.py"
click node_consumer "https://github.com/sriramv1212/real-time-event-driven-payment-processing-backend/blob/main/consumer/payment_consumer.py"
click node_dlq_consumer "https://github.com/sriramv1212/real-time-event-driven-payment-processing-backend/blob/main/consumer/dlq_consumer.py"
click node_cleanup "https://github.com/sriramv1212/real-time-event-driven-payment-processing-backend/blob/main/idempotency_cleanup.py"
click node_config "https://github.com/sriramv1212/real-time-event-driven-payment-processing-backend/blob/main/config.py"

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_api,node_validation,node_client toneBlue
class node_db,node_payments,node_outbox,node_idempotency,node_processed toneAmber
class node_relay,node_producer,node_payment_topic,node_consumer,node_dlq_topic,node_dlq_consumer toneMint
class node_cleanup,node_config toneRose
```

## Components

### Payment API

- [Payment API](https://github.com/sriramv1212/real-time-event-driven-payment-processing-backend/blob/main/api/main.py): `api/main.py`
- [Request Validation](https://github.com/sriramv1212/real-time-event-driven-payment-processing-backend/blob/main/api/models.py): `api/models.py`

### Durable State

- [PostgreSQL](https://github.com/sriramv1212/real-time-event-driven-payment-processing-backend/blob/main/db/schema.sql): `db/schema.sql`
- [Payment Records](https://github.com/sriramv1212/real-time-event-driven-payment-processing-backend/blob/main/db/schema.sql): `db/schema.sql`
- [Outbox Records](https://github.com/sriramv1212/real-time-event-driven-payment-processing-backend/blob/main/db/schema.sql): `db/schema.sql`
- [Idempotency Records](https://github.com/sriramv1212/real-time-event-driven-payment-processing-backend/blob/main/db/schema.sql): `db/schema.sql`
- [Processed Events](https://github.com/sriramv1212/real-time-event-driven-payment-processing-backend/blob/main/db/schema.sql): `db/schema.sql`

### Event Processing

- [Outbox Relay](https://github.com/sriramv1212/real-time-event-driven-payment-processing-backend/blob/main/outbox_relay.py): `outbox_relay.py`
- [Kafka Producer](https://github.com/sriramv1212/real-time-event-driven-payment-processing-backend/blob/main/api/producer.py): `api/producer.py`
- **Payment Topic**
- [Payment Consumer](https://github.com/sriramv1212/real-time-event-driven-payment-processing-backend/blob/main/consumer/payment_consumer.py): `consumer/payment_consumer.py`
- **DLQ Topic**
- [DLQ Inspector](https://github.com/sriramv1212/real-time-event-driven-payment-processing-backend/blob/main/consumer/dlq_consumer.py): `consumer/dlq_consumer.py`

### Operations

- [Idempotency Cleanup](https://github.com/sriramv1212/real-time-event-driven-payment-processing-backend/blob/main/idempotency_cleanup.py): `idempotency_cleanup.py`
- [Runtime Configuration](https://github.com/sriramv1212/real-time-event-driven-payment-processing-backend/blob/main/config.py): `config.py`

### Other components

- **Client**

## Connections

- Client → Payment API: submits request (evidence: `README.md`)
- Payment API → Request Validation: validates with (evidence: `api/main.py`)
- Payment API → Idempotency Records: checks and records (evidence: `api/main.py`)
- Payment API → Payment Records: creates and reads (evidence: `api/main.py`)
- Payment API → Outbox Records: writes atomically (evidence: `api/main.py`)
- Payment API → Client: returns response (evidence: `api/main.py`)
- Outbox Relay → Outbox Records: claims and marks (evidence: `outbox_relay.py`)
- Outbox Relay → Kafka Producer: publishes through (evidence: `outbox_relay.py`)
- Kafka Producer → Payment Topic: sends events (evidence: `api/producer.py`)
- Payment Topic → Payment Consumer: delivers events (evidence: `README.md`)
- Payment Consumer → Processed Events: deduplicates in (evidence: `consumer/payment_consumer.py`)
- Payment Consumer → Payment Records: updates status (evidence: `consumer/payment_consumer.py`)
- Payment Consumer → PostgreSQL: updates balance (evidence: `README.md`)
- Payment Consumer → DLQ Topic: hands off failures (evidence: `consumer/payment_consumer.py`)
- DLQ Topic → DLQ Inspector: feeds inspection (evidence: `README.md`)
- Idempotency Cleanup → Idempotency Records: deletes expired (evidence: `README.md`)
- Payment API → Runtime Configuration: uses settings
- Outbox Relay → PostgreSQL: connects through helper (evidence: `outbox_relay.py`)
