# paypaldev/video-bytemonkio-paypal-tutorial architecture

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

- Interactive diagram: https://gitdiagram.com/paypaldev/video-bytemonkio-paypal-tutorial
- Repository: https://github.com/paypaldev/video-bytemonkio-paypal-tutorial

## Overview

This repository is a PayPal sandbox integration and narrated failure-mode demo. The main runtime flow is buyer checkout through the local server and PayPal Orders API, with later webhook deliveries verified, deduplicated, and applied to application-owned order or subscription state. Separate runnable scenarios demonstrate idempotency, error handling, subscription billing, Venmo eligibility, and scoped agent access. The graph uses the README and SOURCE INDEX references; unsampled server wiring is represented only where the index names the relationship.

Main entry points: [`src/server.ts`](https://github.com/paypaldev/video-bytemonkio-paypal-tutorial/blob/main/src/server.ts) (HTTP server), [`src/paypal/client.ts`](https://github.com/paypaldev/video-bytemonkio-paypal-tutorial/blob/main/src/paypal/client.ts) (HTTP client), [`scenarios/_common.ts`](https://github.com/paypaldev/video-bytemonkio-paypal-tutorial/blob/main/scenarios/_common.ts) (Scenario helpers), [`src/domain/handle-event.ts`](https://github.com/paypaldev/video-bytemonkio-paypal-tutorial/blob/main/src/domain/handle-event.ts) (Event handler)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry points"]
  node_server["HTTP server<br/>[server.ts]"]
  node_checkout_page["Checkout page<br/>[index.html]"]
  node_config["Environment config<br/>[config.ts]"]
  node_logger["Console narration<br/>[log.ts]"]
end

subgraph group_paypal["PayPal integration"]
  node_orders["Orders API<br/>[orders.ts]"]
  node_subscriptions["Subscriptions API<br/>[subscriptions.ts]"]
  node_webhooks["Webhook verification<br/>[webhooks.ts]"]
  node_client["HTTP client<br/>[client.ts]"]
  node_auth["Token authentication<br/>[auth.ts]"]
  node_errors["Error classification<br/>[errors.ts]"]
end

subgraph group_domain["Application state"]
  node_event_handler["Event handler<br/>[handle-event.ts]"]
  node_order_state["Order state<br/>[order-state.ts]"]
  node_subscription_state["Subscription state"]
end

subgraph group_storage["Local persistence"]
  node_event_log[("Webhook event log<br/>[events.ts]")]
  node_ledger[("Idempotency ledger<br/>[ledger.ts]")]
  node_json_store[("JSON file store<br/>[json-store.ts]")]
end

subgraph group_scenarios["Runnable demonstrations"]
  node_checkout_demo["Checkout and retries"]
  node_webhook_demo["Webhook replay demo"]
  node_subscription_demo["Subscription lifecycle"]
  node_error_demo["Error demonstrations"]
  node_agent_demo["Agent toolkit"]
  node_venmo_demo["Venmo eligibility"]
  node_scenario_helpers["Scenario helpers<br/>[_common.ts]"]
end

node_buyer(("Buyer browser"))
node_paypal_service{{"PayPal sandbox"}}

node_buyer -->|"opens"| node_checkout_page
node_checkout_page -->|"submits checkout"| node_server
node_server -->|"creates and captures"| node_orders
node_server -->|"verifies deliveries"| node_webhooks
node_paypal_service -->|"delivers webhooks"| node_server
node_server -->|"handles verified events"| node_event_handler
node_event_handler -->|"records deliveries"| node_event_log
node_event_handler -->|"applies order events"| node_order_state
node_event_handler -->|"applies billing events"| node_subscription_state
node_server -->|"reads order state"| node_order_state
node_server -->|"uses capture ledger"| node_ledger
node_server -->|"reads subscription state"| node_subscription_state
node_orders -->|"sends API calls"| node_client
node_subscriptions -->|"sends API calls"| node_client
node_webhooks -->|"checks and resends"| node_client
node_client -->|"gets access token"| node_auth
node_client -->|"classifies failures"| node_errors
node_client -->|"calls REST API"| node_paypal_service
node_config -->|"configures endpoint"| node_client
node_config -->|"provides webhook ID"| node_webhooks
node_order_state -->|"persists orders"| node_json_store
node_subscription_state -->|"persists subscriptions"| node_json_store
node_event_log -->|"persists events"| node_json_store
node_ledger -->|"persists attempts"| node_json_store
node_checkout_demo -->|"runs checkout"| node_orders
node_checkout_demo -->|"records retries"| node_ledger
node_webhook_demo -->|"replays events"| node_webhooks
node_webhook_demo -->|"exercises handling"| node_event_handler
node_subscription_demo -->|"runs billing lifecycle"| node_subscriptions
node_subscription_demo -->|"shows access state"| node_subscription_state
node_error_demo -->|"demonstrates outcomes"| node_errors
node_agent_demo -->|"creates orders"| node_orders
node_agent_demo -->|"audits attempts"| node_ledger
node_venmo_demo -->|"checks environment"| node_config
node_scenario_helpers -->|"polls order status"| node_orders
node_scenario_helpers -->|"describes token"| node_auth
node_scenario_helpers -->|"checks sandbox mode"| node_config
node_scenario_helpers -->|"formats failures"| node_errors
node_scenario_helpers -->|"prints narration"| node_logger

click node_server "https://github.com/paypaldev/video-bytemonkio-paypal-tutorial/blob/main/src/server.ts"
click node_checkout_page "https://github.com/paypaldev/video-bytemonkio-paypal-tutorial/blob/main/public/index.html"
click node_config "https://github.com/paypaldev/video-bytemonkio-paypal-tutorial/blob/main/src/config.ts"
click node_orders "https://github.com/paypaldev/video-bytemonkio-paypal-tutorial/blob/main/src/paypal/orders.ts"
click node_subscriptions "https://github.com/paypaldev/video-bytemonkio-paypal-tutorial/blob/main/src/paypal/subscriptions.ts"
click node_webhooks "https://github.com/paypaldev/video-bytemonkio-paypal-tutorial/blob/main/src/paypal/webhooks.ts"
click node_client "https://github.com/paypaldev/video-bytemonkio-paypal-tutorial/blob/main/src/paypal/client.ts"
click node_auth "https://github.com/paypaldev/video-bytemonkio-paypal-tutorial/blob/main/src/paypal/auth.ts"
click node_errors "https://github.com/paypaldev/video-bytemonkio-paypal-tutorial/blob/main/src/paypal/errors.ts"
click node_event_handler "https://github.com/paypaldev/video-bytemonkio-paypal-tutorial/blob/main/src/domain/handle-event.ts"
click node_order_state "https://github.com/paypaldev/video-bytemonkio-paypal-tutorial/blob/main/src/domain/order-state.ts"
click node_subscription_state "https://github.com/paypaldev/video-bytemonkio-paypal-tutorial/blob/main/src/domain/subscription-state.ts"
click node_event_log "https://github.com/paypaldev/video-bytemonkio-paypal-tutorial/blob/main/src/store/events.ts"
click node_ledger "https://github.com/paypaldev/video-bytemonkio-paypal-tutorial/blob/main/src/store/ledger.ts"
click node_json_store "https://github.com/paypaldev/video-bytemonkio-paypal-tutorial/blob/main/src/store/json-store.ts"
click node_checkout_demo "https://github.com/paypaldev/video-bytemonkio-paypal-tutorial/blob/main/scenarios/01-checkout-happy-path.ts"
click node_webhook_demo "https://github.com/paypaldev/video-bytemonkio-paypal-tutorial/blob/main/scenarios/03-webhook-replay.ts"
click node_subscription_demo "https://github.com/paypaldev/video-bytemonkio-paypal-tutorial/blob/main/scenarios/05-subscription-lifecycle.ts"
click node_error_demo "https://github.com/paypaldev/video-bytemonkio-paypal-tutorial/blob/main/scenarios/04-errors-three-ways.ts"
click node_agent_demo "https://github.com/paypaldev/video-bytemonkio-paypal-tutorial/blob/main/scenarios/07-agent-toolkit.ts"
click node_venmo_demo "https://github.com/paypaldev/video-bytemonkio-paypal-tutorial/blob/main/scenarios/06-venmo-eligibility.ts"
click node_scenario_helpers "https://github.com/paypaldev/video-bytemonkio-paypal-tutorial/blob/main/scenarios/_common.ts"
click node_logger "https://github.com/paypaldev/video-bytemonkio-paypal-tutorial/blob/main/src/log.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_server,node_checkout_page,node_config,node_logger,node_buyer toneBlue
class node_orders,node_subscriptions,node_webhooks,node_client,node_auth,node_errors toneAmber
class node_event_handler,node_order_state,node_subscription_state toneMint
class node_event_log,node_ledger,node_json_store toneRose
class node_checkout_demo,node_webhook_demo,node_subscription_demo,node_error_demo,node_agent_demo,node_venmo_demo,node_scenario_helpers,node_paypal_service toneIndigo
```

## Components

### Entry points

- [HTTP server](https://github.com/paypaldev/video-bytemonkio-paypal-tutorial/blob/main/src/server.ts): `src/server.ts`
- [Checkout page](https://github.com/paypaldev/video-bytemonkio-paypal-tutorial/blob/main/public/index.html): `public/index.html`
- [Environment config](https://github.com/paypaldev/video-bytemonkio-paypal-tutorial/blob/main/src/config.ts): `src/config.ts`
- [Console narration](https://github.com/paypaldev/video-bytemonkio-paypal-tutorial/blob/main/src/log.ts): `src/log.ts`

### PayPal integration

- [Orders API](https://github.com/paypaldev/video-bytemonkio-paypal-tutorial/blob/main/src/paypal/orders.ts): `src/paypal/orders.ts`
- [Subscriptions API](https://github.com/paypaldev/video-bytemonkio-paypal-tutorial/blob/main/src/paypal/subscriptions.ts): `src/paypal/subscriptions.ts`
- [Webhook verification](https://github.com/paypaldev/video-bytemonkio-paypal-tutorial/blob/main/src/paypal/webhooks.ts): `src/paypal/webhooks.ts`
- [HTTP client](https://github.com/paypaldev/video-bytemonkio-paypal-tutorial/blob/main/src/paypal/client.ts): `src/paypal/client.ts`
- [Token authentication](https://github.com/paypaldev/video-bytemonkio-paypal-tutorial/blob/main/src/paypal/auth.ts): `src/paypal/auth.ts`
- [Error classification](https://github.com/paypaldev/video-bytemonkio-paypal-tutorial/blob/main/src/paypal/errors.ts): `src/paypal/errors.ts`

### Application state

- [Event handler](https://github.com/paypaldev/video-bytemonkio-paypal-tutorial/blob/main/src/domain/handle-event.ts): `src/domain/handle-event.ts`
- [Order state](https://github.com/paypaldev/video-bytemonkio-paypal-tutorial/blob/main/src/domain/order-state.ts): `src/domain/order-state.ts`
- [Subscription state](https://github.com/paypaldev/video-bytemonkio-paypal-tutorial/blob/main/src/domain/subscription-state.ts): `src/domain/subscription-state.ts`

### Local persistence

- [Webhook event log](https://github.com/paypaldev/video-bytemonkio-paypal-tutorial/blob/main/src/store/events.ts): `src/store/events.ts`
- [Idempotency ledger](https://github.com/paypaldev/video-bytemonkio-paypal-tutorial/blob/main/src/store/ledger.ts): `src/store/ledger.ts`
- [JSON file store](https://github.com/paypaldev/video-bytemonkio-paypal-tutorial/blob/main/src/store/json-store.ts): `src/store/json-store.ts`

### Runnable demonstrations

- [Checkout and retries](https://github.com/paypaldev/video-bytemonkio-paypal-tutorial/blob/main/scenarios/01-checkout-happy-path.ts): `scenarios/01-checkout-happy-path.ts`
- [Webhook replay demo](https://github.com/paypaldev/video-bytemonkio-paypal-tutorial/blob/main/scenarios/03-webhook-replay.ts): `scenarios/03-webhook-replay.ts`
- [Subscription lifecycle](https://github.com/paypaldev/video-bytemonkio-paypal-tutorial/blob/main/scenarios/05-subscription-lifecycle.ts): `scenarios/05-subscription-lifecycle.ts`
- [Error demonstrations](https://github.com/paypaldev/video-bytemonkio-paypal-tutorial/blob/main/scenarios/04-errors-three-ways.ts): `scenarios/04-errors-three-ways.ts`
- [Agent toolkit](https://github.com/paypaldev/video-bytemonkio-paypal-tutorial/blob/main/scenarios/07-agent-toolkit.ts): `scenarios/07-agent-toolkit.ts`
- [Venmo eligibility](https://github.com/paypaldev/video-bytemonkio-paypal-tutorial/blob/main/scenarios/06-venmo-eligibility.ts): `scenarios/06-venmo-eligibility.ts`
- [Scenario helpers](https://github.com/paypaldev/video-bytemonkio-paypal-tutorial/blob/main/scenarios/_common.ts): `scenarios/_common.ts`

### Other components

- **Buyer browser**
- **PayPal sandbox**

## Connections

- Buyer browser → Checkout page: opens (evidence: `README.md`)
- Checkout page → HTTP server: submits checkout (evidence: `README.md`)
- HTTP server → Orders API: creates and captures (evidence: `src/server.ts`)
- HTTP server → Webhook verification: verifies deliveries (evidence: `src/server.ts`)
- PayPal sandbox → HTTP server: delivers webhooks (evidence: `README.md`)
- HTTP server → Event handler: handles verified events (evidence: `src/server.ts`)
- Event handler → Webhook event log: records deliveries (evidence: `src/domain/handle-event.ts`)
- Event handler → Order state: applies order events (evidence: `src/domain/handle-event.ts`)
- Event handler → Subscription state: applies billing events (evidence: `src/domain/handle-event.ts`)
- HTTP server → Order state: reads order state (evidence: `src/server.ts`)
- HTTP server → Idempotency ledger: uses capture ledger (evidence: `src/server.ts`)
- HTTP server → Subscription state: reads subscription state (evidence: `src/server.ts`)
- Orders API → HTTP client: sends API calls (evidence: `src/paypal/orders.ts`)
- Subscriptions API → HTTP client: sends API calls (evidence: `src/paypal/subscriptions.ts`)
- Webhook verification → HTTP client: checks and resends (evidence: `src/paypal/webhooks.ts`)
- HTTP client → Token authentication: gets access token (evidence: `src/paypal/client.ts`)
- HTTP client → Error classification: classifies failures (evidence: `src/paypal/client.ts`)
- HTTP client → PayPal sandbox: calls REST API (evidence: `src/paypal/client.ts`)
- Environment config → HTTP client: configures endpoint (evidence: `src/paypal/client.ts`)
- Environment config → Webhook verification: provides webhook ID (evidence: `src/paypal/webhooks.ts`)
- Order state → JSON file store: persists orders (evidence: `src/domain/order-state.ts`)
- Subscription state → JSON file store: persists subscriptions (evidence: `src/domain/subscription-state.ts`)
- Webhook event log → JSON file store: persists events (evidence: `src/store/events.ts`)
- Idempotency ledger → JSON file store: persists attempts (evidence: `src/store/ledger.ts`)
- Checkout and retries → Orders API: runs checkout (evidence: `scenarios/01-checkout-happy-path.ts`)
- Checkout and retries → Idempotency ledger: records retries (evidence: `scenarios/01-checkout-happy-path.ts`)
- Webhook replay demo → Webhook verification: replays events (evidence: `scenarios/03-webhook-replay.ts`)
- Webhook replay demo → Event handler: exercises handling (evidence: `scenarios/03-webhook-replay.ts`)
- Subscription lifecycle → Subscriptions API: runs billing lifecycle (evidence: `scenarios/05-subscription-lifecycle.ts`)
- Subscription lifecycle → Subscription state: shows access state (evidence: `scenarios/05-subscription-lifecycle.ts`)
- Error demonstrations → Error classification: demonstrates outcomes (evidence: `scenarios/04-errors-three-ways.ts`)
- Agent toolkit → Orders API: creates orders (evidence: `scenarios/07-agent-toolkit.ts`)
- Agent toolkit → Idempotency ledger: audits attempts (evidence: `scenarios/07-agent-toolkit.ts`)
- Venmo eligibility → Environment config: checks environment (evidence: `scenarios/06-venmo-eligibility.ts`)
- Scenario helpers → Orders API: polls order status (evidence: `scenarios/_common.ts`)
- Scenario helpers → Token authentication: describes token (evidence: `scenarios/_common.ts`)
- Scenario helpers → Environment config: checks sandbox mode (evidence: `scenarios/_common.ts`)
- Scenario helpers → Error classification: formats failures (evidence: `scenarios/_common.ts`)
- Scenario helpers → Console narration: prints narration (evidence: `scenarios/_common.ts`)
