# avdpro/ai2apps architecture

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

- Interactive diagram: https://gitdiagram.com/avdpro/ai2apps
- Repository: https://github.com/avdpro/ai2apps

## Overview

##### Project type and purpose
- From the README and file tree, this is a full-stack, PC-side AI Agent infrastructure (“AI2Apps”) that combines an Electron-style desktop UI, a Node.js/Express backend, a plugin-style agent engine, pluggable agent definitions, and RPA scripts. Its goal is to let users develop, serve, and share autonomous AI “agents” on the PC, avoiding cloud-only silos.

##### File structure
- Top-level entry points:
- app.js / start.js / main.mjs – bootstraps the Express server (and possibly Electron)
- AgentNodeMain.mjs – CLI entry for running headless agents
- Frontend/UI:
- ebrowser/ – Electron-style browser window (HTML/CSS/JS + preload)
- public/ + views/ – static assets and Pug templates served by Express
- Backend/API:
- routes/ – Express routers (APIChatAI, APIFiles, APIRag, APIUtils, index, ws)
- util/ – configuration, token management, user utilities, locking
- Agent Core Frameworks:
- aaee/ – core agent classes (AgentNode, AABot, AADataBase, tasks, file libs, web bots)
- agenthub/ – multi-agent orchestration, interactive terminal (AgentNodeTerm, AhSession, AhSystem, ChatSession)
- Agent Definitions (plugins):
- agents/AgentBuilder – generator agents for scaffolding new agents/projects
- agents/DrawSD, WebRpa, tabos, wechat – specialized agent kits (each with agent.json + code)
- RPA and Scripts:
- rpa/ – custom RPA flows (WebRpa.mjs, aiquery, pptstart)
- apiproxy/ – HTTP proxies to external services (e.g. OpenAI, Yahoo Finance)
- Database layer:
- aaee/AADataBaseMDB.mjs – MongoDB adapter
- aaee/AADataBaseMem.mjs – in-memory storage
- Packaging & Deployment:
- .env, package.json, my-node/ – embedded Node runtime, build scripts
- cfg/version.json – versioning

##### README for additional insights
- The architecture is “distributed PC-side”: desktop app ↔ local server ↔ agent engine ↔ external APIs.
- End-to-end lifecycle: development (AgentBuilder), serving (runtime & UI), sharing (agent.json modules).

##### Main components & interactions
a. Components
1. Desktop Client (Electron / Browser)
- ebrowser/ + public/ + views/
2. Node.js Server (Express)
- app.js, routes/
3. Agent Engine Core
- aaee/ (AgentNode, AABot, FileLib, Task, DataBase)
- agenthub/ (multi-agent orchestration, terminal UI)
4. Agent Plugins Repository
- agents/ (AgentBuilder, DrawSD, WebRpa, tabos, wechat, …)
5. RPA Scripts & Flows
- rpa/ (WebRpa, aiquery, pptstart)
6. API Proxy Layer
- apiproxy/ (ApiProxy, FetchProxy, ProxyYahooFinance)
7. Database Layer
- MongoDB or in-memory (aaee/AADataBaseMDB, AADataBaseMem)
8. Utility Layer
- util/ (SysConfig, TokenUtils, UserUtils, locker)
9. External Services
- OpenAI / LLM APIs, Web search, Finance APIs, etc.
10. CLI Entrypoints
- AgentNodeMain.mjs, start.js, main.mjs

b. Relationships & Data Flows
- Desktop Client ↔ HTTP/WebSocket ↔ Node.js Server
- Server uses util/ for config/auth
- Server invokes Agent Engine Core (aaee + agenthub) to spin up agents
- Agent Engine loads Agent Plugins from agents/ folder (via agent.json)
- Agents call RPA scripts (rpa/) and API Proxy (apiproxy/) as needed
- Agent Engine persists session or state in Database Layer
- Agents call out to External Services (OpenAI, search, finance) through the proxy
- CLI entrypoints start headless AgentNodes directly

c. Architectural patterns & design principles
- Plugin architecture for agent definitions (dynamic loading via agent.json)
- Layered design: UI / API / Engine / Plugins / Data / External Services
- Separation of concerns: AgentBuilder vs. Agent Runtime vs. Runtime Orchestration
- Use of adapters: AADataBaseMDB vs. AADataBaseMem, Apiproxy adapters

d. Key technologies & frameworks
- Node.js / Express (backend)
- Electron (desktop client)
- Pug (server-side templates)
- MongoDB (optional)
- WebSocket (real-time chat sessions)
- Python (some RPA flows)
- JavaScript modules (ESM .mjs)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Presentation Layer
    subgraph "Presentation Layer"
        direction TB
        EBrowser["Electron Window"]:::frontend
        PublicAssets["Static Assets"]:::frontend
        Views["Pug Templates"]:::frontend
    end

    %% API Layer
    subgraph "API Layer"
        direction TB
        ExpressServer["Express Server"]:::api
        Routes["Express Routes"]:::api
    end

    %% Agent Core Layer
    subgraph "Agent Engine Core"
        direction TB
        AgentCoreAAEE["aaee (Core Classes)"]:::core
        AgentCoreHub["agenthub (Orchestration)"]:::core
    end

    %% Plugin Repository
    subgraph "Agent Plugins Repository"
        direction TB
        AgentBuilder["AgentBuilder"]:::plugin
        DrawSD["DrawSD"]:::plugin
        WebRpaPlugin["WebRpa"]:::plugin
        Tabos["tabos"]:::plugin
        Wechat["wechat"]:::plugin
    end

    %% RPA Scripts
    subgraph "RPA Scripts & Flows"
        direction TB
        WebRpaScript["WebRpa.mjs"]:::rpa
        AIQuery["aiquery.mjs"]:::rpa
        PPTStart["pptstart.mjs"]:::rpa
    end

    %% API Proxy Layer
    subgraph "API Proxy Layer"
        direction TB
        ApiProxy["ApiProxy.mjs"]:::proxy
        FetchProxy["FetchProxy.mjs"]:::proxy
        ProxyYahoo["ProxyYahooFinance.mjs"]:::proxy
    end

    %% Database Layer
    subgraph "Database Layer"
        direction TB
        MongoAdapter["AADataBaseMDB"]:::data
        InMemAdapter["AADataBaseMem"]:::data
    end

    %% Utility Layer
    subgraph "Utility Layer"
        direction TB
        SysConfig["SysConfig.js"]:::util
        TokenUtils["TokenUtils.mjs"]:::util
        UserUtils["UserUtils.js"]:::util
        Locker["locker.mjs"]:::util
        ProxyCall["ProxyCall.js"]:::util
    end

    %% CLI Entrypoints
    subgraph "CLI & Entry Points"
        direction TB
        CLIEntrypoints["CLI Entrypoints"]:::cli
    end

    %% External Services
    ExternalServices["External APIs (OpenAI, Web Search, Finance)"]:::external

    %% Connections
    EBrowser -->|"HTTP/WebSocket"| ExpressServer
    PublicAssets -->|served by| ExpressServer
    Views -->|rendered by| ExpressServer

    ExpressServer -->|uses| Routes
    ExpressServer -->|uses| SysConfig
    ExpressServer -->|uses| TokenUtils
    ExpressServer -->|uses| UserUtils
    ExpressServer -->|uses| Locker

    ExpressServer -->|invokes| AgentCoreAAEE
    ExpressServer -->|invokes| AgentCoreHub

    AgentCoreAAEE -->|orchestrated by| AgentCoreHub
    AgentCoreAAEE -->|loads plugins| AgentBuilder
    AgentCoreAAEE -->|loads plugins| DrawSD
    AgentCoreAAEE -->|loads plugins| WebRpaPlugin
    AgentCoreAAEE -->|loads plugins| Tabos
    AgentCoreAAEE -->|loads plugins| Wechat

    AgentCoreAAEE -->|executes| WebRpaScript
    AgentCoreAAEE -->|executes| AIQuery
    AgentCoreAAEE -->|executes| PPTStart

    AgentCoreAAEE -->|calls| ApiProxy
    AgentCoreAAEE -->|calls| FetchProxy
    AgentCoreAAEE -->|calls| ProxyYahoo

    AgentCoreAAEE -->|persists to| MongoAdapter
    AgentCoreAAEE -->|persists to| InMemAdapter

    AgentCoreAAEE -->|uses| ProxyCall
    AgentCoreHub -->|uses| ProxyCall

    ApiProxy -->|forwards to| ExternalServices
    FetchProxy -->|forwards to| ExternalServices
    ProxyYahoo -->|forwards to| ExternalServices

    CLIEntrypoints -->|starts headless| AgentCoreAAEE
    CLIEntrypoints -->|starts headless| AgentCoreHub

    %% Click Events
    click EBrowser "https://github.com/avdpro/ai2apps/tree/main/ebrowser/"
    click PublicAssets "https://github.com/avdpro/ai2apps/tree/main/public/"
    click Views "https://github.com/avdpro/ai2apps/tree/main/views/"
    click ExpressServer "https://github.com/avdpro/ai2apps/blob/main/app.js"
    click ExpressServer "https://github.com/avdpro/ai2apps/blob/main/start.js"
    click ExpressServer "https://github.com/avdpro/ai2apps/blob/main/main.mjs"
    click Routes "https://github.com/avdpro/ai2apps/tree/main/routes/"
    click AgentCoreAAEE "https://github.com/avdpro/ai2apps/tree/main/aaee/"
    click AgentCoreHub "https://github.com/avdpro/ai2apps/tree/main/agenthub/"
    click AgentBuilder "https://github.com/avdpro/ai2apps/tree/main/agents/AgentBuilder/"
    click DrawSD "https://github.com/avdpro/ai2apps/tree/main/agents/DrawSD/"
    click WebRpaPlugin "https://github.com/avdpro/ai2apps/tree/main/agents/WebRpa/"
    click Tabos "https://github.com/avdpro/ai2apps/tree/main/agents/tabos/"
    click Wechat "https://github.com/avdpro/ai2apps/tree/main/agents/wechat/"
    click WebRpaScript "https://github.com/avdpro/ai2apps/blob/main/rpa/WebRpa.mjs"
    click AIQuery "https://github.com/avdpro/ai2apps/blob/main/rpa/aiquery.mjs"
    click PPTStart "https://github.com/avdpro/ai2apps/blob/main/rpa/pptstart.mjs"
    click ApiProxy "https://github.com/avdpro/ai2apps/blob/main/apiproxy/ApiProxy.mjs"
    click FetchProxy "https://github.com/avdpro/ai2apps/blob/main/apiproxy/FetchProxy.mjs"
    click ProxyYahoo "https://github.com/avdpro/ai2apps/blob/main/apiproxy/ProxyYahooFinance.mjs"
    click MongoAdapter "https://github.com/avdpro/ai2apps/blob/main/aaee/AADataBaseMDB.mjs"
    click InMemAdapter "https://github.com/avdpro/ai2apps/blob/main/aaee/AADataBaseMem.mjs"
    click SysConfig "https://github.com/avdpro/ai2apps/blob/main/util/SysConfig.js"
    click TokenUtils "https://github.com/avdpro/ai2apps/blob/main/util/TokenUtils.mjs"
    click UserUtils "https://github.com/avdpro/ai2apps/blob/main/util/UserUtils.js"
    click Locker "https://github.com/avdpro/ai2apps/blob/main/util/locker.mjs"
    click ProxyCall "https://github.com/avdpro/ai2apps/blob/main/util/ProxyCall.js"
    click CLIEntrypoints "https://github.com/avdpro/ai2apps/blob/main/AgentNodeMain.mjs"

    %% Styles
    classDef frontend fill:#D0E6FF,stroke:#0366D6,color:#0366D6;
    classDef api fill:#DFFFE0,stroke:#33A532,color:#27632A;
    classDef core fill:#FFF4D0,stroke:#E1A100,color:#8B5E00;
    classDef plugin fill:#FFE0F0,stroke:#D6336C,color:#842241;
    classDef rpa fill:#F0E0FF,stroke:#8041A0,color:#4B186A;
    classDef proxy fill:#E0FFFF,stroke:#20A4A0,color:#10706B;
    classDef data fill:#ECECEC,stroke:#888888,color:#444444;
    classDef util fill:#F5F5F5,stroke:#AAAAAA,color:#555555;
    classDef cli fill:#FFE8D0,stroke:#D68F2A,color:#8D5C0A;
    classDef external fill:#FFD0D0,stroke:#D63434,color:#8B1A1A;
```
