# shriyanss/js-recon architecture

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

- Interactive diagram: https://gitdiagram.com/shriyanss/js-recon
- Repository: https://github.com/shriyanss/js-recon

## Overview

1. **Overall shape**
   - This is a TypeScript/Node.js CLI toolchain, not a single app.
   - `src/index.ts` is the top-level entrypoint, and the repo is organized as a set of independent subcommands that can be run alone or chained through `run`.

2. **Command orchestration layer**
   - The `src/` tree is split by command: `lazyload`, `endpoints`, `strings`, `map`, `analyze`, `report`, `refactor`, `load`, `fingerprint`, `mcp`, `api_gateway`, `sourcemaps`, `cs_mast`, and `run`.
   - This layer is the user-facing boundary: it parses inputs, dispatches work, and writes results to files or local caches.

3. **Target acquisition and browser-driven crawling**
   - `lazyload/` is the acquisition subsystem. It discovers JavaScript resources that are not directly visible in initial HTML.
   - It contains framework-specific crawlers for Next.js, Vue, Nuxt, React, Svelte/Astro, and Angular, plus shared download/queue utilities.
   - This subsystem uses browser automation and Chromium helpers in `src/utility/`, which is important because many targets require executing pages or following client-side navigation.

4. **Framework detection and specialization**
   - `lazyload/techDetect/` fingerprints the target framework before crawling.
   - After detection, framework-specific paths diverge:
     - Next.js has the deepest support, including build IDs, manifests, script-tag harvesting, and subsequent-request discovery.
     - Vue and Nuxt have their own page-source and build-manifest analysis.
     - React, Svelte, and Angular have smaller but still specialized discovery flows.
   - This framework split is a key architectural boundary: the same toolchain adapts to different bundle formats and runtime conventions.

5. **Endpoint and client-path extraction**
   - `endpoints/` extracts HTTP endpoints and client-side routes from downloaded JS.
   - It has framework-specific report generation, including Next.js JSON/reporting helpers and path iteration utilities.
   - This module sits between raw JS acquisition and deeper code mapping: it turns discovered scripts into actionable route/API inventories.

6. **Code mapping and request reconstruction**
   - `map/` is the main static-analysis subsystem.
   - For Next.js, React, Vue, Svelte, and Angular it resolves network behavior such as `fetch`, Axios, XHR, server actions, GraphQL, and framework-specific connection patterns.
   - The `map/next_js/resolveAxios*` helpers show that request reconstruction is a major concern: the tool traces client wrappers, headers, bodies, exports, and cross-chunk references to rebuild the actual request shape.
   - This subsystem produces structured connection data that later feeds analysis and report generation.

7. **Static analysis and taint-style reasoning**
   - `analyze/` consumes mapped JS and performs higher-level analysis.
   - It includes AST and request engines plus helper routines for direct assignment, member-expression assignment, function identifier resolution, and taint flow.
   - The output is a validated structured finding set, suggesting this stage is where raw mappings are turned into security-relevant conclusions.

8. **Strings, secrets, and sourcemaps**
   - `strings/` extracts URLs, secrets, and other literals from JS assets.
   - `sourcemaps/` and sourcemap helpers inside `lazyload/` are for recovering original source or mapping minified bundles back to source context.
   - These modules are side-channel enrichment steps: they do not drive crawling, but they improve fidelity for analysis and reporting.

9. **Persistence, import, and reporting**
   - `load/` ingests exported captures from tools like Burp Suite or Caido into the project’s response cache, creating an alternate data source to live crawling.
   - `report/` initializes a report database, populates it from analysis/endpoints/mapped JSON/OpenAPI data, and generates HTML/Markdown-style outputs.
   - The architectural pattern here is “collect first, normalize into a local store, then render a report.”

10. **Automation, AI, and interactive tooling**
   - `run/` is the automation wrapper that chains the core pipeline for quick assessment.
   - `mcp/` adds an AI-facing interface: CLI chat, one-shot prompting, and an MCP stdio server, backed by command/skill/provider abstractions.
   - `refactor/` provides deobfuscation and transformation workflows, especially for webpack/React/Next.js bundles, and `api_gateway/` manages IP rotation via AWS API Gateway to bypass rate limits or blocks.
   - These are support subsystems around the core recon pipeline, extending it to automation, assistance, and operational resilience.

Main entry points: [`src/map/index.ts`](https://github.com/shriyanss/js-recon/blob/main/src/map/index.ts) (Map), [`src/lazyLoad/techDetect/index.ts`](https://github.com/shriyanss/js-recon/blob/main/src/lazyLoad/techDetect/index.ts) (Tech detect), [`src/index.ts`](https://github.com/shriyanss/js-recon/blob/main/src/index.ts) (CLI entry), [`src/lazyLoad/index.ts`](https://github.com/shriyanss/js-recon/blob/main/src/lazyLoad/index.ts) (Lazyload)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI commands"]
  node_src_index["CLI entry<br/>[index.ts]"]
  node_src_run_index["Run<br/>[index.ts]"]
end

subgraph group_acq["Acquisition"]
  node_src_lazyload_index["Lazyload<br/>acquisition command<br/>[index.ts]"]
  node_src_lazyload_techdetect["Tech detect<br/>framework fingerprinting<br/>[index.ts]"]
  node_src_lazyload_next["Next.js crawl<br/>next acquisition<br/>[NextJsCrawler.ts]"]
  node_src_lazyload_vue["Vue crawl<br/>vue acquisition"]
  node_src_lazyload_nuxt["Nuxt crawl<br/>nuxt acquisition"]
  node_src_lazyload_react["React crawl<br/>react acquisition"]
  node_src_lazyload_svelte["Svelte crawl<br/>svelte acquisition"]
  node_src_lazyload_angular["Angular crawl<br/>angular acquisition"]
end

subgraph group_map["Mapping"]
  node_src_map_index["Map<br/>[index.ts]"]
  node_src_map_next["Next map"]
  node_src_map_vue["Vue map"]
  node_src_map_react["React map"]
  node_src_map_angular["Angular map"]
  node_src_map_graphql["GraphQL<br/>[resolveGraphql.ts]"]
end

subgraph group_analysis["Analysis"]
  node_src_analyze_index["Analyze<br/>analysis command<br/>[index.ts]"]
  node_src_strings_index["Strings<br/>literal extraction<br/>[index.ts]"]
  node_src_sourcemaps_index["Sourcemaps<br/>source recovery<br/>[index.ts]"]
end

subgraph group_output["Output"]
  node_src_load_index["Load<br/>import command<br/>[index.ts]"]
  node_src_report_index["Report<br/>[index.ts]"]
end

subgraph group_support["Support"]
  node_src_mcp_index["MCP<br/>ai interface<br/>[index.ts]"]
  node_src_refactor_index["Refactor<br/>deobfuscation<br/>[index.ts]"]
  node_src_api_gateway_index["API gateway<br/>network rotation<br/>[index.ts]"]
  node_src_fingerprint_index["Fingerprint<br/>[index.ts]"]
  node_src_cs_mast_index["CS Mast<br/>aux command<br/>[index.ts]"]
  node_src_utility["Utility<br/>shared helpers<br/>[ai.ts]"]
end

node_src_index -->|"dispatches"| node_src_lazyload_index
node_src_index -->|"dispatches"| node_src_map_index
node_src_index -->|"dispatches"| node_src_analyze_index
node_src_index -->|"dispatches"| node_src_report_index
node_src_index -->|"dispatches"| node_src_run_index
node_src_index -->|"dispatches"| node_src_load_index
node_src_lazyload_index -->|"detects"| node_src_lazyload_techdetect
node_src_lazyload_techdetect -->|"next.js"| node_src_lazyload_next
node_src_lazyload_techdetect -->|"vue"| node_src_lazyload_vue
node_src_lazyload_techdetect -->|"nuxt"| node_src_lazyload_nuxt
node_src_lazyload_techdetect -->|"react"| node_src_lazyload_react
node_src_lazyload_techdetect -->|"svelte"| node_src_lazyload_svelte
node_src_lazyload_techdetect -->|"angular"| node_src_lazyload_angular
node_src_lazyload_index -.->|"uses"| node_src_utility
node_src_lazyload_index -->|"feeds"| node_src_map_index
node_src_map_index -->|"specializes"| node_src_map_next
node_src_map_index -->|"specializes"| node_src_map_vue
node_src_map_index -->|"specializes"| node_src_map_react
node_src_map_index -->|"specializes"| node_src_map_angular
node_src_map_index -->|"normalizes"| node_src_map_graphql
node_src_map_index -->|"feeds"| node_src_analyze_index
node_src_analyze_index -->|"outputs"| node_src_report_index
node_src_strings_index -.->|"enriches"| node_src_analyze_index
node_src_sourcemaps_index -.->|"enriches"| node_src_lazyload_index
node_src_sourcemaps_index -.->|"enriches"| node_src_analyze_index
node_src_load_index -->|"populates"| node_src_report_index
node_src_run_index -->|"chains"| node_src_lazyload_index
node_src_run_index -->|"chains"| node_src_map_index
node_src_run_index -->|"chains"| node_src_analyze_index
node_src_run_index -->|"chains"| node_src_report_index
node_src_mcp_index -.->|"uses"| node_src_utility
node_src_refactor_index -.->|"uses"| node_src_utility
node_src_api_gateway_index -.->|"uses"| node_src_utility
node_src_fingerprint_index -.->|"shares"| node_src_lazyload_techdetect

click node_src_index "https://github.com/shriyanss/js-recon/blob/main/src/index.ts"
click node_src_lazyload_index "https://github.com/shriyanss/js-recon/blob/main/src/lazyLoad/index.ts"
click node_src_lazyload_techdetect "https://github.com/shriyanss/js-recon/blob/main/src/lazyLoad/techDetect/index.ts"
click node_src_lazyload_next "https://github.com/shriyanss/js-recon/blob/main/src/lazyLoad/next_js/NextJsCrawler.ts"
click node_src_lazyload_vue "https://github.com/shriyanss/js-recon/blob/main/src/lazyLoad/vue/vue_discoverJsFiles.ts"
click node_src_lazyload_nuxt "https://github.com/shriyanss/js-recon/blob/main/src/lazyLoad/nuxt_js/nuxt_getFromPageSource.ts"
click node_src_lazyload_react "https://github.com/shriyanss/js-recon/blob/main/src/lazyLoad/react/react_getScriptTags.ts"
click node_src_lazyload_svelte "https://github.com/shriyanss/js-recon/blob/main/src/lazyLoad/svelte/svelte_recursivePageCrawl.ts"
click node_src_lazyload_angular "https://github.com/shriyanss/js-recon/blob/main/src/lazyLoad/angular/angular_getFromPageSource.ts"
click node_src_map_index "https://github.com/shriyanss/js-recon/blob/main/src/map/index.ts"
click node_src_map_next "https://github.com/shriyanss/js-recon/blob/main/src/map/next_js/getFetchInstances.ts"
click node_src_map_vue "https://github.com/shriyanss/js-recon/blob/main/src/map/vue_js/getViteConnections.ts"
click node_src_map_react "https://github.com/shriyanss/js-recon/blob/main/src/map/react_js/getReactConnections.ts"
click node_src_map_angular "https://github.com/shriyanss/js-recon/blob/main/src/map/angular_js/getAngularConnections.ts"
click node_src_map_graphql "https://github.com/shriyanss/js-recon/blob/main/src/map/graphql/resolveGraphql.ts"
click node_src_analyze_index "https://github.com/shriyanss/js-recon/blob/main/src/analyze/index.ts"
click node_src_strings_index "https://github.com/shriyanss/js-recon/blob/main/src/strings/index.ts"
click node_src_sourcemaps_index "https://github.com/shriyanss/js-recon/blob/main/src/sourcemaps/index.ts"
click node_src_load_index "https://github.com/shriyanss/js-recon/blob/main/src/load/index.ts"
click node_src_report_index "https://github.com/shriyanss/js-recon/blob/main/src/report/index.ts"
click node_src_run_index "https://github.com/shriyanss/js-recon/blob/main/src/run/index.ts"
click node_src_mcp_index "https://github.com/shriyanss/js-recon/blob/main/src/mcp/index.ts"
click node_src_refactor_index "https://github.com/shriyanss/js-recon/blob/main/src/refactor/index.ts"
click node_src_api_gateway_index "https://github.com/shriyanss/js-recon/blob/main/src/api_gateway/index.ts"
click node_src_fingerprint_index "https://github.com/shriyanss/js-recon/blob/main/src/fingerprint/index.ts"
click node_src_cs_mast_index "https://github.com/shriyanss/js-recon/blob/main/src/cs_mast/index.ts"
click node_src_utility "https://github.com/shriyanss/js-recon/blob/main/src/utility/ai.ts"

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_src_index,node_src_run_index toneBlue
class node_src_lazyload_index,node_src_lazyload_techdetect,node_src_lazyload_next,node_src_lazyload_vue,node_src_lazyload_nuxt,node_src_lazyload_react,node_src_lazyload_svelte,node_src_lazyload_angular toneAmber
class node_src_map_index,node_src_map_next,node_src_map_vue,node_src_map_react,node_src_map_angular,node_src_map_graphql toneMint
class node_src_analyze_index,node_src_strings_index,node_src_sourcemaps_index toneRose
class node_src_load_index,node_src_report_index toneIndigo
class node_src_mcp_index,node_src_refactor_index,node_src_api_gateway_index,node_src_fingerprint_index,node_src_cs_mast_index,node_src_utility toneTeal
```

## Components

### CLI commands

User-facing command entrypoints and orchestration

- [CLI entry](https://github.com/shriyanss/js-recon/blob/main/src/index.ts): cli entrypoint · Top-level command dispatcher · `src/index.ts`
- [Run](https://github.com/shriyanss/js-recon/blob/main/src/run/index.ts): pipeline runner · Chains the core workflow for quick assessment · `src/run/index.ts`

### Acquisition

Browser-driven crawling and framework-specific JS discovery

- [Lazyload](https://github.com/shriyanss/js-recon/blob/main/src/lazyLoad/index.ts): acquisition command · Entry for framework-aware script discovery · `src/lazyLoad/index.ts`
- [Tech detect](https://github.com/shriyanss/js-recon/blob/main/src/lazyLoad/techDetect/index.ts): framework fingerprinting · Detects target framework before specialized crawling · `src/lazyLoad/techDetect/index.ts`
- [Next.js crawl](https://github.com/shriyanss/js-recon/blob/main/src/lazyLoad/next_js/NextJsCrawler.ts): next acquisition · Deep Next.js resource, manifest, and route discovery · `src/lazyLoad/next_js/NextJsCrawler.ts`
- [Vue crawl](https://github.com/shriyanss/js-recon/blob/main/src/lazyLoad/vue/vue_discoverJsFiles.ts): vue acquisition · Vue page-source and client-side path discovery · `src/lazyLoad/vue/vue_discoverJsFiles.ts`
- [Nuxt crawl](https://github.com/shriyanss/js-recon/blob/main/src/lazyLoad/nuxt_js/nuxt_getFromPageSource.ts): nuxt acquisition · Nuxt build-manifest and source analysis · `src/lazyLoad/nuxt_js/nuxt_getFromPageSource.ts`
- [React crawl](https://github.com/shriyanss/js-recon/blob/main/src/lazyLoad/react/react_getScriptTags.ts): react acquisition · React script-tag, import, and sourcemap discovery · `src/lazyLoad/react/react_getScriptTags.ts`
- [Svelte crawl](https://github.com/shriyanss/js-recon/blob/main/src/lazyLoad/svelte/svelte_recursivePageCrawl.ts): svelte acquisition · Svelte page and recursive client-side discovery · `src/lazyLoad/svelte/svelte_recursivePageCrawl.ts`
- [Angular crawl](https://github.com/shriyanss/js-recon/blob/main/src/lazyLoad/angular/angular_getFromPageSource.ts): angular acquisition · Angular script and page-source discovery · `src/lazyLoad/angular/angular_getFromPageSource.ts`

### Mapping

Static resolution of endpoints and request behavior

- [Map](https://github.com/shriyanss/js-recon/blob/main/src/map/index.ts): mapping command · Static-analysis entry for connections and request shapes · `src/map/index.ts`
- [Next map](https://github.com/shriyanss/js-recon/blob/main/src/map/next_js/getFetchInstances.ts): next mapping · Reconstructs fetch, axios, server actions, and webpack/turbopack calls · `src/map/next_js/getFetchInstances.ts`
- [Vue map](https://github.com/shriyanss/js-recon/blob/main/src/map/vue_js/getViteConnections.ts): vue mapping · Resolves fetch, XHR, and HTTP client behavior in Vue bundles · `src/map/vue_js/getViteConnections.ts`
- [React map](https://github.com/shriyanss/js-recon/blob/main/src/map/react_js/getReactConnections.ts): react mapping · Extracts request connections from React bundles · `src/map/react_js/getReactConnections.ts`
- [Angular map](https://github.com/shriyanss/js-recon/blob/main/src/map/angular_js/getAngularConnections.ts): angular mapping · Extracts Angular request connections · `src/map/angular_js/getAngularConnections.ts`
- [GraphQL](https://github.com/shriyanss/js-recon/blob/main/src/map/graphql/resolveGraphql.ts): graphql resolver · Normalizes GraphQL request shapes · `src/map/graphql/resolveGraphql.ts`

### Analysis

Higher-level reasoning over mapped code and findings

- [Analyze](https://github.com/shriyanss/js-recon/blob/main/src/analyze/index.ts): analysis command · Runs AST and request engines over mapped code · `src/analyze/index.ts`
- [Strings](https://github.com/shriyanss/js-recon/blob/main/src/strings/index.ts): literal extraction · Extracts URLs, secrets, and other literals · `src/strings/index.ts`
- [Sourcemaps](https://github.com/shriyanss/js-recon/blob/main/src/sourcemaps/index.ts): source recovery · Entry for sourcemap-based source reconstruction · `src/sourcemaps/index.ts`

### Output

Persistence, reporting, and export surfaces

- [Load](https://github.com/shriyanss/js-recon/blob/main/src/load/index.ts): import command · Imports external captures into the local cache · `src/load/index.ts`
- [Report](https://github.com/shriyanss/js-recon/blob/main/src/report/index.ts): reporting command · Builds the report database and renders outputs · `src/report/index.ts`

### Support

Shared utilities and auxiliary workflows

- [MCP](https://github.com/shriyanss/js-recon/blob/main/src/mcp/index.ts): ai interface · Chat, one-shot prompting, and MCP server integration · `src/mcp/index.ts`
- [Refactor](https://github.com/shriyanss/js-recon/blob/main/src/refactor/index.ts): deobfuscation · Transforms and validates framework-specific bundles · `src/refactor/index.ts`
- [API gateway](https://github.com/shriyanss/js-recon/blob/main/src/api_gateway/index.ts): network rotation · Checks feasibility and generates rotated requests · `src/api_gateway/index.ts`
- [Fingerprint](https://github.com/shriyanss/js-recon/blob/main/src/fingerprint/index.ts): fingerprinting command · Standalone target fingerprinting entrypoint · `src/fingerprint/index.ts`
- [CS Mast](https://github.com/shriyanss/js-recon/blob/main/src/cs_mast/index.ts): aux command · Additional command surface for specialized workflows · `src/cs_mast/index.ts`
- [Utility](https://github.com/shriyanss/js-recon/blob/main/src/utility/ai.ts): shared helpers · Chromium, AI, sandbox, request, and path helpers · `src/utility/ai.ts`

## Connections

- CLI entry → Lazyload: dispatches · Top-level CLI routes into acquisition
- CLI entry → Map: dispatches · Top-level CLI routes into mapping
- CLI entry → Analyze: dispatches · Top-level CLI routes into analysis
- CLI entry → Report: dispatches · Top-level CLI routes into reporting
- CLI entry → Run: dispatches · Top-level CLI routes into pipeline execution
- CLI entry → Load: dispatches · Top-level CLI routes into cache import
- Lazyload → Tech detect: detects · Framework detection chooses crawl strategy
- Tech detect → Next.js crawl: next.js · Next.js-specific acquisition path
- Tech detect → Vue crawl: vue · Vue-specific acquisition path
- Tech detect → Nuxt crawl: nuxt · Nuxt-specific acquisition path
- Tech detect → React crawl: react · React-specific acquisition path
- Tech detect → Svelte crawl: svelte · Svelte-specific acquisition path
- Tech detect → Angular crawl: angular · Angular-specific acquisition path
- Lazyload → Utility: uses · Browser automation and shared helpers
- Lazyload → Map: feeds · Discovered scripts move into mapping
- Map → Next map: specializes · Next.js request reconstruction
- Map → Vue map: specializes · Vue request reconstruction
- Map → React map: specializes · React request reconstruction
- Map → Angular map: specializes · Angular request reconstruction
- Map → GraphQL: normalizes · GraphQL query and mutation shapes
- Map → Analyze: feeds · Mapped connections feed higher-level analysis
- Analyze → Report: outputs · Findings are persisted for reporting
- Strings → Analyze: enriches · Literal extraction supports analysis
- Sourcemaps → Lazyload: enriches · Source recovery improves acquisition fidelity
- Sourcemaps → Analyze: enriches · Recovered source context improves analysis
- Load → Report: populates · Imported captures fill the report database
- Run → Lazyload: chains · Automated pipeline begins with acquisition
- Run → Map: chains · Automated pipeline continues to mapping
- Run → Analyze: chains · Automated pipeline continues to analysis
- Run → Report: chains · Automated pipeline ends in reporting
- MCP → Utility: uses · AI interfaces rely on shared infrastructure
- Refactor → Utility: uses · Refactor workflows reuse helpers
- API gateway → Utility: uses · Request generation and network checks reuse helpers
- Fingerprint → Tech detect: shares · Standalone fingerprinting aligns with tech detection
