How dreadvoice/pylos works
Pylos is a Chrome extension and Spring Boot service for turning seller conversations into reviewed PayPal invoices, refunds, and reminders. Content adapters extract page context; the seller requests a proposal, reviews and edits it, then approves or rejects it. The backend validates approved actions before execution, while verified PayPal webhooks feed an activity view. The README documents the overall workflow; source-index references and sampled excerpts support the cited internal calls. Some unsampled implementation details are shown only where the README explicitly documents them.
Main entry points: main.tsx Side panel · messages.ts Extension messaging · ActionService.java Action service · AssistController.java Assist endpoint
Components 28
Browser extension
- Content adapters
extension/src/content/router.ts - Page context
extension/src/shared/context.ts - Side panel
extension/src/sidepanel/main.tsx - Confirmation cards
extension/src/sidepanel/ConfirmCard.tsx - Extension messaging
extension/src/shared/messages.ts - Extension settings
extension/src/shared/settings.ts - Settings page
extension/src/options/main.tsx - Activity feed
extension/src/sidepanel/Notifications.tsx
Proposal and review
- Assist endpoint
backend/src/main/java/com/dreadvoice/pylos/api/AssistController.java - Context sanitizer
backend/src/main/java/com/dreadvoice/pylos/context/ContextSanitizer.java - Copilot agent
backend/src/main/java/com/dreadvoice/pylos/agent/CopilotAgent.java - Read tools
backend/src/main/java/com/dreadvoice/pylos/agent/ReadTools.java - Proposal tools
backend/src/main/java/com/dreadvoice/pylos/agent/ProposeTools.java
Action execution
- Action service
backend/src/main/java/com/dreadvoice/pylos/action/ActionService.java - Pending actions
backend/src/main/java/com/dreadvoice/pylos/action/PendingActionRepository.java - Action endpoint
backend/src/main/java/com/dreadvoice/pylos/api/ActionController.java - Action validator
backend/src/main/java/com/dreadvoice/pylos/action/ActionValidator.java - Action executor
backend/src/main/java/com/dreadvoice/pylos/action/ActionExecutor.java - Invoice client
backend/src/main/java/com/dreadvoice/pylos/paypal/InvoiceClient.java - Refund client
backend/src/main/java/com/dreadvoice/pylos/paypal/RefundClient.java
PayPal activity
- Webhook endpoint
backend/src/main/java/com/dreadvoice/pylos/api/PayPalWebhookController.java - Webhook verifier
backend/src/main/java/com/dreadvoice/pylos/paypal/WebhookVerifier.java - Event handler
backend/src/main/java/com/dreadvoice/pylos/notification/WebhookEventHandler.java - Notifications
backend/src/main/java/com/dreadvoice/pylos/notification/NotificationRepository.java - Notification endpoint
backend/src/main/java/com/dreadvoice/pylos/api/NotificationController.java
Other components
- Seller
- Conversation page
- PayPal
Connections 37
- Conversation page → Content adapters: provides DOM
- Content adapters → Page context: extracts context
extension/src/content/router.ts - Seller → Side panel: requests proposal
- Side panel → Extension messaging: requests context
extension/src/sidepanel/main.tsx - Side panel → Extension messaging: calls backend
extension/src/sidepanel/main.tsx - Extension messaging → Assist endpoint: posts context
- Assist endpoint → Copilot agent: invokes agent
backend/src/main/java/com/dreadvoice/pylos/api/AssistController.java - Page context → Assist endpoint: sends context
- Context sanitizer → Copilot agent: sanitizes input
- Copilot agent → Read tools: retrieves information
- Copilot agent → Proposal tools: proposes actions
- Proposal tools → Action service: creates proposal
- Action service → Pending actions: persists state
backend/src/main/java/com/dreadvoice/pylos/action/ActionService.java - Assist endpoint → Action service: creates proposal
backend/src/main/java/com/dreadvoice/pylos/api/AssistController.java - Assist endpoint → Side panel: returns proposal
- Side panel → Confirmation cards: renders proposals
extension/src/sidepanel/main.tsx - Seller → Confirmation cards: edits and approves
- Confirmation cards → Extension messaging: submits decision
extension/src/sidepanel/main.tsx - Extension messaging → Action endpoint: posts decision
- Action endpoint → Action service: delegates decision
backend/src/main/java/com/dreadvoice/pylos/api/ActionController.java - Action service → Action validator: validates action
backend/src/main/java/com/dreadvoice/pylos/action/ActionService.java - Action service → Action executor: executes approved
backend/src/main/java/com/dreadvoice/pylos/action/ActionService.java - Action executor → Invoice client: writes invoice
- Action executor → Refund client: issues refund
- Invoice client → PayPal: calls invoicing API
backend/src/main/java/com/dreadvoice/pylos/paypal/InvoiceClient.java - Refund client → PayPal: calls refund API
- PayPal → Webhook endpoint: sends events
- Webhook endpoint → Webhook verifier: verifies signature
backend/src/main/java/com/dreadvoice/pylos/api/PayPalWebhookController.java - Webhook endpoint → Event handler: handles verified event
backend/src/main/java/com/dreadvoice/pylos/api/PayPalWebhookController.java - Event handler → Notifications: records event
backend/src/main/java/com/dreadvoice/pylos/notification/WebhookEventHandler.java - Side panel → Notification endpoint: loads activity
extension/src/sidepanel/main.tsx - Notification endpoint → Notifications: reads notifications
backend/src/main/java/com/dreadvoice/pylos/api/NotificationController.java - Side panel → Activity feed: renders activity
extension/src/sidepanel/main.tsx - Notifications → Activity feed: feeds activity
- Seller → Settings page: sets credentials
extension/src/options/main.tsx - Settings page → Extension settings: saves settings
extension/src/options/main.tsx - Extension messaging → Extension settings: uses settings
extension/src/background/service-worker.ts