How srainney/aap_pay works
Project type and purpose
• This is a full-stack payment-processing application split into two pieces:
• A lightweight JavaScript/HTML client (“JSClient”) that drives the UI for Agent-Assisted Pay.
• A backend of Twilio Serverless Functions (“Server”) that orchestrates calls, tokenizes/charges payments, and syncs real-time state.
• Purpose: enable agents to place outbound calls (PSTN or SIP), capture call SIDs, accept payment data, process charges, and broadcast updates via Twilio Sync.
File structure
• Top level:
• JSClient/ – the static frontend (index.html, payment.html, payment.js, img folder).
• Server/ – Node.js Twilio Serverless project (functions/*, config & lock files).
• “Server/functions” is subdivided by domain:
• aap/ → changeCapture.js, changeStatus.js, startCapture.js
• connector/ → tokenization (tokenize.js) and charging (charge.js)
• pv/ → call initiation (callToPSTN.js, callToSIP.js)
• sync/ → real-time updates (getSyncToken.js, setupSyncServices.js, uuiSyncUpdate.js, paySyncUpdate.protected.js)
• Config & deployment: .env (Twilio credentials), .twilioserverlessrc, .nvmrc, pnpm-lock, package.json.
Key insights from README
• Dev workflow: local JSClient at localhost:1234, Server via twilio serverless:start (Twilio CLI + plugin).
• Production: deploy Server via pnpm run deploy into Twilio Runtime.
• Payment flow: outbound call → capture Call SID → tokenize card → charge → sync updates.
System components & interactions
a. Main components
• Frontend (JSClient) – static pages + Twilio Sync JS SDK + HTTP calls to Server.
• Backend (Twilio Serverless Functions) – microservices handling calls, payments, and sync logic.
• Twilio REST API Suite
– Voice API (connect to PSTN/SIP)
– Pay API (tokenize & charge)
– Sync API (real-time data and events)
• External endpoints
– PSTN carriers
– SIP endpoints
b. Relationships & data flows
• User/agent web UI → HTTP(S) → Serverless Functions
• Payment Function calls Twilio Pay REST → returns token/charge response
• Call Functions call Twilio Voice REST → initiate call, return Call SID
• Sync Functions call Twilio Sync REST → create/update documents/channels
• JSClient listens on Sync events → updates UI in real time
c. Architectural patterns & principles
• Serverless microservices: each Twilio Function addresses a single responsibility.
• Event-driven updates via Twilio Sync (pub/sub).
• Clear separation of concerns: “pv” for calls, “connector” for payments, “sync” for real-time.
d. Key technologies & frameworks
• Node.js Twilio Serverless Functions
• Twilio REST APIs: Voice, Pay, Sync
• Static JS/HTML frontend (bundled with pnpm & a dev server)
• Twilio CLI + Serverless plugin (local dev & deploy)