# pavansaikavuri/failed-subscription-recovery-agent architecture

> Architecture diagram of the GitHub repository pavansaikavuri/failed-subscription-recovery-agent, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/pavansaikavuri/failed-subscription-recovery-agent
- Repository: https://github.com/pavansaikavuri/failed-subscription-recovery-agent

## Overview

This is a subscription-payment recovery agent with batch and Razorpay-webhook entry points. Both feed validated failure records into a guarded rules/LLM decision engine; campaign mode revisits unresolved records across dunning cycles. Decisions are evaluated by an independent deterministic outcome simulator, then recorded for audit and benchmark reporting. The graph reflects README-described capabilities where excerpts were incomplete; uncertain implementation wiring is omitted.

Main entry points: [`pipeline.py`](https://github.com/pavansaikavuri/failed-subscription-recovery-agent/blob/main/pipeline.py) (Recovery pipeline), [`app.py`](https://github.com/pavansaikavuri/failed-subscription-recovery-agent/blob/main/app.py) (Webhook receiver), [`strategies.py`](https://github.com/pavansaikavuri/failed-subscription-recovery-agent/blob/main/strategies.py) (Decision strategies), [`benchmark.py`](https://github.com/pavansaikavuri/failed-subscription-recovery-agent/blob/main/benchmark.py) (Benchmark runner)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_intake["Intake and validation"]
  node_batch["Sample batch<br/>[sample_batch.py]"]
  node_webhook["Webhook receiver<br/>[app.py]"]
  node_normalizer["Error normalizer"]
  node_models["Payment models<br/>[models.py]"]
end

subgraph group_decision["Recovery decisions"]
  node_engine["Recovery pipeline<br/>[pipeline.py]"]
  node_security["Notes sanitizer<br/>[security.py]"]
  node_strategies["Decision strategies<br/>[strategies.py]"]
  node_cache[("LLM decision cache")]
end

subgraph group_evaluation["Simulation and benchmarks"]
  node_outcomes["Outcome simulator<br/>[outcome_model.py]"]
  node_benchmark["Benchmark runner<br/>[benchmark.py]"]
end

subgraph group_state["Persistence and reporting"]
  node_audit[("Audit ledger<br/>[audit_log.jsonl]")]
  node_escalations[("Escalation records<br/>[escalations.json]")]
  node_sqlite[("Webhook event ledger<br/>[app.py]")]
  node_report["Report generator"]
end

node_merchant(("Merchant / batch operator"))
node_razorpay(("Razorpay webhooks"))
node_gemini(("Gemini Flash"))

node_merchant -->|"provides records"| node_batch
node_batch -->|"processes batch"| node_engine
node_razorpay -->|"sends events"| node_webhook
node_webhook -->|"normalizes errors"| node_normalizer
node_webhook -->|"records events"| node_sqlite
node_webhook -->|"dispatches failure"| node_engine
node_engine -->|"validates records"| node_models
node_engine -->|"requests decision"| node_strategies
node_strategies -->|"sanitizes notes"| node_security
node_strategies -.->|"requests inference"| node_gemini
node_strategies -->|"reads and writes"| node_cache
node_strategies -->|"returns decision"| node_models
node_engine -->|"simulates action"| node_outcomes
node_engine -->|"appends audit"| node_audit
node_engine -->|"records escalations"| node_escalations
node_engine -->|"runs evaluations"| node_benchmark
node_benchmark -->|"scores outcomes"| node_outcomes
node_benchmark -->|"generates report"| node_report
node_webhook -->|"serves history"| node_sqlite

click node_batch "https://github.com/pavansaikavuri/failed-subscription-recovery-agent/blob/main/data/sample_batch.py"
click node_webhook "https://github.com/pavansaikavuri/failed-subscription-recovery-agent/blob/main/app.py"
click node_normalizer "https://github.com/pavansaikavuri/failed-subscription-recovery-agent/blob/main/error_normalizer.py"
click node_models "https://github.com/pavansaikavuri/failed-subscription-recovery-agent/blob/main/models.py"
click node_engine "https://github.com/pavansaikavuri/failed-subscription-recovery-agent/blob/main/pipeline.py"
click node_security "https://github.com/pavansaikavuri/failed-subscription-recovery-agent/blob/main/security.py"
click node_strategies "https://github.com/pavansaikavuri/failed-subscription-recovery-agent/blob/main/strategies.py"
click node_cache "https://github.com/pavansaikavuri/failed-subscription-recovery-agent/blob/main/llm_decision_cache.json"
click node_outcomes "https://github.com/pavansaikavuri/failed-subscription-recovery-agent/blob/main/outcome_model.py"
click node_benchmark "https://github.com/pavansaikavuri/failed-subscription-recovery-agent/blob/main/benchmark.py"
click node_audit "https://github.com/pavansaikavuri/failed-subscription-recovery-agent/blob/main/audit_log.jsonl"
click node_escalations "https://github.com/pavansaikavuri/failed-subscription-recovery-agent/blob/main/escalations.json"
click node_sqlite "https://github.com/pavansaikavuri/failed-subscription-recovery-agent/blob/main/app.py"
click node_report "https://github.com/pavansaikavuri/failed-subscription-recovery-agent/blob/main/report_generator.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_batch,node_webhook,node_normalizer,node_models toneBlue
class node_engine,node_security,node_strategies,node_cache toneAmber
class node_outcomes,node_benchmark,node_razorpay toneMint
class node_audit,node_escalations,node_sqlite,node_report toneRose
class node_merchant,node_gemini toneIndigo
```

## Components

### Intake and validation

- [Sample batch](https://github.com/pavansaikavuri/failed-subscription-recovery-agent/blob/main/data/sample_batch.py): `data/sample_batch.py`
- [Webhook receiver](https://github.com/pavansaikavuri/failed-subscription-recovery-agent/blob/main/app.py): `app.py`
- [Error normalizer](https://github.com/pavansaikavuri/failed-subscription-recovery-agent/blob/main/error_normalizer.py): `error_normalizer.py`
- [Payment models](https://github.com/pavansaikavuri/failed-subscription-recovery-agent/blob/main/models.py): `models.py`

### Recovery decisions

- [Recovery pipeline](https://github.com/pavansaikavuri/failed-subscription-recovery-agent/blob/main/pipeline.py): `pipeline.py`
- [Notes sanitizer](https://github.com/pavansaikavuri/failed-subscription-recovery-agent/blob/main/security.py): `security.py`
- [Decision strategies](https://github.com/pavansaikavuri/failed-subscription-recovery-agent/blob/main/strategies.py): `strategies.py`
- [LLM decision cache](https://github.com/pavansaikavuri/failed-subscription-recovery-agent/blob/main/llm_decision_cache.json): `llm_decision_cache.json`

### Simulation and benchmarks

- [Outcome simulator](https://github.com/pavansaikavuri/failed-subscription-recovery-agent/blob/main/outcome_model.py): `outcome_model.py`
- [Benchmark runner](https://github.com/pavansaikavuri/failed-subscription-recovery-agent/blob/main/benchmark.py): `benchmark.py`

### Persistence and reporting

- [Audit ledger](https://github.com/pavansaikavuri/failed-subscription-recovery-agent/blob/main/audit_log.jsonl): `audit_log.jsonl`
- [Escalation records](https://github.com/pavansaikavuri/failed-subscription-recovery-agent/blob/main/escalations.json): `escalations.json`
- [Webhook event ledger](https://github.com/pavansaikavuri/failed-subscription-recovery-agent/blob/main/app.py): `app.py`
- [Report generator](https://github.com/pavansaikavuri/failed-subscription-recovery-agent/blob/main/report_generator.py): `report_generator.py`

### Other components

- **Merchant / batch operator**
- **Razorpay webhooks**
- **Gemini Flash**

## Connections

- Merchant / batch operator → Sample batch: provides records
- Sample batch → Recovery pipeline: processes batch
- Razorpay webhooks → Webhook receiver: sends events
- Webhook receiver → Error normalizer: normalizes errors
- Webhook receiver → Webhook event ledger: records events
- Webhook receiver → Recovery pipeline: dispatches failure
- Recovery pipeline → Payment models: validates records
- Recovery pipeline → Decision strategies: requests decision
- Decision strategies → Notes sanitizer: sanitizes notes
- Decision strategies → Gemini Flash: requests inference
- Decision strategies → LLM decision cache: reads and writes
- Decision strategies → Payment models: returns decision
- Recovery pipeline → Outcome simulator: simulates action
- Recovery pipeline → Audit ledger: appends audit
- Recovery pipeline → Escalation records: records escalations
- Recovery pipeline → Benchmark runner: runs evaluations
- Benchmark runner → Outcome simulator: scores outcomes
- Benchmark runner → Report generator: generates report
- Webhook receiver → Webhook event ledger: serves history