# vaibhav-nhayade/recover-ai architecture

> Architecture diagram of the GitHub repository vaibhav-nhayade/recover-ai, 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/vaibhav-nhayade/recover-ai
- Repository: https://github.com/vaibhav-nhayade/recover-ai

## Overview

RecoverAI is a merchant-facing revenue recovery platform: merchants review failed transactions and recovery cases, while the backend scores cases, selects and checks interventions, executes recovery actions, records outcomes, and exposes audit and analytics views. The graph preserves the documented ML pipeline as a distinct capability; sampled code does not establish a runtime connection from that pipeline to backend scoring. Backend wiring is sampled in the recovery workflow and app entry point; frontend API-client wiring and several service integrations are not shown.

Main entry points: [`backend/app/main.py`](https://github.com/vaibhav-nhayade/recover-ai/blob/main/backend/app/main.py) (FastAPI application), [`backend/app/services/recovery_service.py`](https://github.com/vaibhav-nhayade/recover-ai/blob/main/backend/app/services/recovery_service.py) (Recovery orchestrator), [`backend/app/core/database.py`](https://github.com/vaibhav-nhayade/recover-ai/blob/main/backend/app/core/database.py) (Relational database), [`frontend/src/app/(authenticated)/layout.tsx`](https://github.com/vaibhav-nhayade/recover-ai/blob/main/frontend/src/app/(authenticated)/layout.tsx) (Web application)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_merchant_ui["Merchant experience"]
  node_web_app["Web application<br/>[layout.tsx]"]
  node_case_views["Recovery case views<br/>[page.tsx]"]
  node_case_hook["Case data hook<br/>[useRecoveryCase.ts]"]
  node_auth_guard["Auth guard<br/>[AuthGuard.tsx]"]
end

subgraph group_api_data["API and records"]
  node_api["FastAPI application<br/>[main.py]"]
  node_auth_routes["Merchant authentication<br/>[auth.py]"]
  node_transaction_routes["Transactions API<br/>[transactions.py]"]
  node_case_routes["Recovery cases API<br/>[recovery_cases.py]"]
  node_recovery_routes["Agent and batch APIs<br/>[recovery_agent.py]"]
  node_outcome_routes["Outcome API"]
  node_database[("Relational database<br/>[database.py]")]
end

subgraph group_recovery["Recovery decisions"]
  node_case_service["Case eligibility"]
  node_recovery_service["Recovery orchestrator"]
  node_scoring["Recovery scoring"]
  node_ranking["Intervention ranking"]
  node_retry["Retry controls<br/>[recovery_retry.py]"]
  node_message["Recovery messaging"]
  node_provider["Provider selection"]
  node_provider_service["Recovery provider"]
  node_result["Outcome application<br/>[recovery_result.py]"]
end

subgraph group_insight["Audit and insight"]
  node_audit_routes["Audit API<br/>[audit.py]"]
  node_audit_service["Audit records<br/>[audit_service.py]"]
  node_analytics_routes["Analytics API<br/>[analytics.py]"]
  node_analytics_service["Analytics service"]
end

subgraph group_ml["ML pipeline"]
  node_ml_training["Model training"]
  node_ml_model["Recovery model<br/>[recovery_model.py]"]
  node_ml_inference["Model inference"]
end

node_merchant(("Merchant"))
node_external_provider{{"Recovery provider service"}}

node_merchant -->|"uses"| node_web_app
node_web_app -->|"guards pages"| node_auth_guard
node_web_app -->|"presents cases"| node_case_views
node_case_views -->|"loads details"| node_case_hook
node_case_hook -->|"requests data"| node_api
node_api -->|"mounts routes"| node_auth_routes
node_api -->|"mounts routes"| node_transaction_routes
node_api -->|"mounts routes"| node_case_routes
node_api -->|"mounts routes"| node_recovery_routes
node_api -->|"mounts routes"| node_outcome_routes
node_api -->|"mounts routes"| node_audit_routes
node_api -->|"mounts routes"| node_analytics_routes
node_case_routes -->|"delegates"| node_case_service
node_case_service -->|"reads/writes"| node_database
node_recovery_routes -->|"dispatches"| node_recovery_service
node_recovery_service -->|"reads/writes"| node_database
node_recovery_service -->|"checks retries"| node_retry
node_recovery_service -->|"scores transaction"| node_scoring
node_recovery_service -->|"ranks interventions"| node_ranking
node_recovery_service -->|"generates message"| node_message
node_recovery_service -->|"selects provider"| node_provider
node_provider -->|"returns provider"| node_provider_service
node_provider_service -.->|"executes action"| node_external_provider
node_recovery_service -->|"applies result"| node_result
node_result -->|"persists outcome"| node_database
node_audit_routes -->|"queries events"| node_audit_service
node_audit_service -->|"reads/writes"| node_database
node_analytics_routes -->|"delegates"| node_analytics_service
node_analytics_service -->|"reads records"| node_database
node_ml_training -->|"trains"| node_ml_model
node_ml_inference -->|"loads model"| node_ml_model

click node_web_app "https://github.com/vaibhav-nhayade/recover-ai/blob/main/frontend/src/app/(authenticated)/layout.tsx"
click node_case_views "https://github.com/vaibhav-nhayade/recover-ai/blob/main/frontend/src/app/(authenticated)/recovery/%5BcaseId%5D/page.tsx"
click node_case_hook "https://github.com/vaibhav-nhayade/recover-ai/blob/main/frontend/src/hooks/useRecoveryCase.ts"
click node_auth_guard "https://github.com/vaibhav-nhayade/recover-ai/blob/main/frontend/src/components/auth/AuthGuard.tsx"
click node_api "https://github.com/vaibhav-nhayade/recover-ai/blob/main/backend/app/main.py"
click node_auth_routes "https://github.com/vaibhav-nhayade/recover-ai/blob/main/backend/app/api/v1/auth.py"
click node_transaction_routes "https://github.com/vaibhav-nhayade/recover-ai/blob/main/backend/app/api/v1/transactions.py"
click node_case_routes "https://github.com/vaibhav-nhayade/recover-ai/blob/main/backend/app/api/v1/recovery_cases.py"
click node_case_service "https://github.com/vaibhav-nhayade/recover-ai/blob/main/backend/app/services/recovery_case_service.py"
click node_recovery_routes "https://github.com/vaibhav-nhayade/recover-ai/blob/main/backend/app/api/v1/recovery_agent.py"
click node_recovery_service "https://github.com/vaibhav-nhayade/recover-ai/blob/main/backend/app/services/recovery_service.py"
click node_scoring "https://github.com/vaibhav-nhayade/recover-ai/blob/main/backend/app/services/recovery_scoring.py"
click node_ranking "https://github.com/vaibhav-nhayade/recover-ai/blob/main/backend/app/services/intervention_ranker.py"
click node_retry "https://github.com/vaibhav-nhayade/recover-ai/blob/main/backend/app/services/recovery_retry.py"
click node_message "https://github.com/vaibhav-nhayade/recover-ai/blob/main/backend/app/services/recovery_message.py"
click node_provider "https://github.com/vaibhav-nhayade/recover-ai/blob/main/backend/app/services/provider_factory.py"
click node_provider_service "https://github.com/vaibhav-nhayade/recover-ai/blob/main/backend/app/services/recovery_provider.py"
click node_result "https://github.com/vaibhav-nhayade/recover-ai/blob/main/backend/app/services/recovery_result.py"
click node_outcome_routes "https://github.com/vaibhav-nhayade/recover-ai/blob/main/backend/app/api/v1/recovery_outcomes.py"
click node_audit_routes "https://github.com/vaibhav-nhayade/recover-ai/blob/main/backend/app/api/v1/audit.py"
click node_audit_service "https://github.com/vaibhav-nhayade/recover-ai/blob/main/backend/app/services/audit_service.py"
click node_analytics_routes "https://github.com/vaibhav-nhayade/recover-ai/blob/main/backend/app/api/v1/analytics.py"
click node_analytics_service "https://github.com/vaibhav-nhayade/recover-ai/blob/main/backend/app/services/analytics_service.py"
click node_database "https://github.com/vaibhav-nhayade/recover-ai/blob/main/backend/app/core/database.py"
click node_ml_training "https://github.com/vaibhav-nhayade/recover-ai/blob/main/ml/training/train_recovery_model.py"
click node_ml_model "https://github.com/vaibhav-nhayade/recover-ai/blob/main/ml/models/recovery_model.py"
click node_ml_inference "https://github.com/vaibhav-nhayade/recover-ai/blob/main/ml/inference/predict_recovery.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_web_app,node_case_views,node_case_hook,node_auth_guard toneBlue
class node_api,node_auth_routes,node_transaction_routes,node_case_routes,node_recovery_routes,node_outcome_routes,node_database toneAmber
class node_case_service,node_recovery_service,node_scoring,node_ranking,node_retry,node_message,node_provider,node_provider_service,node_result toneMint
class node_audit_routes,node_audit_service,node_analytics_routes,node_analytics_service toneRose
class node_ml_training,node_ml_model,node_ml_inference,node_merchant,node_external_provider toneIndigo
```

## Components

### Merchant experience

- [Web application](https://github.com/vaibhav-nhayade/recover-ai/blob/main/frontend/src/app/(authenticated)/layout.tsx): `frontend/src/app/(authenticated)/layout.tsx`
- [Recovery case views](https://github.com/vaibhav-nhayade/recover-ai/blob/main/frontend/src/app/(authenticated)/recovery/%5BcaseId%5D/page.tsx): `frontend/src/app/(authenticated)/recovery/[caseId]/page.tsx`
- [Case data hook](https://github.com/vaibhav-nhayade/recover-ai/blob/main/frontend/src/hooks/useRecoveryCase.ts): `frontend/src/hooks/useRecoveryCase.ts`
- [Auth guard](https://github.com/vaibhav-nhayade/recover-ai/blob/main/frontend/src/components/auth/AuthGuard.tsx): `frontend/src/components/auth/AuthGuard.tsx`

### API and records

- [FastAPI application](https://github.com/vaibhav-nhayade/recover-ai/blob/main/backend/app/main.py): `backend/app/main.py`
- [Merchant authentication](https://github.com/vaibhav-nhayade/recover-ai/blob/main/backend/app/api/v1/auth.py): `backend/app/api/v1/auth.py`
- [Transactions API](https://github.com/vaibhav-nhayade/recover-ai/blob/main/backend/app/api/v1/transactions.py): `backend/app/api/v1/transactions.py`
- [Recovery cases API](https://github.com/vaibhav-nhayade/recover-ai/blob/main/backend/app/api/v1/recovery_cases.py): `backend/app/api/v1/recovery_cases.py`
- [Agent and batch APIs](https://github.com/vaibhav-nhayade/recover-ai/blob/main/backend/app/api/v1/recovery_agent.py): `backend/app/api/v1/recovery_agent.py`
- [Outcome API](https://github.com/vaibhav-nhayade/recover-ai/blob/main/backend/app/api/v1/recovery_outcomes.py): `backend/app/api/v1/recovery_outcomes.py`
- [Relational database](https://github.com/vaibhav-nhayade/recover-ai/blob/main/backend/app/core/database.py): `backend/app/core/database.py`

### Recovery decisions

- [Case eligibility](https://github.com/vaibhav-nhayade/recover-ai/blob/main/backend/app/services/recovery_case_service.py): `backend/app/services/recovery_case_service.py`
- [Recovery orchestrator](https://github.com/vaibhav-nhayade/recover-ai/blob/main/backend/app/services/recovery_service.py): `backend/app/services/recovery_service.py`
- [Recovery scoring](https://github.com/vaibhav-nhayade/recover-ai/blob/main/backend/app/services/recovery_scoring.py): `backend/app/services/recovery_scoring.py`
- [Intervention ranking](https://github.com/vaibhav-nhayade/recover-ai/blob/main/backend/app/services/intervention_ranker.py): `backend/app/services/intervention_ranker.py`
- [Retry controls](https://github.com/vaibhav-nhayade/recover-ai/blob/main/backend/app/services/recovery_retry.py): `backend/app/services/recovery_retry.py`
- [Recovery messaging](https://github.com/vaibhav-nhayade/recover-ai/blob/main/backend/app/services/recovery_message.py): `backend/app/services/recovery_message.py`
- [Provider selection](https://github.com/vaibhav-nhayade/recover-ai/blob/main/backend/app/services/provider_factory.py): `backend/app/services/provider_factory.py`
- [Recovery provider](https://github.com/vaibhav-nhayade/recover-ai/blob/main/backend/app/services/recovery_provider.py): `backend/app/services/recovery_provider.py`
- [Outcome application](https://github.com/vaibhav-nhayade/recover-ai/blob/main/backend/app/services/recovery_result.py): `backend/app/services/recovery_result.py`

### Audit and insight

- [Audit API](https://github.com/vaibhav-nhayade/recover-ai/blob/main/backend/app/api/v1/audit.py): `backend/app/api/v1/audit.py`
- [Audit records](https://github.com/vaibhav-nhayade/recover-ai/blob/main/backend/app/services/audit_service.py): `backend/app/services/audit_service.py`
- [Analytics API](https://github.com/vaibhav-nhayade/recover-ai/blob/main/backend/app/api/v1/analytics.py): `backend/app/api/v1/analytics.py`
- [Analytics service](https://github.com/vaibhav-nhayade/recover-ai/blob/main/backend/app/services/analytics_service.py): `backend/app/services/analytics_service.py`

### ML pipeline

- [Model training](https://github.com/vaibhav-nhayade/recover-ai/blob/main/ml/training/train_recovery_model.py): `ml/training/train_recovery_model.py`
- [Recovery model](https://github.com/vaibhav-nhayade/recover-ai/blob/main/ml/models/recovery_model.py): `ml/models/recovery_model.py`
- [Model inference](https://github.com/vaibhav-nhayade/recover-ai/blob/main/ml/inference/predict_recovery.py): `ml/inference/predict_recovery.py`

### Other components

- **Merchant**
- **Recovery provider service**

## Connections

- Merchant → Web application: uses
- Web application → Auth guard: guards pages
- Web application → Recovery case views: presents cases
- Recovery case views → Case data hook: loads details
- Case data hook → FastAPI application: requests data
- FastAPI application → Merchant authentication: mounts routes
- FastAPI application → Transactions API: mounts routes
- FastAPI application → Recovery cases API: mounts routes
- FastAPI application → Agent and batch APIs: mounts routes
- FastAPI application → Outcome API: mounts routes
- FastAPI application → Audit API: mounts routes
- FastAPI application → Analytics API: mounts routes
- Recovery cases API → Case eligibility: delegates
- Case eligibility → Relational database: reads/writes
- Agent and batch APIs → Recovery orchestrator: dispatches
- Recovery orchestrator → Relational database: reads/writes
- Recovery orchestrator → Retry controls: checks retries
- Recovery orchestrator → Recovery scoring: scores transaction
- Recovery orchestrator → Intervention ranking: ranks interventions
- Recovery orchestrator → Recovery messaging: generates message
- Recovery orchestrator → Provider selection: selects provider
- Provider selection → Recovery provider: returns provider
- Recovery provider → Recovery provider service: executes action
- Recovery orchestrator → Outcome application: applies result
- Outcome application → Relational database: persists outcome
- Audit API → Audit records: queries events
- Audit records → Relational database: reads/writes
- Analytics API → Analytics service: delegates
- Analytics service → Relational database: reads records
- Model training → Recovery model: trains
- Model inference → Recovery model: loads model