# rapiercraft/n8n-nodes-alterlab architecture

> Architecture diagram of the GitHub repository rapiercraft/n8n-nodes-alterlab, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/rapiercraft/n8n-nodes-alterlab
- Repository: https://github.com/rapiercraft/n8n-nodes-alterlab

## Overview

1. **Repository role**
   - This is an **n8n community node package** named `n8n-nodes-alterlab`.
   - Its purpose is to expose **AlterLab’s web-scraping API** as an n8n workflow node so workflows can send URLs and receive scraped content back.

2. **Core runtime boundary**
   - The package is a **Node.js / TypeScript** library, not a standalone app.
   - It runs inside the **n8n host process** as a custom node extension and depends on n8n’s node/credential SDK conventions.

3. **Main functional subsystem: AlterLab node**
   - The central implementation lives under `nodes/AlterLab/AlterLab.node.ts`.
   - `AlterLab.node.json` is the node manifest used by n8n to describe the node’s UI, inputs, outputs, and behavior.
   - This is the primary execution unit that maps n8n workflow items into AlterLab API calls and returns results back into the workflow.

4. **Authentication subsystem**
   - Two credential types are defined under `credentials/`:
     - `AlterLabApi.credentials.ts` for API key authentication.
     - `AlterLabOAuth2Api.credentials.ts` for OAuth2-based sign-in.
   - These form a separate boundary from the node logic: the node consumes credentials, but credential handling is encapsulated in dedicated n8n credential definitions.

5. **External service dependency**
   - The package is a client for the **AlterLab SaaS API**.
   - That external platform performs the actual scraping, anti-bot handling, JavaScript rendering, extraction, screenshot/PDF/OCR, and tier selection described in the README.
   - The node is therefore mostly an orchestration and data-mapping layer between n8n and AlterLab.

6. **Workflow data flow**
   - Input typically enters as one or more n8n items containing a URL and optional scrape options.
   - The node sends those parameters to AlterLab, then receives a response containing fields such as markdown, text, raw HTML, structured JSON, billing metadata, and optional artifact URLs.
   - The node flattens this into n8n-friendly JSON output for downstream nodes.

7. **Outputs and downstream integration**
   - The output contract is designed for workflow chaining:
     - human/LLM-friendly text like `markdown`
     - machine-readable structured data like `json` / `filteredContent`
     - operational metadata like `billing.cost` and `billing.tier`
     - optional artifact links like `screenshotUrl` and `pdfUrl`
   - This makes the node a producer for other n8n nodes such as filters, sheet sinks, Slack, Notion, databases, or AI steps.

8. **Execution modes and scrape orchestration**
   - The README indicates support for modes such as `auto`, `html`, `js`, `pdf`, and `ocr`, plus extraction profiles and custom schemas/prompts.
   - Architecturally, this means the node is not just a raw fetch wrapper; it is a **parameterized request orchestrator** that lets workflows choose scraping strategy and output shape.

9. **Build and packaging layer**
   - `package.json`, `tsconfig.json`, and `gulpfile.js` indicate a build pipeline that compiles TypeScript into distributable JavaScript for n8n.
   - The package is published to npm and intended to be installed via n8n’s community node mechanism or standard npm installation.

10. **Release and CI/CD boundary**
   - GitHub Actions under `.github/workflows/` handle:
     - CI validation
     - automated publishing to npm on release
     - project automation
   - This separates source development from package distribution and enforces the package’s compiled output before publication.

11. **Repo structure and assets**
   - `assets/` contains branding and screenshots used primarily for the README and marketplace presentation.
   - These do not affect runtime behavior, but they signal that the repo is a packaged integration distributed through npm and n8n’s UI.

12. **Operational assumptions**
   - The package assumes network access to AlterLab’s API and a configured credential in n8n.
   - Any scaling, anti-bot bypass, browser rendering, proxying, or extraction intelligence happens outside the repo in the AlterLab platform, not locally in the node.

13. **Diagram takeaway**
   - The architecture is best drawn as: **n8n workflow item(s) → AlterLab node → AlterLab credentials → AlterLab API service → structured scrape response → downstream n8n nodes**.
   - The repo itself contains the node adapter, credential definitions, packaging/build logic, and release automation around that external API integration.

Main entry points: [`nodes/AlterLab/AlterLab.node.ts`](https://github.com/rapiercraft/n8n-nodes-alterlab/blob/main/nodes/AlterLab/AlterLab.node.ts) (AlterLab node), [`package.json`](https://github.com/rapiercraft/n8n-nodes-alterlab/blob/main/package.json) (Package config), [`gulpfile.js`](https://github.com/rapiercraft/n8n-nodes-alterlab/blob/main/gulpfile.js) (Build script), [`nodes/AlterLab/AlterLab.node.json`](https://github.com/rapiercraft/n8n-nodes-alterlab/blob/main/nodes/AlterLab/AlterLab.node.json) (Node manifest)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["n8n runtime"]
  node_workflow_items(("Workflow items<br/>n8n input"))
  node_alterlab_node["AlterLab node<br/>n8n node<br/>[AlterLab.node.ts]"]
  node_node_manifest["Node manifest<br/>n8n schema<br/>[AlterLab.node.json]"]
  node_request_orchestrator{{"Request orchestration<br/>scrape modes"}}
  node_response_mapper["Response mapper<br/>output shaping"]
end

subgraph group_auth["Authentication"]
  node_api_key_cred["API key<br/>credential"]
  node_oauth2_cred["OAuth2 login<br/>credential"]
end

subgraph group_external["External service"]
  node_alterlab_api[("AlterLab API<br/>SaaS backend")]
  node_billing_meta["Billing data<br/>usage metadata"]
  node_artifact_urls["Artifacts<br/>result links"]
end

subgraph group_delivery["Build & release"]
  node_npm_pkg["Package config<br/>npm metadata<br/>[package.json]"]
  node_tsconfig["TypeScript config<br/>compiler config<br/>[tsconfig.json]"]
  node_gulp_build["Build script<br/>compile pipeline<br/>[gulpfile.js]"]
  node_ci_workflow["CI workflow<br/>github actions<br/>[ci.yml]"]
  node_publish_workflow["Publish workflow<br/>github actions<br/>[publish.yml]"]
  node_project_auto["Project automation<br/>github actions"]
end

subgraph group_assets["Assets"]
  node_branding_assets["Branding<br/>static assets"]
end

node_workflow_items -->|"input"| node_alterlab_node
node_node_manifest -->|"describes"| node_alterlab_node
node_alterlab_node -->|"builds"| node_request_orchestrator
node_request_orchestrator -->|"uses"| node_api_key_cred
node_request_orchestrator -->|"uses"| node_oauth2_cred
node_request_orchestrator -->|"calls"| node_alterlab_api
node_alterlab_api -->|"returns"| node_response_mapper
node_response_mapper -->|"includes"| node_billing_meta
node_response_mapper -->|"includes"| node_artifact_urls
node_response_mapper -->|"outputs"| node_alterlab_node
node_alterlab_node -->|"produces"| node_workflow_items
node_npm_pkg -->|"scripts"| node_gulp_build
node_tsconfig -->|"configures"| node_gulp_build
node_gulp_build -->|"compiles"| node_alterlab_node
node_ci_workflow -->|"validates"| node_gulp_build
node_publish_workflow -->|"publishes"| node_npm_pkg
node_project_auto -->|"automates"| node_npm_pkg
node_branding_assets -->|"supports"| node_npm_pkg

click node_alterlab_node "https://github.com/rapiercraft/n8n-nodes-alterlab/blob/main/nodes/AlterLab/AlterLab.node.ts"
click node_node_manifest "https://github.com/rapiercraft/n8n-nodes-alterlab/blob/main/nodes/AlterLab/AlterLab.node.json"
click node_api_key_cred "https://github.com/rapiercraft/n8n-nodes-alterlab/blob/main/credentials/AlterLabApi.credentials.ts"
click node_oauth2_cred "https://github.com/rapiercraft/n8n-nodes-alterlab/blob/main/credentials/AlterLabOAuth2Api.credentials.ts"
click node_npm_pkg "https://github.com/rapiercraft/n8n-nodes-alterlab/blob/main/package.json"
click node_tsconfig "https://github.com/rapiercraft/n8n-nodes-alterlab/blob/main/tsconfig.json"
click node_gulp_build "https://github.com/rapiercraft/n8n-nodes-alterlab/blob/main/gulpfile.js"
click node_ci_workflow "https://github.com/rapiercraft/n8n-nodes-alterlab/blob/main/.github/workflows/ci.yml"
click node_publish_workflow "https://github.com/rapiercraft/n8n-nodes-alterlab/blob/main/.github/workflows/publish.yml"
click node_project_auto "https://github.com/rapiercraft/n8n-nodes-alterlab/blob/main/.github/workflows/project-auto-add.yml"
click node_branding_assets "https://github.com/rapiercraft/n8n-nodes-alterlab/tree/main/assets"

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_workflow_items,node_alterlab_node,node_node_manifest,node_request_orchestrator,node_response_mapper toneBlue
class node_api_key_cred,node_oauth2_cred toneAmber
class node_alterlab_api,node_billing_meta,node_artifact_urls toneMint
class node_npm_pkg,node_tsconfig,node_gulp_build,node_ci_workflow,node_publish_workflow,node_project_auto toneRose
class node_branding_assets toneIndigo
```

## Components

### n8n runtime

Custom node code that runs inside the n8n host process.

- **Workflow items**: n8n input · Incoming n8n items carrying URLs and scrape options.
- [AlterLab node](https://github.com/rapiercraft/n8n-nodes-alterlab/blob/main/nodes/AlterLab/AlterLab.node.ts): n8n node · Main execution unit that maps workflow items to AlterLab requests and returns results. · `nodes/AlterLab/AlterLab.node.ts`
- [Node manifest](https://github.com/rapiercraft/n8n-nodes-alterlab/blob/main/nodes/AlterLab/AlterLab.node.json): n8n schema · n8n UI and behavior definition for the AlterLab node. · `nodes/AlterLab/AlterLab.node.json`
- **Request orchestration**: scrape modes · Selects scraping mode, extraction profile, and output shape for each request.
- **Response mapper**: output shaping · Flattens AlterLab responses into n8n-friendly JSON for downstream steps.

### Authentication

n8n credential definitions used by the node.

- [API key](https://github.com/rapiercraft/n8n-nodes-alterlab/blob/main/credentials/AlterLabApi.credentials.ts): credential · Credential definition for AlterLab API key authentication. · `credentials/AlterLabApi.credentials.ts`
- [OAuth2 login](https://github.com/rapiercraft/n8n-nodes-alterlab/blob/main/credentials/AlterLabOAuth2Api.credentials.ts): credential · Credential definition for AlterLab OAuth2 authentication. · `credentials/AlterLabOAuth2Api.credentials.ts`

### External service

AlterLab SaaS API that performs scraping and extraction.

- **AlterLab API**: SaaS backend · External scraping service that executes rendering, extraction, OCR, and artifact generation.
- **Billing data**: usage metadata · Cost and tier metadata returned with scrape results.
- **Artifacts**: result links · Optional screenshot and PDF links returned by the service.

### Build & release

Compilation, packaging, CI, and publishing automation.

- [Package config](https://github.com/rapiercraft/n8n-nodes-alterlab/blob/main/package.json): npm metadata · Package metadata and scripts for distribution. · `package.json`
- [TypeScript config](https://github.com/rapiercraft/n8n-nodes-alterlab/blob/main/tsconfig.json): compiler config · TypeScript compilation settings for the library. · `tsconfig.json`
- [Build script](https://github.com/rapiercraft/n8n-nodes-alterlab/blob/main/gulpfile.js): compile pipeline · Gulp-based build and packaging pipeline. · `gulpfile.js`
- [CI workflow](https://github.com/rapiercraft/n8n-nodes-alterlab/blob/main/.github/workflows/ci.yml): github actions · Validation workflow for source and build checks. · `.github/workflows/ci.yml`
- [Publish workflow](https://github.com/rapiercraft/n8n-nodes-alterlab/blob/main/.github/workflows/publish.yml): github actions · Automated npm publishing workflow for releases. · `.github/workflows/publish.yml`
- [Project automation](https://github.com/rapiercraft/n8n-nodes-alterlab/blob/main/.github/workflows/project-auto-add.yml): github actions · Repository automation for project management. · `.github/workflows/project-auto-add.yml`

### Assets

Presentation and marketplace resources.

- [Branding](https://github.com/rapiercraft/n8n-nodes-alterlab/tree/main/assets): static assets · Screenshots and brand assets used in README and marketplace presentation. · `assets`

## Connections

- Workflow items → AlterLab node: input · n8n items enter the node for processing.
- Node manifest → AlterLab node: describes · Manifest defines node UI, inputs, outputs, and behavior.
- AlterLab node → Request orchestration: builds · Node converts workflow parameters into scrape requests.
- Request orchestration → API key: uses · API key credentials can authorize requests.
- Request orchestration → OAuth2 login: uses · OAuth2 credentials can authorize requests.
- Request orchestration → AlterLab API: calls · Requests are sent to the AlterLab scraping service.
- AlterLab API → Response mapper: returns · Service returns scraped content and metadata.
- Response mapper → Billing data: includes · Mapped output exposes cost and tier information.
- Response mapper → Artifacts: includes · Mapped output can include screenshot and PDF links.
- Response mapper → AlterLab node: outputs · Node emits flattened JSON back into the workflow.
- AlterLab node → Workflow items: produces · Workflow continues with the node's output items.
- Package config → Build script: scripts · Package scripts drive the build pipeline.
- TypeScript config → Build script: configures · TypeScript settings shape compilation output.
- Build script → AlterLab node: compiles · Source node code is compiled for distribution.
- CI workflow → Build script: validates · CI checks the build and package behavior.
- Publish workflow → Package config: publishes · Release workflow publishes the package to npm.
- Project automation → Package config: automates · Project automation supports repository workflow management.
- Branding → Package config: supports · Assets support README and marketplace presentation.