# v1629/x.a.v.i.e.r. architecture

> Architecture diagram of the GitHub repository v1629/x.a.v.i.e.r., generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/v1629/x.a.v.i.e.r.
- Repository: https://github.com/v1629/x.a.v.i.e.r.

## Overview

X.A.V.I.E.R. is a payment-failure recovery product with a React operations UI and a FastAPI agent backend. Its principal workflow accepts failures from payment reports or Razorpay webhooks, processes eligible transactions through detection, governance, diagnosis, notification and recovery strategy execution, then records outcomes and streams updates. The README also describes gateway-health fallback routing, customer nudges and safeguards. Several backend relationships are grounded in excerpts or the source index; unsampled UI and API details are represented only where documented or indexed, so uncertain links are omitted.

Main entry points: [`server/app/api/routes.py`](https://github.com/v1629/x.a.v.i.e.r./blob/main/server/app/api/routes.py) (Payment & API Routes), [`server/app/agent/orchestrator.py`](https://github.com/v1629/x.a.v.i.e.r./blob/main/server/app/agent/orchestrator.py) (Recovery Orchestrator), [`server/app/agent/actions.py`](https://github.com/v1629/x.a.v.i.e.r./blob/main/server/app/agent/actions.py) (Recovery Actions), [`client/src/App.jsx`](https://github.com/v1629/x.a.v.i.e.r./blob/main/client/src/App.jsx) (React Application)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Failure Intake"]
  node_routes["Payment &amp; API Routes<br/>[routes.py]"]
  node_transactions[("Transaction Store")]
end

subgraph group_agent["Recovery Agent"]
  node_orchestrator["Recovery Orchestrator<br/>[orchestrator.py]"]
  node_detector["Failure Detector<br/>[detector.py]"]
  node_diagnoser["AI Diagnoser<br/>[diagnoser.py]"]
  node_knowledge[("Error Knowledge Base<br/>[kb_retriever.py]")]
  node_groq["Groq Client<br/>[groq_client.py]"]
  node_prompts["AI Prompts<br/>[prompts.py]"]
  node_strategies["Recovery Strategies<br/>[strategies.py]"]
  node_actions["Recovery Actions<br/>[actions.py]"]
  node_gateway_monitor["Gateway Health Monitor<br/>[gateway_monitor.py]"]
end

subgraph group_governance["Governance &amp; Audit"]
  node_governance_rules["Governance Rules<br/>[rules.py]"]
  node_audit_logger["Audit Logger<br/>[audit_logger.py]"]
  node_audit_store[("Audit Store<br/>[audit_store.py]")]
end

subgraph group_api["API &amp; Events"]
  node_sse["SSE Manager<br/>[sse_manager.py]"]
end

subgraph group_ui["Operations UI"]
  node_frontend_app["React Application<br/>[App.jsx]"]
  node_agent_page["Agent Console<br/>[AgentPage.jsx]"]
  node_sse_hook["SSE Hook<br/>[useSSE.js]"]
  node_dashboard["Recovery Dashboard<br/>[DashboardPage.jsx]"]
  node_store_page["Store Checkout<br/>[StorePage.jsx]"]
  node_audit_page["Audit View<br/>[AuditPage.jsx]"]
  node_settings_page["Settings View<br/>[SettingsPage.jsx]"]
end

node_gateway(("Payment Gateways"))
node_customer(("Customer"))
node_groq_service["Groq AI Service"]
node_stripe["Stripe Checkout"]
node_resend["Resend Email"]

node_gateway -->|"reports failures"| node_routes
node_customer -->|"reports failure"| node_routes
node_routes -->|"stores transactions"| node_transactions
node_routes -->|"starts batch"| node_orchestrator
node_orchestrator -->|"detects failures"| node_detector
node_orchestrator -->|"checks limits"| node_governance_rules
node_orchestrator -->|"requests diagnosis"| node_diagnoser
node_diagnoser -->|"retrieves patterns"| node_knowledge
node_diagnoser -->|"analyzes errors"| node_groq
node_diagnoser -->|"uses prompts"| node_prompts
node_groq -->|"calls model"| node_groq_service
node_orchestrator -->|"dispatches notification"| node_actions
node_actions -->|"generates nudge"| node_groq
node_actions -->|"builds nudge"| node_prompts
node_actions -->|"sends email"| node_resend
node_orchestrator -->|"selects strategy"| node_strategies
node_strategies -->|"invokes actions"| node_actions
node_actions -->|"creates fallback"| node_stripe
node_actions -->|"broadcasts fallback"| node_sse
node_orchestrator -->|"updates outcomes"| node_transactions
node_orchestrator -->|"broadcasts status"| node_sse
node_orchestrator -->|"records actions"| node_audit_logger
node_audit_logger -->|"persists entries"| node_audit_store
node_routes -->|"streams events"| node_sse
node_routes -->|"reads health"| node_gateway_monitor
node_frontend_app -->|"routes to"| node_agent_page
node_frontend_app -->|"routes to"| node_dashboard
node_frontend_app -->|"routes to"| node_settings_page
node_frontend_app -->|"routes to"| node_store_page
node_agent_page -->|"subscribes events"| node_sse_hook
node_sse_hook -.->|"receives stream"| node_sse
node_agent_page -.->|"starts recovery batch"| node_routes
node_frontend_app -->|"toggles kill switch"| node_routes
node_audit_page -.->|"loads audit entries"| node_routes
node_dashboard -.->|"loads metrics"| node_routes
node_store_page -.->|"uses payment API"| node_routes
node_customer -->|"opens recovery link"| node_routes
node_routes -->|"marks recovered"| node_transactions

click node_routes "https://github.com/v1629/x.a.v.i.e.r./blob/main/server/app/api/routes.py"
click node_transactions "https://github.com/v1629/x.a.v.i.e.r./blob/main/server/app/data/transaction_store.py"
click node_orchestrator "https://github.com/v1629/x.a.v.i.e.r./blob/main/server/app/agent/orchestrator.py"
click node_detector "https://github.com/v1629/x.a.v.i.e.r./blob/main/server/app/agent/detector.py"
click node_diagnoser "https://github.com/v1629/x.a.v.i.e.r./blob/main/server/app/agent/diagnoser.py"
click node_knowledge "https://github.com/v1629/x.a.v.i.e.r./blob/main/server/app/ai/kb_retriever.py"
click node_groq "https://github.com/v1629/x.a.v.i.e.r./blob/main/server/app/ai/groq_client.py"
click node_prompts "https://github.com/v1629/x.a.v.i.e.r./blob/main/server/app/ai/prompts.py"
click node_strategies "https://github.com/v1629/x.a.v.i.e.r./blob/main/server/app/agent/strategies.py"
click node_actions "https://github.com/v1629/x.a.v.i.e.r./blob/main/server/app/agent/actions.py"
click node_gateway_monitor "https://github.com/v1629/x.a.v.i.e.r./blob/main/server/app/agent/gateway_monitor.py"
click node_governance_rules "https://github.com/v1629/x.a.v.i.e.r./blob/main/server/app/governance/rules.py"
click node_audit_logger "https://github.com/v1629/x.a.v.i.e.r./blob/main/server/app/audit/audit_logger.py"
click node_audit_store "https://github.com/v1629/x.a.v.i.e.r./blob/main/server/app/data/audit_store.py"
click node_sse "https://github.com/v1629/x.a.v.i.e.r./blob/main/server/app/api/sse_manager.py"
click node_frontend_app "https://github.com/v1629/x.a.v.i.e.r./blob/main/client/src/App.jsx"
click node_agent_page "https://github.com/v1629/x.a.v.i.e.r./blob/main/client/src/pages/AgentPage.jsx"
click node_sse_hook "https://github.com/v1629/x.a.v.i.e.r./blob/main/client/src/hooks/useSSE.js"
click node_dashboard "https://github.com/v1629/x.a.v.i.e.r./blob/main/client/src/pages/DashboardPage.jsx"
click node_store_page "https://github.com/v1629/x.a.v.i.e.r./blob/main/client/src/pages/StorePage.jsx"
click node_audit_page "https://github.com/v1629/x.a.v.i.e.r./blob/main/client/src/pages/AuditPage.jsx"
click node_settings_page "https://github.com/v1629/x.a.v.i.e.r./blob/main/client/src/pages/SettingsPage.jsx"

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_routes,node_transactions toneBlue
class node_orchestrator,node_detector,node_diagnoser,node_knowledge,node_groq,node_prompts,node_strategies,node_actions,node_gateway_monitor toneAmber
class node_governance_rules,node_audit_logger,node_audit_store toneMint
class node_sse toneRose
class node_frontend_app,node_agent_page,node_sse_hook,node_dashboard,node_store_page,node_audit_page,node_settings_page,node_gateway,node_customer,node_groq_service,node_stripe,node_resend toneIndigo
```

## Components

### Failure Intake

- [Payment & API Routes](https://github.com/v1629/x.a.v.i.e.r./blob/main/server/app/api/routes.py): `server/app/api/routes.py`
- [Transaction Store](https://github.com/v1629/x.a.v.i.e.r./blob/main/server/app/data/transaction_store.py): `server/app/data/transaction_store.py`

### Recovery Agent

- [Recovery Orchestrator](https://github.com/v1629/x.a.v.i.e.r./blob/main/server/app/agent/orchestrator.py): `server/app/agent/orchestrator.py`
- [Failure Detector](https://github.com/v1629/x.a.v.i.e.r./blob/main/server/app/agent/detector.py): `server/app/agent/detector.py`
- [AI Diagnoser](https://github.com/v1629/x.a.v.i.e.r./blob/main/server/app/agent/diagnoser.py): `server/app/agent/diagnoser.py`
- [Error Knowledge Base](https://github.com/v1629/x.a.v.i.e.r./blob/main/server/app/ai/kb_retriever.py): `server/app/ai/kb_retriever.py`
- [Groq Client](https://github.com/v1629/x.a.v.i.e.r./blob/main/server/app/ai/groq_client.py): `server/app/ai/groq_client.py`
- [AI Prompts](https://github.com/v1629/x.a.v.i.e.r./blob/main/server/app/ai/prompts.py): `server/app/ai/prompts.py`
- [Recovery Strategies](https://github.com/v1629/x.a.v.i.e.r./blob/main/server/app/agent/strategies.py): `server/app/agent/strategies.py`
- [Recovery Actions](https://github.com/v1629/x.a.v.i.e.r./blob/main/server/app/agent/actions.py): `server/app/agent/actions.py`
- [Gateway Health Monitor](https://github.com/v1629/x.a.v.i.e.r./blob/main/server/app/agent/gateway_monitor.py): `server/app/agent/gateway_monitor.py`

### Governance & Audit

- [Governance Rules](https://github.com/v1629/x.a.v.i.e.r./blob/main/server/app/governance/rules.py): `server/app/governance/rules.py`
- [Audit Logger](https://github.com/v1629/x.a.v.i.e.r./blob/main/server/app/audit/audit_logger.py): `server/app/audit/audit_logger.py`
- [Audit Store](https://github.com/v1629/x.a.v.i.e.r./blob/main/server/app/data/audit_store.py): `server/app/data/audit_store.py`

### API & Events

- [SSE Manager](https://github.com/v1629/x.a.v.i.e.r./blob/main/server/app/api/sse_manager.py): `server/app/api/sse_manager.py`

### Operations UI

- [React Application](https://github.com/v1629/x.a.v.i.e.r./blob/main/client/src/App.jsx): `client/src/App.jsx`
- [Agent Console](https://github.com/v1629/x.a.v.i.e.r./blob/main/client/src/pages/AgentPage.jsx): `client/src/pages/AgentPage.jsx`
- [SSE Hook](https://github.com/v1629/x.a.v.i.e.r./blob/main/client/src/hooks/useSSE.js): `client/src/hooks/useSSE.js`
- [Recovery Dashboard](https://github.com/v1629/x.a.v.i.e.r./blob/main/client/src/pages/DashboardPage.jsx): `client/src/pages/DashboardPage.jsx`
- [Store Checkout](https://github.com/v1629/x.a.v.i.e.r./blob/main/client/src/pages/StorePage.jsx): `client/src/pages/StorePage.jsx`
- [Audit View](https://github.com/v1629/x.a.v.i.e.r./blob/main/client/src/pages/AuditPage.jsx): `client/src/pages/AuditPage.jsx`
- [Settings View](https://github.com/v1629/x.a.v.i.e.r./blob/main/client/src/pages/SettingsPage.jsx): `client/src/pages/SettingsPage.jsx`

### Other components

- **Payment Gateways**
- **Customer**
- **Groq AI Service**
- **Stripe Checkout**
- **Resend Email**

## Connections

- Payment Gateways → Payment & API Routes: reports failures (evidence: `README.md`)
- Customer → Payment & API Routes: reports failure (evidence: `server/app/api/routes.py`)
- Payment & API Routes → Transaction Store: stores transactions (evidence: `server/app/api/routes.py`)
- Payment & API Routes → Recovery Orchestrator: starts batch (evidence: `server/app/api/routes.py`)
- Recovery Orchestrator → Failure Detector: detects failures (evidence: `server/app/agent/orchestrator.py`)
- Recovery Orchestrator → Governance Rules: checks limits (evidence: `server/app/agent/orchestrator.py`)
- Recovery Orchestrator → AI Diagnoser: requests diagnosis (evidence: `server/app/agent/orchestrator.py`)
- AI Diagnoser → Error Knowledge Base: retrieves patterns (evidence: `server/app/agent/diagnoser.py`)
- AI Diagnoser → Groq Client: analyzes errors (evidence: `server/app/agent/diagnoser.py`)
- AI Diagnoser → AI Prompts: uses prompts (evidence: `server/app/agent/diagnoser.py`)
- Groq Client → Groq AI Service: calls model (evidence: `server/app/ai/groq_client.py`)
- Recovery Orchestrator → Recovery Actions: dispatches notification (evidence: `server/app/agent/orchestrator.py`)
- Recovery Actions → Groq Client: generates nudge (evidence: `server/app/agent/actions.py`)
- Recovery Actions → AI Prompts: builds nudge (evidence: `server/app/agent/actions.py`)
- Recovery Actions → Resend Email: sends email (evidence: `server/app/agent/actions.py`)
- Recovery Orchestrator → Recovery Strategies: selects strategy (evidence: `server/app/agent/orchestrator.py`)
- Recovery Strategies → Recovery Actions: invokes actions (evidence: `server/app/agent/strategies.py`)
- Recovery Actions → Stripe Checkout: creates fallback (evidence: `server/app/agent/actions.py`)
- Recovery Actions → SSE Manager: broadcasts fallback (evidence: `server/app/agent/actions.py`)
- Recovery Orchestrator → Transaction Store: updates outcomes (evidence: `server/app/agent/orchestrator.py`)
- Recovery Orchestrator → SSE Manager: broadcasts status (evidence: `server/app/agent/orchestrator.py`)
- Recovery Orchestrator → Audit Logger: records actions (evidence: `server/app/agent/orchestrator.py`)
- Audit Logger → Audit Store: persists entries (evidence: `server/app/audit/audit_logger.py`)
- Payment & API Routes → SSE Manager: streams events (evidence: `server/app/api/routes.py`)
- Payment & API Routes → Gateway Health Monitor: reads health (evidence: `server/app/api/routes.py`)
- React Application → Agent Console: routes to (evidence: `client/src/App.jsx`)
- React Application → Recovery Dashboard: routes to (evidence: `client/src/App.jsx`)
- React Application → Settings View: routes to (evidence: `client/src/App.jsx`)
- React Application → Store Checkout: routes to (evidence: `client/src/App.jsx`)
- Agent Console → SSE Hook: subscribes events (evidence: `client/src/pages/AgentPage.jsx`)
- SSE Hook → SSE Manager: receives stream
- Agent Console → Payment & API Routes: starts recovery batch
- React Application → Payment & API Routes: toggles kill switch (evidence: `client/src/App.jsx`)
- Audit View → Payment & API Routes: loads audit entries
- Recovery Dashboard → Payment & API Routes: loads metrics
- Store Checkout → Payment & API Routes: uses payment API
- Customer → Payment & API Routes: opens recovery link (evidence: `server/app/api/routes.py`)
- Payment & API Routes → Transaction Store: marks recovered (evidence: `server/app/api/routes.py`)
