# roman-simone/autonomous-software-agent architecture

> Architecture diagram of the GitHub repository roman-simone/autonomous-software-agent, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-24). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/roman-simone/autonomous-software-agent
- Repository: https://github.com/roman-simone/autonomous-software-agent

## Overview

##### Project type and purpose
- This is a Node.js-based autonomous agent implementing the Belief-Desire-Intention (BDI) architecture.
- It interacts with the Deliveroo.js game environment via a socket API and optionally with a PDDL solver (local or remote Docker service).

##### File structure
- Top-level entry point: index.js
- Core layers under the ASAP/ folder:
- belief/      – maintains world model (agentData.js, belief.js, map.js, utilsBelief.js)
- coordination (communication in file tree) – inter-agent messaging (coordination.js)
- intention&revision – BDI control loop (agent.js, intention.js, options.js, utilsOptions.js)
- planners – domain definition and plan generation (domain.pddl, plans.js, utils_planner.js)
- Infrastructure files: config.js (parameters), socketConnection.js (game API), package.json, external PDFs.

##### Extract insights from the README
- Confirms BDI architecture, single- or multi-agent modes (MASTER/SLAVE), PDDL planning via Planutils or remote solver.
- Dependencies: Node.js, deliveroo-agent.js API, optional Docker/PDDL server.

##### Main components
a. Agent Control Layer (index.js)
- Orchestrates startup (reads config, chooses ONE/TWO mode)
b. Communication Layer
- socketConnection.js ↔ Deliveroo.js game server (REST/WebSocket)
- coordination.js ↔ peer agents (in multi-agent mode)
c. Belief Layer
- belief.js, map.js, agentData.js – stores and updates world state
d. Planning Layer
- plans.js, utils_planner.js, domain.pddl – generates or retrieves PDDL plans
- External PDDL solver service (HTTP API)
e. Intention & Revision Layer
- options.js + utilsOptions.js – generates candidate goals/options
- intention.js – executes chosen plan/actions
f. Configuration
- config.js – parameters for connection, planning, thresholds

##### Relationships and data flows
- index.js invokes socketConnection to receive environment updates → passes raw state to Belief Layer → updates internal world model.
- Belief Layer publishes a snapshot to the Intention & Revision Layer → Options module computes utilities → Intention module selects plan.
- If plan requires PDDL, Intention module calls Planning Layer → communicates with local/remote PDDL solver → receives plan steps.
- Intention module issues actions via socketConnection to the game server.
- In multi-agent mode, coordination.js sends/receives messages to/from other agents (state sharing, task handoff).

##### Architectural patterns & principles
- BDI (Belief-Desire-Intention) layered architecture
- Modular separation: communication, state management, planning, decision logic
- Externalization of PDDL planning as a service (loose coupling)
- Configurable via config.js for easy experimentation

##### Final checklist
- All major components and sub-modules clearly labeled.
- A title and brief annotation explaining the overall BDI workflow.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Title
    Title["BDI Agent Architecture"]:::infra

    %% Agent Control Layer
    subgraph "Agent Control Layer"
        index["index.js"]:::infra
    end

    %% Communication Layer
    subgraph "Communication Layer" 
        socket["socketConnection.js"]:::comm
        coord["coordination.js"]:::comm
    end

    %% Belief Layer
    subgraph "Belief Layer"
        belief["belief.js"]:::belief
        map["map.js"]:::belief
        agentData["agentData.js"]:::belief
        utilsBelief["utilsBelief.js"]:::belief
    end

    %% Intention & Revision Layer
    subgraph "Intention & Revision Layer"
        agentLoop["agent.js"]:::decision
        options["options.js"]:::decision
        utilsOptions["utilsOptions.js"]:::decision
        intention["intention.js"]:::decision
    end

    %% Planning Layer
    subgraph "Planning Layer"
        plans["plans.js"]:::planning
        utilsPlanner["utils_planner.js"]:::planning
        domain["domain.pddl"]:::planning
        solver["External PDDL Solver"]:::external
    end

    %% Configuration
    config["config.js"]:::infra

    %% External Game Server
    game["Deliveroo.js Game Server"]:::external

    %% Data Flows
    Title --> index
    index -->|"start, read config"| config
    index -->|"connect"| socket
    socket -->|"agentState"| belief
    belief -->|"worldSnapshot"| options
    options -->|"candidateGoals"| intention
    intention -->|"planRequest"| plans
    intention -->|"planRequest"| solver
    plans -->|"planResponse"| intention
    solver -->|"planResponse"| intention
    intention -->|"actionCommand"| socket
    coord ---|"peerMessage"| coord
    index -->|"init coordination"| coord

    %% Click Events
    click index "https://github.com/roman-simone/autonomous-software-agent/blob/main/ASAP/index.js"
    click socket "https://github.com/roman-simone/autonomous-software-agent/blob/main/ASAP/socketConnection.js"
    click coord "https://github.com/roman-simone/autonomous-software-agent/blob/main/ASAP/communication/coordination.js"
    click belief "https://github.com/roman-simone/autonomous-software-agent/blob/main/ASAP/belief/belief.js"
    click map "https://github.com/roman-simone/autonomous-software-agent/blob/main/ASAP/belief/map.js"
    click agentData "https://github.com/roman-simone/autonomous-software-agent/blob/main/ASAP/belief/agentData.js"
    click utilsBelief "https://github.com/roman-simone/autonomous-software-agent/blob/main/ASAP/belief/utilsBelief.js"
    click plans "https://github.com/roman-simone/autonomous-software-agent/blob/main/ASAP/planners/plans.js"
    click utilsPlanner "https://github.com/roman-simone/autonomous-software-agent/blob/main/ASAP/planners/utils_planner.js"
    click domain "https://github.com/roman-simone/autonomous-software-agent/blob/main/ASAP/planners/domain.pddl"
    click options "https://github.com/roman-simone/autonomous-software-agent/blob/main/ASAP/intention&revision/options.js"
    click utilsOptions "https://github.com/roman-simone/autonomous-software-agent/blob/main/ASAP/intention&revision/utilsOptions.js"
    click intention "https://github.com/roman-simone/autonomous-software-agent/blob/main/ASAP/intention&revision/intention.js"
    click agentLoop "https://github.com/roman-simone/autonomous-software-agent/blob/main/ASAP/intention&revision/agent.js"
    click config "https://github.com/roman-simone/autonomous-software-agent/blob/main/ASAP/config.js"

    %% Styles
    classDef comm fill:#a2d2ff,stroke:#1a73e8,color:#000
    classDef belief fill:#b7e4c7,stroke:#40916c,color:#000
    classDef decision fill:#ffba08,stroke:#ff8800,color:#000
    classDef planning fill:#cdb4db,stroke:#9d4edd,color:#000
    classDef infra fill:#f0efeb,stroke:#6c757d,color:#000
    classDef external fill:#ffadad,stroke:#d00000,color:#000
```
