# duongnguyen321/manus-js architecture

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

- Interactive diagram: https://gitdiagram.com/duongnguyen321/manus-js
- Repository: https://github.com/duongnguyen321/manus-js

## Overview

##### Project Type and Purpose
- Manus JS is a CLI-based, AI-powered web research “agent.”
- Purpose: automate web research by driving a real browser, scraping page content, and using LLMs (OpenAI/OpenRouter via LangChain or direct API) to plan tasks, gather information, synthesize findings, and present results.

##### File Structure
Top-level files and folders:
- configs/
– configs.ts (env/config loader)
– puppeteer.ts (browser connection settings)
- index.ts – entry point and CLI handler
- src/
– agent/
· initializeAgent.ts & initializeAgentLangChain.ts (agent bootstrap + task planning + synthesis)
· tools/
‑ browserTools.ts (Puppeteer Real Browser wrapper)
‑ performResearch.ts (orchestrates page visits and text extraction)
– utils/
· logger.ts (console logging)
· puppeteer.ts (low-level Puppeteer helpers)
– test.ts (local test harness)
- package.json, tsconfig.json, Bun-oriented scripts

##### README for Architecture Insights
- Two modes for agent initialization: direct OpenAI or via LangChain + OpenRouter.
- Runtime flow:
1. Choose provider (index.ts)
2. Task analysis & plan (initializeAgent*.ts)
3. Perform research (browserTools + performResearch)
4. Synthesize & generate response (initializeAgent*.ts)

##### Sketch the Main Components
a. CLI Interface
– index.ts + test.ts
b. Configuration Loader
– configs/configs.ts (reads .env)
– configs/puppeteer.ts
c. Agent Orchestrator
– initializeAgent.ts
– initializeAgentLangChain.ts
d. Research Tools
– browserTools.ts (connects to real browser)
– performResearch.ts (page navigation + scraping)
e. Browser Engine (external)
– Google Chrome driven by puppeteer-real-browser
f. LLM Provider (external)
– OpenAI / OpenRouter APIs (via LangChain or direct HTTP)
g. Utilities
– logger.ts, puppeteer.ts

##### Architectural Patterns and Principles
- Agent-tool pattern: agent orchestrates “tools” (browserScraper, LLM)
- Separation of concerns: config loading, agent logic, I/O, browser control, LLM calls
- Extensibility: easily swap provider (OpenAI vs OpenRouter via LangChain)
- Resilience: retry logic in browserTools (recursive connect)

##### Technologies, Frameworks, Libraries
- Bun (runtime) + TypeScript
- puppeteer-real-browser + Puppeteer
- LangChain or custom OpenAI/OpenRouter API calls

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interaction
    subgraph "User Interaction"
        CLI["CLI Interface\n(index.ts)"]:::code
        TEST["Test Harness\n(src/test.ts)"]:::code
    end

    %% Configuration Loader
    subgraph "Configuration Loader"
        CFG1["configs.ts\n(env loader)"]:::code
        CFG2["puppeteer.ts\n(browser settings)"]:::code
    end

    %% Agent Orchestrator
    subgraph "Agent Orchestrator"
        INIT1["initializeAgent.ts"]:::code
        INIT2["initializeAgentLangChain.ts"]:::code
    end

    %% Research Tools
    subgraph "Research Tools"
        BT["browserTools.ts"]:::code
        PR["performResearch.ts"]:::code
    end

    %% External Services
    LLM["LLM Provider\n(OpenAI/OpenRouter)"]:::external
    BROWSER["Browser Engine\n(Google Chrome)"]:::browser

    %% Connections
    CLI -->|"load config"| CFG1
    CLI -->|"load config"| CFG2
    CFG1 -->|"init agent"| INIT1
    CFG1 -->|"init agent"| INIT2
    CFG2 -->|"init agent"| INIT1
    CFG2 -->|"init agent"| INIT2

    INIT1 -->|"getPlan()"| LLM
    INIT2 -->|"getPlan()"| LLM

    INIT1 -->|"performResearch()"| BT
    INIT2 -->|"performResearch()"| BT

    BT -->|"launch & scrape"| BROWSER
    BROWSER -->|"raw data"| PR
    PR -->|"raw data"| INIT1
    PR -->|"raw data"| INIT2

    INIT1 -->|"synthesize()"| LLM
    INIT2 -->|"synthesize()"| LLM
    LLM -->|"final answer"| CLI

    TEST -->|"bypass CLI"| INIT1
    TEST -->|"bypass CLI"| INIT2

    %% Click Events
    click CLI "https://github.com/duongnguyen321/manus-js/blob/main/index.ts"
    click TEST "https://github.com/duongnguyen321/manus-js/blob/main/src/test.ts"
    click CFG1 "https://github.com/duongnguyen321/manus-js/blob/main/configs/configs.ts"
    click CFG2 "https://github.com/duongnguyen321/manus-js/blob/main/configs/puppeteer.ts"
    click INIT1 "https://github.com/duongnguyen321/manus-js/blob/main/src/agent/tools/initializeAgent.ts"
    click INIT2 "https://github.com/duongnguyen321/manus-js/blob/main/src/agent/tools/initializeAgentLangChain.ts"
    click BT "https://github.com/duongnguyen321/manus-js/blob/main/src/agent/tools/browserTools.ts"
    click PR "https://github.com/duongnguyen321/manus-js/blob/main/src/agent/tools/performResearch.ts"
    click Logger "https://github.com/duongnguyen321/manus-js/blob/main/src/utils/logger.ts"
    click PuppeteerUtil "https://github.com/duongnguyen321/manus-js/blob/main/src/utils/puppeteer.ts"
    click Helpers "https://github.com/duongnguyen321/manus-js/blob/main/src/helpers.ts"

    %% Legend
    subgraph "Legend"
        CodeModule["Code Module"]:::code
        ExternalService["External Service"]:::external
        BrowserEngine["Browser Engine"]:::browser
    end

    %% Styles
    classDef code fill:#cce5ff,stroke:#3399ff,stroke-width:1px;
    classDef external fill:#d4edda,stroke:#28a745,stroke-width:1px;
    classDef browser fill:#fff3cd,stroke:#ffcd39,stroke-width:1px;
```
