# dreadvoice/pylos architecture

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

- Interactive diagram: https://gitdiagram.com/dreadvoice/pylos
- Repository: https://github.com/dreadvoice/pylos

## Overview

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: [`extension/src/sidepanel/main.tsx`](https://github.com/dreadvoice/pylos/blob/main/extension/src/sidepanel/main.tsx) (Side panel), [`extension/src/shared/messages.ts`](https://github.com/dreadvoice/pylos/blob/main/extension/src/shared/messages.ts) (Extension messaging), [`backend/src/main/java/com/dreadvoice/pylos/action/ActionService.java`](https://github.com/dreadvoice/pylos/blob/main/backend/src/main/java/com/dreadvoice/pylos/action/ActionService.java) (Action service), [`backend/src/main/java/com/dreadvoice/pylos/api/AssistController.java`](https://github.com/dreadvoice/pylos/blob/main/backend/src/main/java/com/dreadvoice/pylos/api/AssistController.java) (Assist endpoint)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_extension["Browser extension"]
  node_content_adapters["Content adapters<br/>[router.ts]"]
  node_page_context["Page context<br/>[context.ts]"]
  node_side_panel["Side panel<br/>[main.tsx]"]
  node_confirmation_card["Confirmation cards<br/>[ConfirmCard.tsx]"]
  node_extension_messaging["Extension messaging<br/>[messages.ts]"]
  node_extension_settings["Extension settings<br/>[settings.ts]"]
  node_options_page["Settings page<br/>[main.tsx]"]
  node_activity_view["Activity feed<br/>[Notifications.tsx]"]
end

subgraph group_proposal["Proposal and review"]
  node_assist_api["Assist endpoint"]
  node_context_sanitizer["Context sanitizer"]
  node_copilot["Copilot agent<br/>[CopilotAgent.java]"]
  node_read_tools["Read tools<br/>[ReadTools.java]"]
  node_proposal_tools["Proposal tools<br/>[ProposeTools.java]"]
end

subgraph group_execution["Action execution"]
  node_action_service["Action service<br/>[ActionService.java]"]
  node_pending_actions[("Pending actions")]
  node_action_api["Action endpoint"]
  node_action_validator["Action validator"]
  node_action_executor["Action executor"]
  node_invoice_client["Invoice client<br/>[InvoiceClient.java]"]
  node_refund_client["Refund client<br/>[RefundClient.java]"]
end

subgraph group_activity["PayPal activity"]
  node_webhook_api["Webhook endpoint"]
  node_webhook_verifier["Webhook verifier"]
  node_webhook_handler["Event handler"]
  node_notifications[("Notifications")]
  node_notification_api["Notification endpoint"]
end

node_seller(("Seller"))
node_chat_page["Conversation page"]
node_paypal["PayPal"]

node_chat_page -->|"provides DOM"| node_content_adapters
node_content_adapters -->|"extracts context"| node_page_context
node_seller -->|"requests proposal"| node_side_panel
node_side_panel -->|"requests context"| node_extension_messaging
node_side_panel -->|"calls backend"| node_extension_messaging
node_extension_messaging -->|"posts context"| node_assist_api
node_assist_api -->|"invokes agent"| node_copilot
node_page_context -->|"sends context"| node_assist_api
node_context_sanitizer -->|"sanitizes input"| node_copilot
node_copilot -->|"retrieves information"| node_read_tools
node_copilot -->|"proposes actions"| node_proposal_tools
node_proposal_tools -->|"creates proposal"| node_action_service
node_action_service -->|"persists state"| node_pending_actions
node_assist_api -->|"creates proposal"| node_action_service
node_assist_api -->|"returns proposal"| node_side_panel
node_side_panel -->|"renders proposals"| node_confirmation_card
node_seller -->|"edits and approves"| node_confirmation_card
node_confirmation_card -->|"submits decision"| node_extension_messaging
node_extension_messaging -->|"posts decision"| node_action_api
node_action_api -->|"delegates decision"| node_action_service
node_action_service -->|"validates action"| node_action_validator
node_action_service -->|"executes approved"| node_action_executor
node_action_executor -->|"writes invoice"| node_invoice_client
node_action_executor -->|"issues refund"| node_refund_client
node_invoice_client -->|"calls invoicing API"| node_paypal
node_refund_client -.->|"calls refund API"| node_paypal
node_paypal -->|"sends events"| node_webhook_api
node_webhook_api -->|"verifies signature"| node_webhook_verifier
node_webhook_api -->|"handles verified event"| node_webhook_handler
node_webhook_handler -->|"records event"| node_notifications
node_side_panel -->|"loads activity"| node_notification_api
node_notification_api -->|"reads notifications"| node_notifications
node_side_panel -->|"renders activity"| node_activity_view
node_notifications -->|"feeds activity"| node_activity_view
node_seller -->|"sets credentials"| node_options_page
node_options_page -->|"saves settings"| node_extension_settings
node_extension_messaging -->|"uses settings"| node_extension_settings

click node_content_adapters "https://github.com/dreadvoice/pylos/blob/main/extension/src/content/router.ts"
click node_page_context "https://github.com/dreadvoice/pylos/blob/main/extension/src/shared/context.ts"
click node_side_panel "https://github.com/dreadvoice/pylos/blob/main/extension/src/sidepanel/main.tsx"
click node_confirmation_card "https://github.com/dreadvoice/pylos/blob/main/extension/src/sidepanel/ConfirmCard.tsx"
click node_extension_messaging "https://github.com/dreadvoice/pylos/blob/main/extension/src/shared/messages.ts"
click node_extension_settings "https://github.com/dreadvoice/pylos/blob/main/extension/src/shared/settings.ts"
click node_options_page "https://github.com/dreadvoice/pylos/blob/main/extension/src/options/main.tsx"
click node_assist_api "https://github.com/dreadvoice/pylos/blob/main/backend/src/main/java/com/dreadvoice/pylos/api/AssistController.java"
click node_context_sanitizer "https://github.com/dreadvoice/pylos/blob/main/backend/src/main/java/com/dreadvoice/pylos/context/ContextSanitizer.java"
click node_copilot "https://github.com/dreadvoice/pylos/blob/main/backend/src/main/java/com/dreadvoice/pylos/agent/CopilotAgent.java"
click node_read_tools "https://github.com/dreadvoice/pylos/blob/main/backend/src/main/java/com/dreadvoice/pylos/agent/ReadTools.java"
click node_proposal_tools "https://github.com/dreadvoice/pylos/blob/main/backend/src/main/java/com/dreadvoice/pylos/agent/ProposeTools.java"
click node_action_service "https://github.com/dreadvoice/pylos/blob/main/backend/src/main/java/com/dreadvoice/pylos/action/ActionService.java"
click node_pending_actions "https://github.com/dreadvoice/pylos/blob/main/backend/src/main/java/com/dreadvoice/pylos/action/PendingActionRepository.java"
click node_action_api "https://github.com/dreadvoice/pylos/blob/main/backend/src/main/java/com/dreadvoice/pylos/api/ActionController.java"
click node_action_validator "https://github.com/dreadvoice/pylos/blob/main/backend/src/main/java/com/dreadvoice/pylos/action/ActionValidator.java"
click node_action_executor "https://github.com/dreadvoice/pylos/blob/main/backend/src/main/java/com/dreadvoice/pylos/action/ActionExecutor.java"
click node_invoice_client "https://github.com/dreadvoice/pylos/blob/main/backend/src/main/java/com/dreadvoice/pylos/paypal/InvoiceClient.java"
click node_refund_client "https://github.com/dreadvoice/pylos/blob/main/backend/src/main/java/com/dreadvoice/pylos/paypal/RefundClient.java"
click node_webhook_api "https://github.com/dreadvoice/pylos/blob/main/backend/src/main/java/com/dreadvoice/pylos/api/PayPalWebhookController.java"
click node_webhook_verifier "https://github.com/dreadvoice/pylos/blob/main/backend/src/main/java/com/dreadvoice/pylos/paypal/WebhookVerifier.java"
click node_webhook_handler "https://github.com/dreadvoice/pylos/blob/main/backend/src/main/java/com/dreadvoice/pylos/notification/WebhookEventHandler.java"
click node_notifications "https://github.com/dreadvoice/pylos/blob/main/backend/src/main/java/com/dreadvoice/pylos/notification/NotificationRepository.java"
click node_notification_api "https://github.com/dreadvoice/pylos/blob/main/backend/src/main/java/com/dreadvoice/pylos/api/NotificationController.java"
click node_activity_view "https://github.com/dreadvoice/pylos/blob/main/extension/src/sidepanel/Notifications.tsx"

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_content_adapters,node_page_context,node_side_panel,node_confirmation_card,node_extension_messaging,node_extension_settings,node_options_page,node_activity_view toneBlue
class node_assist_api,node_context_sanitizer,node_copilot,node_read_tools,node_proposal_tools toneAmber
class node_action_service,node_pending_actions,node_action_api,node_action_validator,node_action_executor,node_invoice_client,node_refund_client toneMint
class node_webhook_api,node_webhook_verifier,node_webhook_handler,node_notifications,node_notification_api toneRose
class node_seller,node_chat_page,node_paypal toneIndigo
```

## Components

### Browser extension

- [Content adapters](https://github.com/dreadvoice/pylos/blob/main/extension/src/content/router.ts): `extension/src/content/router.ts`
- [Page context](https://github.com/dreadvoice/pylos/blob/main/extension/src/shared/context.ts): `extension/src/shared/context.ts`
- [Side panel](https://github.com/dreadvoice/pylos/blob/main/extension/src/sidepanel/main.tsx): `extension/src/sidepanel/main.tsx`
- [Confirmation cards](https://github.com/dreadvoice/pylos/blob/main/extension/src/sidepanel/ConfirmCard.tsx): `extension/src/sidepanel/ConfirmCard.tsx`
- [Extension messaging](https://github.com/dreadvoice/pylos/blob/main/extension/src/shared/messages.ts): `extension/src/shared/messages.ts`
- [Extension settings](https://github.com/dreadvoice/pylos/blob/main/extension/src/shared/settings.ts): `extension/src/shared/settings.ts`
- [Settings page](https://github.com/dreadvoice/pylos/blob/main/extension/src/options/main.tsx): `extension/src/options/main.tsx`
- [Activity feed](https://github.com/dreadvoice/pylos/blob/main/extension/src/sidepanel/Notifications.tsx): `extension/src/sidepanel/Notifications.tsx`

### Proposal and review

- [Assist endpoint](https://github.com/dreadvoice/pylos/blob/main/backend/src/main/java/com/dreadvoice/pylos/api/AssistController.java): `backend/src/main/java/com/dreadvoice/pylos/api/AssistController.java`
- [Context sanitizer](https://github.com/dreadvoice/pylos/blob/main/backend/src/main/java/com/dreadvoice/pylos/context/ContextSanitizer.java): `backend/src/main/java/com/dreadvoice/pylos/context/ContextSanitizer.java`
- [Copilot agent](https://github.com/dreadvoice/pylos/blob/main/backend/src/main/java/com/dreadvoice/pylos/agent/CopilotAgent.java): `backend/src/main/java/com/dreadvoice/pylos/agent/CopilotAgent.java`
- [Read tools](https://github.com/dreadvoice/pylos/blob/main/backend/src/main/java/com/dreadvoice/pylos/agent/ReadTools.java): `backend/src/main/java/com/dreadvoice/pylos/agent/ReadTools.java`
- [Proposal tools](https://github.com/dreadvoice/pylos/blob/main/backend/src/main/java/com/dreadvoice/pylos/agent/ProposeTools.java): `backend/src/main/java/com/dreadvoice/pylos/agent/ProposeTools.java`

### Action execution

- [Action service](https://github.com/dreadvoice/pylos/blob/main/backend/src/main/java/com/dreadvoice/pylos/action/ActionService.java): `backend/src/main/java/com/dreadvoice/pylos/action/ActionService.java`
- [Pending actions](https://github.com/dreadvoice/pylos/blob/main/backend/src/main/java/com/dreadvoice/pylos/action/PendingActionRepository.java): `backend/src/main/java/com/dreadvoice/pylos/action/PendingActionRepository.java`
- [Action endpoint](https://github.com/dreadvoice/pylos/blob/main/backend/src/main/java/com/dreadvoice/pylos/api/ActionController.java): `backend/src/main/java/com/dreadvoice/pylos/api/ActionController.java`
- [Action validator](https://github.com/dreadvoice/pylos/blob/main/backend/src/main/java/com/dreadvoice/pylos/action/ActionValidator.java): `backend/src/main/java/com/dreadvoice/pylos/action/ActionValidator.java`
- [Action executor](https://github.com/dreadvoice/pylos/blob/main/backend/src/main/java/com/dreadvoice/pylos/action/ActionExecutor.java): `backend/src/main/java/com/dreadvoice/pylos/action/ActionExecutor.java`
- [Invoice client](https://github.com/dreadvoice/pylos/blob/main/backend/src/main/java/com/dreadvoice/pylos/paypal/InvoiceClient.java): `backend/src/main/java/com/dreadvoice/pylos/paypal/InvoiceClient.java`
- [Refund client](https://github.com/dreadvoice/pylos/blob/main/backend/src/main/java/com/dreadvoice/pylos/paypal/RefundClient.java): `backend/src/main/java/com/dreadvoice/pylos/paypal/RefundClient.java`

### PayPal activity

- [Webhook endpoint](https://github.com/dreadvoice/pylos/blob/main/backend/src/main/java/com/dreadvoice/pylos/api/PayPalWebhookController.java): `backend/src/main/java/com/dreadvoice/pylos/api/PayPalWebhookController.java`
- [Webhook verifier](https://github.com/dreadvoice/pylos/blob/main/backend/src/main/java/com/dreadvoice/pylos/paypal/WebhookVerifier.java): `backend/src/main/java/com/dreadvoice/pylos/paypal/WebhookVerifier.java`
- [Event handler](https://github.com/dreadvoice/pylos/blob/main/backend/src/main/java/com/dreadvoice/pylos/notification/WebhookEventHandler.java): `backend/src/main/java/com/dreadvoice/pylos/notification/WebhookEventHandler.java`
- [Notifications](https://github.com/dreadvoice/pylos/blob/main/backend/src/main/java/com/dreadvoice/pylos/notification/NotificationRepository.java): `backend/src/main/java/com/dreadvoice/pylos/notification/NotificationRepository.java`
- [Notification endpoint](https://github.com/dreadvoice/pylos/blob/main/backend/src/main/java/com/dreadvoice/pylos/api/NotificationController.java): `backend/src/main/java/com/dreadvoice/pylos/api/NotificationController.java`

### Other components

- **Seller**
- **Conversation page**
- **PayPal**

## Connections

- Conversation page → Content adapters: provides DOM
- Content adapters → Page context: extracts context (evidence: `extension/src/content/router.ts`)
- Seller → Side panel: requests proposal
- Side panel → Extension messaging: requests context (evidence: `extension/src/sidepanel/main.tsx`)
- Side panel → Extension messaging: calls backend (evidence: `extension/src/sidepanel/main.tsx`)
- Extension messaging → Assist endpoint: posts context
- Assist endpoint → Copilot agent: invokes agent (evidence: `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 (evidence: `backend/src/main/java/com/dreadvoice/pylos/action/ActionService.java`)
- Assist endpoint → Action service: creates proposal (evidence: `backend/src/main/java/com/dreadvoice/pylos/api/AssistController.java`)
- Assist endpoint → Side panel: returns proposal
- Side panel → Confirmation cards: renders proposals (evidence: `extension/src/sidepanel/main.tsx`)
- Seller → Confirmation cards: edits and approves
- Confirmation cards → Extension messaging: submits decision (evidence: `extension/src/sidepanel/main.tsx`)
- Extension messaging → Action endpoint: posts decision
- Action endpoint → Action service: delegates decision (evidence: `backend/src/main/java/com/dreadvoice/pylos/api/ActionController.java`)
- Action service → Action validator: validates action (evidence: `backend/src/main/java/com/dreadvoice/pylos/action/ActionService.java`)
- Action service → Action executor: executes approved (evidence: `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 (evidence: `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 (evidence: `backend/src/main/java/com/dreadvoice/pylos/api/PayPalWebhookController.java`)
- Webhook endpoint → Event handler: handles verified event (evidence: `backend/src/main/java/com/dreadvoice/pylos/api/PayPalWebhookController.java`)
- Event handler → Notifications: records event (evidence: `backend/src/main/java/com/dreadvoice/pylos/notification/WebhookEventHandler.java`)
- Side panel → Notification endpoint: loads activity (evidence: `extension/src/sidepanel/main.tsx`)
- Notification endpoint → Notifications: reads notifications (evidence: `backend/src/main/java/com/dreadvoice/pylos/api/NotificationController.java`)
- Side panel → Activity feed: renders activity (evidence: `extension/src/sidepanel/main.tsx`)
- Notifications → Activity feed: feeds activity
- Seller → Settings page: sets credentials (evidence: `extension/src/options/main.tsx`)
- Settings page → Extension settings: saves settings (evidence: `extension/src/options/main.tsx`)
- Extension messaging → Extension settings: uses settings (evidence: `extension/src/background/service-worker.ts`)