# aakashmutum/paypal-hackathon architecture

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

- Interactive diagram: https://gitdiagram.com/aakashmutum/paypal-hackathon
- Repository: https://github.com/aakashmutum/paypal-hackathon

## Overview

TrustOra is a merchant/payee risk check placed between PayPal authorization and capture. A shopper or agent initiates checkout; the API holds funds, investigates merchant identity and supporting signals, decides from evidence and rules, then captures, holds for review, or voids. The web app presents the case and checkout flow, while an MCP server exposes agent tools. The README documents Channel3 pricing, registry checks, scam memory, and prompt-injection defenses; sampled source confirms key orchestration paths, but not every integration’s wiring.

Main entry points: [`packages/agent/src/orchestrator.ts`](https://github.com/aakashmutum/paypal-hackathon/blob/main/packages/agent/src/orchestrator.ts) (Investigator), [`apps/api/src/controllers/frontendApi.controller.ts`](https://github.com/aakashmutum/paypal-hackathon/blob/main/apps/api/src/controllers/frontendApi.controller.ts) (Frontend Controller), [`apps/api/src/services/orders/orderOrchestration.service.ts`](https://github.com/aakashmutum/paypal-hackathon/blob/main/apps/api/src/services/orders/orderOrchestration.service.ts) (Order Orchestration), [`apps/web/src/api/apiClient.ts`](https://github.com/aakashmutum/paypal-hackathon/blob/main/apps/web/src/api/apiClient.ts) (Web API Client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Shopper Experience"]
  node_web_checkout["Web Checkout<br/>[Checkout.tsx]"]
  node_web_case["Case View<br/>[Engine.tsx]"]
  node_web_api["Web API Client<br/>[apiClient.ts]"]
end

subgraph group_api["Checkout API"]
  node_api_routes["API Routes<br/>[app.ts]"]
  node_frontend_controller["Frontend Controller"]
  node_agent_controller["Agent Bridge"]
  node_order_flow["Order Orchestration"]
  node_payment_flow["Payment Flow"]
  node_paypal_orders["PayPal Orders"]
  node_investigation_store[("Investigation State")]
  node_merchant_verification["Merchant Verification"]
  node_risk_engine["Risk Decision"]
end

subgraph group_investigation["Investigation Engine"]
  node_agent_runner["Agent Runner"]
  node_agent_orchestrator["Investigator<br/>[orchestrator.ts]"]
  node_baseline_checks["Baseline Checks<br/>[baseline.ts]"]
  node_evidence_derivation["Evidence Derivation<br/>[derive.ts]"]
  node_scoring["Scoring Rules"]
  node_explanations["Decision Explanation"]
  node_agent_ports["Agent Ports<br/>[ports.ts]"]
end

subgraph group_integrations["Evidence Integrations"]
  node_signals["Merchant Signals"]
  node_page_claims["Page Claims<br/>[html.ts]"]
  node_channel3["Channel3 Pricing<br/>[channel3Client.ts]"]
  node_memory[("Scam Memory")]
  node_corporate_registry["Business Registry"]
end

subgraph group_agenttools["Agent Access"]
  node_mcp_server["MCP Server<br/>[server.ts]"]
  node_mcp_client["MCP API Client<br/>[apiClient.ts]"]
  node_mcp_tools["Checkout Tools<br/>[safeCheckout.ts]"]
end

node_shopper(("Shopper"))
node_shopping_agent(("AI Shopping Agent"))
node_paypal["PayPal Sandbox"]

node_shopper -->|"starts checkout"| node_web_checkout
node_web_checkout -.->|"requests checkout"| node_web_api
node_web_api -.->|"calls API"| node_api_routes
node_api_routes -->|"routes requests"| node_frontend_controller
node_frontend_controller -->|"creates authorization"| node_payment_flow
node_payment_flow -->|"creates order"| node_paypal_orders
node_paypal_orders -->|"holds funds"| node_paypal
node_frontend_controller -->|"stores investigation"| node_investigation_store
node_frontend_controller -.->|"starts investigation"| node_agent_runner
node_agent_controller -->|"runs agent"| node_agent_runner
node_agent_runner -->|"invokes investigator"| node_agent_orchestrator
node_agent_orchestrator -->|"runs checks"| node_baseline_checks
node_baseline_checks -->|"uses ports"| node_agent_ports
node_agent_ports -.->|"collects signals"| node_signals
node_signals -->|"extracts claims"| node_page_claims
node_agent_orchestrator -->|"derives evidence"| node_evidence_derivation
node_agent_orchestrator -->|"scores evidence"| node_scoring
node_agent_orchestrator -->|"writes explanation"| node_explanations
node_agent_orchestrator -->|"uses memory"| node_memory
node_agent_orchestrator -.->|"checks prices"| node_channel3
node_order_flow -->|"reads and captures"| node_paypal_orders
node_order_flow -->|"looks up business"| node_corporate_registry
node_order_flow -.->|"verifies payee"| node_merchant_verification
node_order_flow -.->|"evaluates risk"| node_risk_engine
node_agent_runner -.->|"returns findings"| node_frontend_controller
node_web_api -.->|"provides case data"| node_web_case
node_web_case -->|"requests case actions"| node_web_api
node_shopping_agent -.->|"uses tools"| node_mcp_server
node_mcp_server -->|"registers tools"| node_mcp_tools
node_mcp_tools -->|"requests checkout"| node_mcp_client
node_mcp_client -.->|"calls API"| node_api_routes
node_risk_engine -.->|"guides capture or void"| node_payment_flow

click node_web_checkout "https://github.com/aakashmutum/paypal-hackathon/blob/main/apps/web/src/pages/Checkout.tsx"
click node_web_case "https://github.com/aakashmutum/paypal-hackathon/blob/main/apps/web/src/pages/Engine.tsx"
click node_web_api "https://github.com/aakashmutum/paypal-hackathon/blob/main/apps/web/src/api/apiClient.ts"
click node_api_routes "https://github.com/aakashmutum/paypal-hackathon/blob/main/apps/api/src/app.ts"
click node_frontend_controller "https://github.com/aakashmutum/paypal-hackathon/blob/main/apps/api/src/controllers/frontendApi.controller.ts"
click node_agent_controller "https://github.com/aakashmutum/paypal-hackathon/blob/main/apps/api/src/controllers/agentBridge.controller.ts"
click node_order_flow "https://github.com/aakashmutum/paypal-hackathon/blob/main/apps/api/src/services/orders/orderOrchestration.service.ts"
click node_payment_flow "https://github.com/aakashmutum/paypal-hackathon/blob/main/apps/api/src/services/payments/paymentFlow.service.ts"
click node_paypal_orders "https://github.com/aakashmutum/paypal-hackathon/blob/main/apps/api/src/services/paypal/paypalOrders.service.ts"
click node_investigation_store "https://github.com/aakashmutum/paypal-hackathon/blob/main/apps/api/src/services/investigation/investigation.types.ts"
click node_merchant_verification "https://github.com/aakashmutum/paypal-hackathon/blob/main/apps/api/src/services/verification/merchantVerification.service.ts"
click node_risk_engine "https://github.com/aakashmutum/paypal-hackathon/blob/main/apps/api/src/services/risk/riskEngine.service.ts"
click node_agent_runner "https://github.com/aakashmutum/paypal-hackathon/blob/main/apps/api/src/services/agent/agentRunner.service.ts"
click node_agent_orchestrator "https://github.com/aakashmutum/paypal-hackathon/blob/main/packages/agent/src/orchestrator.ts"
click node_baseline_checks "https://github.com/aakashmutum/paypal-hackathon/blob/main/packages/agent/src/tools/baseline.ts"
click node_evidence_derivation "https://github.com/aakashmutum/paypal-hackathon/blob/main/packages/agent/src/evidence/derive.ts"
click node_scoring "https://github.com/aakashmutum/paypal-hackathon/tree/main/packages/agent/src/scoring"
click node_explanations "https://github.com/aakashmutum/paypal-hackathon/tree/main/packages/agent/src/explain"
click node_agent_ports "https://github.com/aakashmutum/paypal-hackathon/blob/main/packages/agent/src/ports.ts"
click node_signals "https://github.com/aakashmutum/paypal-hackathon/tree/main/packages/signals/src/agentPort"
click node_page_claims "https://github.com/aakashmutum/paypal-hackathon/blob/main/packages/signals/src/agentPort/html.ts"
click node_channel3 "https://github.com/aakashmutum/paypal-hackathon/blob/main/packages/signals/src/agentPort/channel3Client.ts"
click node_memory "https://github.com/aakashmutum/paypal-hackathon/tree/main/packages/memory/src"
click node_corporate_registry "https://github.com/aakashmutum/paypal-hackathon/blob/main/apps/api/src/services/registry/corporateRegistry.ts"
click node_mcp_server "https://github.com/aakashmutum/paypal-hackathon/blob/main/apps/mcp/src/server.ts"
click node_mcp_client "https://github.com/aakashmutum/paypal-hackathon/blob/main/apps/mcp/src/apiClient.ts"
click node_mcp_tools "https://github.com/aakashmutum/paypal-hackathon/blob/main/apps/mcp/src/tools/safeCheckout.ts"

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_checkout,node_web_case,node_web_api toneBlue
class node_api_routes,node_frontend_controller,node_agent_controller,node_order_flow,node_payment_flow,node_paypal_orders,node_investigation_store,node_merchant_verification,node_risk_engine toneAmber
class node_agent_runner,node_agent_orchestrator,node_baseline_checks,node_evidence_derivation,node_scoring,node_explanations,node_agent_ports toneMint
class node_signals,node_page_claims,node_channel3,node_memory,node_corporate_registry toneRose
class node_mcp_server,node_mcp_client,node_mcp_tools,node_shopper,node_shopping_agent,node_paypal toneIndigo
```

## Components

### Shopper Experience

- [Web Checkout](https://github.com/aakashmutum/paypal-hackathon/blob/main/apps/web/src/pages/Checkout.tsx): `apps/web/src/pages/Checkout.tsx`
- [Case View](https://github.com/aakashmutum/paypal-hackathon/blob/main/apps/web/src/pages/Engine.tsx): `apps/web/src/pages/Engine.tsx`
- [Web API Client](https://github.com/aakashmutum/paypal-hackathon/blob/main/apps/web/src/api/apiClient.ts): `apps/web/src/api/apiClient.ts`

### Checkout API

- [API Routes](https://github.com/aakashmutum/paypal-hackathon/blob/main/apps/api/src/app.ts): `apps/api/src/app.ts`
- [Frontend Controller](https://github.com/aakashmutum/paypal-hackathon/blob/main/apps/api/src/controllers/frontendApi.controller.ts): `apps/api/src/controllers/frontendApi.controller.ts`
- [Agent Bridge](https://github.com/aakashmutum/paypal-hackathon/blob/main/apps/api/src/controllers/agentBridge.controller.ts): `apps/api/src/controllers/agentBridge.controller.ts`
- [Order Orchestration](https://github.com/aakashmutum/paypal-hackathon/blob/main/apps/api/src/services/orders/orderOrchestration.service.ts): `apps/api/src/services/orders/orderOrchestration.service.ts`
- [Payment Flow](https://github.com/aakashmutum/paypal-hackathon/blob/main/apps/api/src/services/payments/paymentFlow.service.ts): `apps/api/src/services/payments/paymentFlow.service.ts`
- [PayPal Orders](https://github.com/aakashmutum/paypal-hackathon/blob/main/apps/api/src/services/paypal/paypalOrders.service.ts): `apps/api/src/services/paypal/paypalOrders.service.ts`
- [Investigation State](https://github.com/aakashmutum/paypal-hackathon/blob/main/apps/api/src/services/investigation/investigation.types.ts): `apps/api/src/services/investigation/investigation.types.ts`
- [Merchant Verification](https://github.com/aakashmutum/paypal-hackathon/blob/main/apps/api/src/services/verification/merchantVerification.service.ts): `apps/api/src/services/verification/merchantVerification.service.ts`
- [Risk Decision](https://github.com/aakashmutum/paypal-hackathon/blob/main/apps/api/src/services/risk/riskEngine.service.ts): `apps/api/src/services/risk/riskEngine.service.ts`

### Investigation Engine

- [Agent Runner](https://github.com/aakashmutum/paypal-hackathon/blob/main/apps/api/src/services/agent/agentRunner.service.ts): `apps/api/src/services/agent/agentRunner.service.ts`
- [Investigator](https://github.com/aakashmutum/paypal-hackathon/blob/main/packages/agent/src/orchestrator.ts): `packages/agent/src/orchestrator.ts`
- [Baseline Checks](https://github.com/aakashmutum/paypal-hackathon/blob/main/packages/agent/src/tools/baseline.ts): `packages/agent/src/tools/baseline.ts`
- [Evidence Derivation](https://github.com/aakashmutum/paypal-hackathon/blob/main/packages/agent/src/evidence/derive.ts): `packages/agent/src/evidence/derive.ts`
- [Scoring Rules](https://github.com/aakashmutum/paypal-hackathon/tree/main/packages/agent/src/scoring): `packages/agent/src/scoring`
- [Decision Explanation](https://github.com/aakashmutum/paypal-hackathon/tree/main/packages/agent/src/explain): `packages/agent/src/explain`
- [Agent Ports](https://github.com/aakashmutum/paypal-hackathon/blob/main/packages/agent/src/ports.ts): `packages/agent/src/ports.ts`

### Evidence Integrations

- [Merchant Signals](https://github.com/aakashmutum/paypal-hackathon/tree/main/packages/signals/src/agentPort): `packages/signals/src/agentPort`
- [Page Claims](https://github.com/aakashmutum/paypal-hackathon/blob/main/packages/signals/src/agentPort/html.ts): `packages/signals/src/agentPort/html.ts`
- [Channel3 Pricing](https://github.com/aakashmutum/paypal-hackathon/blob/main/packages/signals/src/agentPort/channel3Client.ts): `packages/signals/src/agentPort/channel3Client.ts`
- [Scam Memory](https://github.com/aakashmutum/paypal-hackathon/tree/main/packages/memory/src): `packages/memory/src`
- [Business Registry](https://github.com/aakashmutum/paypal-hackathon/blob/main/apps/api/src/services/registry/corporateRegistry.ts): `apps/api/src/services/registry/corporateRegistry.ts`

### Agent Access

- [MCP Server](https://github.com/aakashmutum/paypal-hackathon/blob/main/apps/mcp/src/server.ts): `apps/mcp/src/server.ts`
- [MCP API Client](https://github.com/aakashmutum/paypal-hackathon/blob/main/apps/mcp/src/apiClient.ts): `apps/mcp/src/apiClient.ts`
- [Checkout Tools](https://github.com/aakashmutum/paypal-hackathon/blob/main/apps/mcp/src/tools/safeCheckout.ts): `apps/mcp/src/tools/safeCheckout.ts`

### Other components

- **Shopper**
- **AI Shopping Agent**
- **PayPal Sandbox**

## Connections

- Shopper → Web Checkout: starts checkout (evidence: `README.md`)
- Web Checkout → Web API Client: requests checkout
- Web API Client → API Routes: calls API
- API Routes → Frontend Controller: routes requests (evidence: `apps/api/src/app.ts`)
- Frontend Controller → Payment Flow: creates authorization (evidence: `apps/api/src/controllers/frontendApi.controller.ts`)
- Payment Flow → PayPal Orders: creates order (evidence: `apps/api/src/services/payments/paymentFlow.service.ts`)
- PayPal Orders → PayPal Sandbox: holds funds (evidence: `README.md`)
- Frontend Controller → Investigation State: stores investigation (evidence: `apps/api/src/controllers/frontendApi.controller.ts`)
- Frontend Controller → Agent Runner: starts investigation (evidence: `apps/api/src/controllers/frontendApi.controller.ts`)
- Agent Bridge → Agent Runner: runs agent (evidence: `apps/api/src/controllers/agentBridge.controller.ts`)
- Agent Runner → Investigator: invokes investigator (evidence: `apps/api/src/services/agent/agentRunner.service.ts`)
- Investigator → Baseline Checks: runs checks (evidence: `packages/agent/src/orchestrator.ts`)
- Baseline Checks → Agent Ports: uses ports (evidence: `packages/agent/src/tools/baseline.ts`)
- Agent Ports → Merchant Signals: collects signals
- Merchant Signals → Page Claims: extracts claims (evidence: `packages/signals/src/agentPort/kernelClient.ts`)
- Investigator → Evidence Derivation: derives evidence (evidence: `packages/agent/src/orchestrator.ts`)
- Investigator → Scoring Rules: scores evidence (evidence: `packages/agent/src/orchestrator.ts`)
- Investigator → Decision Explanation: writes explanation (evidence: `packages/agent/src/orchestrator.ts`)
- Investigator → Scam Memory: uses memory (evidence: `packages/agent/src/orchestrator.ts`)
- Investigator → Channel3 Pricing: checks prices (evidence: `README.md`)
- Order Orchestration → PayPal Orders: reads and captures (evidence: `apps/api/src/services/orders/orderOrchestration.service.ts`)
- Order Orchestration → Business Registry: looks up business (evidence: `apps/api/src/services/orders/orderOrchestration.service.ts`)
- Order Orchestration → Merchant Verification: verifies payee (evidence: `apps/api/src/services/orders/orderOrchestration.service.ts`)
- Order Orchestration → Risk Decision: evaluates risk (evidence: `apps/api/src/services/orders/orderOrchestration.service.ts`)
- Agent Runner → Frontend Controller: returns findings (evidence: `apps/api/src/controllers/frontendApi.controller.ts`)
- Web API Client → Case View: provides case data (evidence: `apps/web/src/pages/Engine.tsx`)
- Case View → Web API Client: requests case actions (evidence: `apps/web/src/pages/Engine.tsx`)
- AI Shopping Agent → MCP Server: uses tools (evidence: `README.md`)
- MCP Server → Checkout Tools: registers tools (evidence: `apps/mcp/src/server.ts`)
- Checkout Tools → MCP API Client: requests checkout (evidence: `apps/mcp/src/tools/safeCheckout.ts`)
- MCP API Client → API Routes: calls API
- Risk Decision → Payment Flow: guides capture or void (evidence: `README.md`)