How automaapp/automa works
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: content/index.js Content runtime · manifest.chrome.json Browser manifests · background/index.js Background worker · newtab/index.js New-tab Vue app
Components 20
Extension contexts
- Browser manifests · Chrome and Firefox product entry definitions.
src/manifest.chrome.json - Background worker
src/background/index.js - Popup actions
src/popup/index.js - Triggers and listeners · Schedules, visits, shortcuts, events, and webhooks activate workflows.
src/background/BackgroundWorkflowTriggers.js - Code sandbox · Evaluates user JavaScript and conditions.
src/sandbox/index.js - Offscreen runtime · Supports capabilities unavailable in the service worker.
src/offscreen/index.js
Authoring and data
- New-tab Vue app
src/newtab/index.js - Workflow editor
src/components/newtab/workflow/WorkflowEditor.vue - Workflow stores · Workflows, packages, folders, users, and hosted workflows.
src/stores/workflow.js - Workflow storage · Stores local workflows and execution logs.
src/db/storage.js
Workflow execution
- Workflow manager
src/workflowEngine/WorkflowManager.js - Workflow engine · Executes workflow lifecycle and block traversal.
src/workflowEngine/WorkflowEngine.js - Block dispatch · Routes browser, control-flow, data, webhook, Google, and code blocks.
src/workflowEngine/blocksHandler.js - Run state and logs
src/workflowEngine/WorkflowState.js
Browser and page runtime
- Browser API service
src/service/browser-api/BrowserAPIService.js - Content runtime
src/content/index.js - DOM block dispatch · Performs forms, selectors, keyboard, scraping, screenshots, and uploads.
src/content/blocksHandler.js - Workflow recorder · Captures browser events and creates workflow blocks.
src/content/services/recordWorkflow/recordEvents.js - Element selector · Injects selection UI and generates element selectors.
src/content/elementSelector/index.js
Other components
- Webpack distribution · Builds Chrome and Firefox extension outputs.
webpack.config.js
Connections 21
- 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