# automaapp/automa architecture

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

- Interactive diagram: https://gitdiagram.com/automaapp/automa
- Repository: https://github.com/automaapp/automa

## Overview

#### Purpose and Runtime Shape
Automa is a Chrome/Firefox browser extension for building, scheduling, and running block-connected browser automations: form filling, scraping, screenshots, and data workflows. Browser-specific extension manifests define the product boundary: `src/manifest.chrome.json`, `src/manifest.firefox.json`.

#### Extension Entry Points
The extension has separate execution contexts:
- Background/service-worker orchestration: `src/background/index.js`
- Webpage content-script runtime: `src/content/index.js`
- Full workflow-management UI in the new-tab page: `src/newtab/index.js`, `src/newtab/App.vue`
- Popup quick actions: `src/popup/index.js`
- Isolated execution/sandbox contexts for code and expressions: `src/execute/index.js`, `src/sandbox/index.js`
- Offscreen document support, likely for background capabilities unavailable in the worker: `src/offscreen/index.js`

#### Workflow Authoring and Persistence
The new-tab Vue application is the primary control plane for browsing, editing, sharing, recording, scheduling, and inspecting workflows. Its graph editor and block configuration surface are centered on `src/components/newtab/workflow/WorkflowEditor.vue`, `src/components/newtab/workflow/WorkflowEditBlock.vue`, and `src/components/newtab/workflow/edit/`.
State is organized through Pinia-style stores for workflows, packages, folders, users, and hosted/shared/team workflows: `src/stores/workflow.js`, `src/stores/package.js`, `src/stores/hostedWorkflow.js`. Local workflow data and execution logs are persisted through `src/db/storage.js` and `src/db/logs.js`.

#### Execution Engine
The workflow engine interprets workflow graphs, manages lifecycle/state, dispatches block implementations, and records activity. Its core boundary is `src/workflowEngine/WorkflowEngine.js`, with management/worker coordination in `src/workflowEngine/WorkflowManager.js` and `src/workflowEngine/WorkflowWorker.js`. Block dispatch is centralized in `src/workflowEngine/blocksHandler.js`; concrete handlers cover browser, control-flow, data, webhook, Google, and code operations under `src/workflowEngine/blocksHandler/`.
Execution state and logs are explicit concerns: `src/workflowEngine/WorkflowState.js` and `src/workflowEngine/WorkflowLogger.js`.

#### Browser and Page-Interaction Boundary
The engine cannot directly manipulate page DOM in all contexts, so page actions are delegated to content scripts. `src/content/blocksHandler.js` dispatches DOM-level handlers such as forms, selectors, keyboard events, scraping, screenshots, and uploads in `src/content/blocksHandler/`. Background-to-browser/tab operations are abstracted by `src/service/browser-api/BrowserAPIService.js` and `src/service/browser-api/BrowserAPIEventHandler.js`. Messaging is therefore a primary control flow: UI/background initiates a run, engine selects handlers, and browser/content contexts execute privileged or page-local actions.

#### Recording and Element Selection
Interactive authoring inside target pages is a distinct content-script subsystem. Workflow recording captures browser events and turns them into blocks via `src/content/services/recordWorkflow/recordEvents.js` and `src/content/services/recordWorkflow/addBlock.js`. Selector tooling injects a Vue UI, discovers candidate elements, and generates selectors through `src/content/elementSelector/index.js`, `src/content/elementSelector/generateElementsSelector.js`, and `src/content/handleSelector.js`.

#### Triggers, Scheduling, and External Integrations
Background listeners and trigger utilities activate workflows from schedules, visits, shortcuts, events, and webhooks: `src/background/BackgroundWorkflowTriggers.js`, `src/background/BackgroundEventsListeners.js`, `src/utils/workflowTrigger.js`. The engine also exposes integration-oriented blocks for webhooks, Google Drive, and Google Sheets, implemented in `src/workflowEngine/blocksHandler/handlerWebhook.js`, `src/workflowEngine/blocksHandler/handlerGoogleDrive.js`, and `src/workflowEngine/blocksHandler/handlerGoogleSheets.js`. User-authored JavaScript and conditions cross into the sandbox boundary through `src/sandbox/utils/handleJavascriptBlock.js` and `src/sandbox/utils/handleConditionCode.js`.

#### Build and Distribution
Webpack builds browser-targeted extension bundles using `webpack.config.js`; package scripts support Chrome and Firefox development/production outputs. A required local pass-key module protects cryptographic or encrypted-flow functionality referenced by `secrets.blank.js` and `src/utils/decryptFlow.js`.

Main entry points: [`src/content/index.js`](https://github.com/automaapp/automa/blob/main/src/content/index.js) (Content runtime), [`src/manifest.chrome.json`](https://github.com/automaapp/automa/blob/main/src/manifest.chrome.json) (Browser manifests), [`src/background/index.js`](https://github.com/automaapp/automa/blob/main/src/background/index.js) (Background worker), [`src/newtab/index.js`](https://github.com/automaapp/automa/blob/main/src/newtab/index.js) (New-tab Vue app)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_extension["Extension contexts"]
  node_manifests["Browser manifests<br/>extension boundary"]
  node_background{{"Background worker<br/>orchestrator<br/>[index.js]"}}
  node_popup["Popup actions<br/>extension UI<br/>[index.js]"]
  node_triggers["Triggers and listeners<br/>activation service"]
  node_sandbox{{"Code sandbox<br/>isolated runtime<br/>[index.js]"}}
  node_offscreen["Offscreen runtime<br/>extension document<br/>[index.js]"]
end

subgraph group_authoring["Authoring and data"]
  node_newtab["New-tab Vue app<br/>control-plane UI<br/>[index.js]"]
  node_workflow_editor["Workflow editor<br/>graph editor<br/>[WorkflowEditor.vue]"]
  node_stores["Workflow stores<br/>Pinia state<br/>[workflow.js]"]
  node_storage[("Workflow storage<br/>local persistence<br/>[storage.js]")]
end

subgraph group_execution["Workflow execution"]
  node_workflow_manager["Workflow manager<br/>run coordinator<br/>[WorkflowManager.js]"]
  node_workflow_engine{{"Workflow engine<br/>graph interpreter<br/>[WorkflowEngine.js]"}}
  node_block_dispatch["Block dispatch<br/>handler router<br/>[blocksHandler.js]"]
  node_execution_state[("Run state and logs<br/>execution records<br/>[WorkflowState.js]")]
end

subgraph group_page["Browser and page runtime"]
  node_browser_api["Browser API service<br/>tab and browser adapter"]
  node_content{{"Content runtime<br/>page content script<br/>[index.js]"}}
  node_dom_dispatch["DOM block dispatch<br/>page handler router<br/>[blocksHandler.js]"]
  node_recording["Workflow recorder<br/>page authoring service<br/>[recordEvents.js]"]
  node_selector_tool["Element selector<br/>page authoring tool<br/>[index.js]"]
end

node_build["Webpack distribution<br/>browser bundle build<br/>[webpack.config.js]"]

node_manifests -->|"declares"| node_background
node_manifests -->|"injects"| node_content
node_manifests -->|"opens"| node_newtab
node_newtab -->|"hosts"| node_workflow_editor
node_workflow_editor -->|"edits through"| node_stores
node_stores -->|"persists"| node_storage
node_newtab -->|"starts runs"| node_workflow_manager
node_popup -->|"sends quick actions"| node_background
node_background -->|"hosts"| node_triggers
node_triggers -->|"activates"| node_workflow_manager
node_workflow_manager -->|"coordinates"| node_workflow_engine
node_workflow_engine -->|"selects blocks"| node_block_dispatch
node_workflow_engine -->|"records lifecycle"| node_execution_state
node_block_dispatch -->|"evaluates code"| node_sandbox
node_block_dispatch -->|"uses browser operations"| node_browser_api
node_browser_api -->|"messages page runtime"| node_content
node_content -->|"routes page actions"| node_dom_dispatch
node_content -.->|"captures authoring events"| node_recording
node_content -.->|"runs element picking"| node_selector_tool
node_background -.->|"delegates unavailable capabilities"| node_offscreen
node_build -->|"packages"| node_manifests

click node_manifests "https://github.com/automaapp/automa/blob/main/src/manifest.chrome.json"
click node_background "https://github.com/automaapp/automa/blob/main/src/background/index.js"
click node_newtab "https://github.com/automaapp/automa/blob/main/src/newtab/index.js"
click node_workflow_editor "https://github.com/automaapp/automa/blob/main/src/components/newtab/workflow/WorkflowEditor.vue"
click node_stores "https://github.com/automaapp/automa/blob/main/src/stores/workflow.js"
click node_storage "https://github.com/automaapp/automa/blob/main/src/db/storage.js"
click node_popup "https://github.com/automaapp/automa/blob/main/src/popup/index.js"
click node_triggers "https://github.com/automaapp/automa/blob/main/src/background/BackgroundWorkflowTriggers.js"
click node_workflow_manager "https://github.com/automaapp/automa/blob/main/src/workflowEngine/WorkflowManager.js"
click node_workflow_engine "https://github.com/automaapp/automa/blob/main/src/workflowEngine/WorkflowEngine.js"
click node_block_dispatch "https://github.com/automaapp/automa/blob/main/src/workflowEngine/blocksHandler.js"
click node_execution_state "https://github.com/automaapp/automa/blob/main/src/workflowEngine/WorkflowState.js"
click node_sandbox "https://github.com/automaapp/automa/blob/main/src/sandbox/index.js"
click node_browser_api "https://github.com/automaapp/automa/blob/main/src/service/browser-api/BrowserAPIService.js"
click node_content "https://github.com/automaapp/automa/blob/main/src/content/index.js"
click node_dom_dispatch "https://github.com/automaapp/automa/blob/main/src/content/blocksHandler.js"
click node_recording "https://github.com/automaapp/automa/blob/main/src/content/services/recordWorkflow/recordEvents.js"
click node_selector_tool "https://github.com/automaapp/automa/blob/main/src/content/elementSelector/index.js"
click node_offscreen "https://github.com/automaapp/automa/blob/main/src/offscreen/index.js"
click node_build "https://github.com/automaapp/automa/blob/main/webpack.config.js"

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_manifests,node_background,node_popup,node_triggers,node_sandbox,node_offscreen toneBlue
class node_newtab,node_workflow_editor,node_stores,node_storage toneAmber
class node_workflow_manager,node_workflow_engine,node_block_dispatch,node_execution_state toneMint
class node_browser_api,node_content,node_dom_dispatch,node_recording,node_selector_tool toneRose
class node_build toneNeutral
```

## Components

### Extension contexts

- [Browser manifests](https://github.com/automaapp/automa/blob/main/src/manifest.chrome.json): extension boundary · Chrome and Firefox product entry definitions. · `src/manifest.chrome.json`
- [Background worker](https://github.com/automaapp/automa/blob/main/src/background/index.js): orchestrator · `src/background/index.js`
- [Popup actions](https://github.com/automaapp/automa/blob/main/src/popup/index.js): extension UI · `src/popup/index.js`
- [Triggers and listeners](https://github.com/automaapp/automa/blob/main/src/background/BackgroundWorkflowTriggers.js): activation service · Schedules, visits, shortcuts, events, and webhooks activate workflows. · `src/background/BackgroundWorkflowTriggers.js`
- [Code sandbox](https://github.com/automaapp/automa/blob/main/src/sandbox/index.js): isolated runtime · Evaluates user JavaScript and conditions. · `src/sandbox/index.js`
- [Offscreen runtime](https://github.com/automaapp/automa/blob/main/src/offscreen/index.js): extension document · Supports capabilities unavailable in the service worker. · `src/offscreen/index.js`

### Authoring and data

- [New-tab Vue app](https://github.com/automaapp/automa/blob/main/src/newtab/index.js): control-plane UI · `src/newtab/index.js`
- [Workflow editor](https://github.com/automaapp/automa/blob/main/src/components/newtab/workflow/WorkflowEditor.vue): graph editor · `src/components/newtab/workflow/WorkflowEditor.vue`
- [Workflow stores](https://github.com/automaapp/automa/blob/main/src/stores/workflow.js): Pinia state · Workflows, packages, folders, users, and hosted workflows. · `src/stores/workflow.js`
- [Workflow storage](https://github.com/automaapp/automa/blob/main/src/db/storage.js): local persistence · Stores local workflows and execution logs. · `src/db/storage.js`

### Workflow execution

- [Workflow manager](https://github.com/automaapp/automa/blob/main/src/workflowEngine/WorkflowManager.js): run coordinator · `src/workflowEngine/WorkflowManager.js`
- [Workflow engine](https://github.com/automaapp/automa/blob/main/src/workflowEngine/WorkflowEngine.js): graph interpreter · Executes workflow lifecycle and block traversal. · `src/workflowEngine/WorkflowEngine.js`
- [Block dispatch](https://github.com/automaapp/automa/blob/main/src/workflowEngine/blocksHandler.js): handler router · Routes browser, control-flow, data, webhook, Google, and code blocks. · `src/workflowEngine/blocksHandler.js`
- [Run state and logs](https://github.com/automaapp/automa/blob/main/src/workflowEngine/WorkflowState.js): execution records · `src/workflowEngine/WorkflowState.js`

### Browser and page runtime

- [Browser API service](https://github.com/automaapp/automa/blob/main/src/service/browser-api/BrowserAPIService.js): tab and browser adapter · `src/service/browser-api/BrowserAPIService.js`
- [Content runtime](https://github.com/automaapp/automa/blob/main/src/content/index.js): page content script · `src/content/index.js`
- [DOM block dispatch](https://github.com/automaapp/automa/blob/main/src/content/blocksHandler.js): page handler router · Performs forms, selectors, keyboard, scraping, screenshots, and uploads. · `src/content/blocksHandler.js`
- [Workflow recorder](https://github.com/automaapp/automa/blob/main/src/content/services/recordWorkflow/recordEvents.js): page authoring service · Captures browser events and creates workflow blocks. · `src/content/services/recordWorkflow/recordEvents.js`
- [Element selector](https://github.com/automaapp/automa/blob/main/src/content/elementSelector/index.js): page authoring tool · Injects selection UI and generates element selectors. · `src/content/elementSelector/index.js`

### Other components

- [Webpack distribution](https://github.com/automaapp/automa/blob/main/webpack.config.js): browser bundle build · Builds Chrome and Firefox extension outputs. · `webpack.config.js`

## Connections

- Browser manifests → Background worker: declares
- Browser manifests → Content runtime: injects
- Browser manifests → New-tab Vue app: opens
- New-tab Vue app → Workflow editor: hosts
- Workflow editor → Workflow stores: edits through
- Workflow stores → Workflow storage: persists
- New-tab Vue app → Workflow manager: starts runs
- Popup actions → Background worker: sends quick actions
- Background worker → Triggers and listeners: hosts
- Triggers and listeners → Workflow manager: activates
- Workflow manager → Workflow engine: coordinates
- Workflow engine → Block dispatch: selects blocks
- Workflow engine → Run state and logs: records lifecycle
- Block dispatch → Code sandbox: evaluates code
- Block dispatch → Browser API service: uses browser operations
- Browser API service → Content runtime: messages page runtime
- Content runtime → DOM block dispatch: routes page actions
- Content runtime → Workflow recorder: captures authoring events
- Content runtime → Element selector: runs element picking
- Background worker → Offscreen runtime: delegates unavailable capabilities
- Webpack distribution → Browser manifests: packages
