# piyush2676/recoverx architecture

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

- Interactive diagram: https://gitdiagram.com/piyush2676/recoverx
- Repository: https://github.com/piyush2676/recoverx

## Overview

RecoverX is a failed-payment recovery agent: it classifies gateway errors, applies deterministic safety and timing gates, executes eligible recovery actions, and audits outcomes. Its principal workflow is documented in the README; sampled source confirms validation and caching for the model classifier, policy gates, Razorpay idempotency, ledger persistence, and dashboard ledger reads. Batch generation and evaluation are major product capabilities too. Some runner wiring is unsampled, so uncertain call links are omitted.

Main entry points: [`src/main/java/com/recoverx/eval/ExecutionRunner.java`](https://github.com/piyush2676/recoverx/blob/main/src/main/java/com/recoverx/eval/ExecutionRunner.java) (Execution runner), [`src/main/java/com/recoverx/RecoverXApplication.java`](https://github.com/piyush2676/recoverx/blob/main/src/main/java/com/recoverx/RecoverXApplication.java) (Application entry), [`src/main/java/com/recoverx/classify/LlmClassifier.java`](https://github.com/piyush2676/recoverx/blob/main/src/main/java/com/recoverx/classify/LlmClassifier.java) (LLM classifier), [`src/main/java/com/recoverx/policy/DefaultRecoveryPolicy.java`](https://github.com/piyush2676/recoverx/blob/main/src/main/java/com/recoverx/policy/DefaultRecoveryPolicy.java) (Recovery policy)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_batch["Batch data"]
  node_generator["Synthetic generator"]
  node_transactions["Transaction model"]
end

subgraph group_recovery["Recovery workflow"]
  node_app["Application entry"]
  node_cycle["Recovery cycle<br/>[RecoveryCycle.java]"]
  node_execution["Execution runner"]
  node_policy["Recovery policy"]
  node_decision["Recovery decision"]
  node_executor["Recovery executor"]
  node_razorpay["Razorpay adapter"]
end

subgraph group_audit["Audit and reporting"]
  node_ledger[("Append-only ledger<br/>[JsonlLedger.java]")]
  node_eval["Evaluation harness"]
  node_scorer["Classification scorer"]
  node_dashboard["Dashboard API"]
end

subgraph group_classification["Classification"]
  node_classifier["Classifier interface"]
  node_rules["Rule classifier"]
  node_llm["LLM classifier<br/>[LlmClassifier.java]"]
  node_provider["Gemini provider"]
  node_parser["Response validator"]
  node_cache[("Classification cache")]
end

node_operator(("Batch operator"))
node_gateway{{"Razorpay API"}}

node_operator -->|"starts mode"| node_app
node_app -->|"runs generation"| node_generator
node_generator -->|"creates records"| node_transactions
node_app -->|"runs batch"| node_execution
node_app -->|"runs comparison"| node_eval
node_execution -->|"classifies transactions"| node_classifier
node_execution -->|"requests decisions"| node_policy
node_execution -->|"executes decisions"| node_executor
node_execution -->|"reads and records"| node_ledger
node_classifier -->|"rule implementation"| node_rules
node_classifier -->|"model implementation"| node_llm
node_llm -.->|"optional model calls"| node_provider
node_llm -->|"validates response"| node_parser
node_llm -->|"reads and writes"| node_cache
node_policy -->|"checks pending attempts"| node_ledger
node_policy -->|"produces decision"| node_decision
node_executor -->|"dispatches action"| node_razorpay
node_razorpay -->|"sends payment request"| node_gateway
node_eval -->|"scores classifications"| node_scorer
node_eval -->|"runs recovery arms"| node_cycle
node_dashboard -->|"reads ledger file"| node_ledger

click node_app "https://github.com/piyush2676/recoverx/blob/main/src/main/java/com/recoverx/RecoverXApplication.java"
click node_generator "https://github.com/piyush2676/recoverx/blob/main/src/main/java/com/recoverx/datagen/SyntheticDataGenerator.java"
click node_transactions "https://github.com/piyush2676/recoverx/blob/main/src/main/java/com/recoverx/domain/FailedTransaction.java"
click node_cycle "https://github.com/piyush2676/recoverx/blob/main/src/main/java/com/recoverx/eval/RecoveryCycle.java"
click node_execution "https://github.com/piyush2676/recoverx/blob/main/src/main/java/com/recoverx/eval/ExecutionRunner.java"
click node_classifier "https://github.com/piyush2676/recoverx/blob/main/src/main/java/com/recoverx/classify/FailureClassifier.java"
click node_rules "https://github.com/piyush2676/recoverx/blob/main/src/main/java/com/recoverx/classify/RuleBasedClassifier.java"
click node_llm "https://github.com/piyush2676/recoverx/blob/main/src/main/java/com/recoverx/classify/LlmClassifier.java"
click node_provider "https://github.com/piyush2676/recoverx/blob/main/src/main/java/com/recoverx/classify/GeminiClassifier.java"
click node_parser "https://github.com/piyush2676/recoverx/blob/main/src/main/java/com/recoverx/classify/ResponseParser.java"
click node_cache "https://github.com/piyush2676/recoverx/blob/main/src/main/java/com/recoverx/classify/ClassificationCache.java"
click node_policy "https://github.com/piyush2676/recoverx/blob/main/src/main/java/com/recoverx/policy/DefaultRecoveryPolicy.java"
click node_decision "https://github.com/piyush2676/recoverx/blob/main/src/main/java/com/recoverx/policy/RecoveryDecision.java"
click node_executor "https://github.com/piyush2676/recoverx/blob/main/src/main/java/com/recoverx/executor/RecoveryExecutor.java"
click node_razorpay "https://github.com/piyush2676/recoverx/blob/main/src/main/java/com/recoverx/executor/RazorpayExecutor.java"
click node_ledger "https://github.com/piyush2676/recoverx/blob/main/src/main/java/com/recoverx/ledger/JsonlLedger.java"
click node_eval "https://github.com/piyush2676/recoverx/blob/main/src/main/java/com/recoverx/eval/ComparisonRunner.java"
click node_scorer "https://github.com/piyush2676/recoverx/blob/main/src/main/java/com/recoverx/eval/ClassificationScorer.java"
click node_dashboard "https://github.com/piyush2676/recoverx/blob/main/src/main/java/com/recoverx/dashboard/DashboardController.java"

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_generator,node_transactions toneBlue
class node_app,node_cycle,node_execution,node_policy,node_decision,node_executor,node_razorpay toneAmber
class node_ledger,node_eval,node_scorer,node_dashboard,node_gateway toneMint
class node_classifier,node_rules,node_llm,node_provider,node_parser,node_cache toneRose
class node_operator toneIndigo
```

## Components

### Batch data

- [Synthetic generator](https://github.com/piyush2676/recoverx/blob/main/src/main/java/com/recoverx/datagen/SyntheticDataGenerator.java): `src/main/java/com/recoverx/datagen/SyntheticDataGenerator.java`
- [Transaction model](https://github.com/piyush2676/recoverx/blob/main/src/main/java/com/recoverx/domain/FailedTransaction.java): `src/main/java/com/recoverx/domain/FailedTransaction.java`

### Recovery workflow

- [Application entry](https://github.com/piyush2676/recoverx/blob/main/src/main/java/com/recoverx/RecoverXApplication.java): `src/main/java/com/recoverx/RecoverXApplication.java`
- [Recovery cycle](https://github.com/piyush2676/recoverx/blob/main/src/main/java/com/recoverx/eval/RecoveryCycle.java): `src/main/java/com/recoverx/eval/RecoveryCycle.java`
- [Execution runner](https://github.com/piyush2676/recoverx/blob/main/src/main/java/com/recoverx/eval/ExecutionRunner.java): `src/main/java/com/recoverx/eval/ExecutionRunner.java`
- [Recovery policy](https://github.com/piyush2676/recoverx/blob/main/src/main/java/com/recoverx/policy/DefaultRecoveryPolicy.java): `src/main/java/com/recoverx/policy/DefaultRecoveryPolicy.java`
- [Recovery decision](https://github.com/piyush2676/recoverx/blob/main/src/main/java/com/recoverx/policy/RecoveryDecision.java): `src/main/java/com/recoverx/policy/RecoveryDecision.java`
- [Recovery executor](https://github.com/piyush2676/recoverx/blob/main/src/main/java/com/recoverx/executor/RecoveryExecutor.java): `src/main/java/com/recoverx/executor/RecoveryExecutor.java`
- [Razorpay adapter](https://github.com/piyush2676/recoverx/blob/main/src/main/java/com/recoverx/executor/RazorpayExecutor.java): `src/main/java/com/recoverx/executor/RazorpayExecutor.java`

### Audit and reporting

- [Append-only ledger](https://github.com/piyush2676/recoverx/blob/main/src/main/java/com/recoverx/ledger/JsonlLedger.java): `src/main/java/com/recoverx/ledger/JsonlLedger.java`
- [Evaluation harness](https://github.com/piyush2676/recoverx/blob/main/src/main/java/com/recoverx/eval/ComparisonRunner.java): `src/main/java/com/recoverx/eval/ComparisonRunner.java`
- [Classification scorer](https://github.com/piyush2676/recoverx/blob/main/src/main/java/com/recoverx/eval/ClassificationScorer.java): `src/main/java/com/recoverx/eval/ClassificationScorer.java`
- [Dashboard API](https://github.com/piyush2676/recoverx/blob/main/src/main/java/com/recoverx/dashboard/DashboardController.java): `src/main/java/com/recoverx/dashboard/DashboardController.java`

### Classification

- [Classifier interface](https://github.com/piyush2676/recoverx/blob/main/src/main/java/com/recoverx/classify/FailureClassifier.java): `src/main/java/com/recoverx/classify/FailureClassifier.java`
- [Rule classifier](https://github.com/piyush2676/recoverx/blob/main/src/main/java/com/recoverx/classify/RuleBasedClassifier.java): `src/main/java/com/recoverx/classify/RuleBasedClassifier.java`
- [LLM classifier](https://github.com/piyush2676/recoverx/blob/main/src/main/java/com/recoverx/classify/LlmClassifier.java): `src/main/java/com/recoverx/classify/LlmClassifier.java`
- [Gemini provider](https://github.com/piyush2676/recoverx/blob/main/src/main/java/com/recoverx/classify/GeminiClassifier.java): `src/main/java/com/recoverx/classify/GeminiClassifier.java`
- [Response validator](https://github.com/piyush2676/recoverx/blob/main/src/main/java/com/recoverx/classify/ResponseParser.java): `src/main/java/com/recoverx/classify/ResponseParser.java`
- [Classification cache](https://github.com/piyush2676/recoverx/blob/main/src/main/java/com/recoverx/classify/ClassificationCache.java): `src/main/java/com/recoverx/classify/ClassificationCache.java`

### Other components

- **Batch operator**
- **Razorpay API**

## Connections

- Batch operator → Application entry: starts mode
- Application entry → Synthetic generator: runs generation
- Synthetic generator → Transaction model: creates records
- Application entry → Execution runner: runs batch
- Application entry → Evaluation harness: runs comparison
- Execution runner → Classifier interface: classifies transactions
- Execution runner → Recovery policy: requests decisions
- Execution runner → Recovery executor: executes decisions
- Execution runner → Append-only ledger: reads and records
- Classifier interface → Rule classifier: rule implementation
- Classifier interface → LLM classifier: model implementation
- LLM classifier → Gemini provider: optional model calls
- LLM classifier → Response validator: validates response
- LLM classifier → Classification cache: reads and writes
- Recovery policy → Append-only ledger: checks pending attempts
- Recovery policy → Recovery decision: produces decision
- Recovery executor → Razorpay adapter: dispatches action
- Razorpay adapter → Razorpay API: sends payment request
- Evaluation harness → Classification scorer: scores classifications
- Evaluation harness → Recovery cycle: runs recovery arms
- Dashboard API → Append-only ledger: reads ledger file