# matheusbuniotto/goagent architecture

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

- Interactive diagram: https://gitdiagram.com/matheusbuniotto/goagent
- Repository: https://github.com/matheusbuniotto/goagent

## Overview

##### Project Type and Purpose
- This is a bare-bones Go implementation of an AI agent (“goAgent”) with a hexagonal (ports-and-adapters) architecture.
- The core goal is to let the agent invoke “tools” (file operations, interaction utilities, etc.) without relying on any SDK.

##### Key Components (to appear
a. Core Agent (agent/agent.go) – the domain logic.
b. Orchestrator (main.go) – bootstraps the agent, wires up tools, parses flags for model selection.
c. Ports (tools/definitions.go) – declare ToolDefinition and ToolFunction types (these are your “ports” interfaces).
d. Adapters (tools/adapter.go) – implement the ports by wrapping each ToolDefinition into a ToolAdapter.
e. Tool Implementations (tools/file_tools.go, tools/interaction_tools.go) – concrete logic for each tool, invoked by adapters.
f. External AI Providers – raw HTTP clients calling OpenAI or Gemini APIs.
g. (Omit tests, go.mod, README.md, .gitignore per instructions.)

##### Relationships and Data Flow
- main.go → constructs a list of ToolAdapters (adapters) that satisfy the Ports defined in definitions.go.
- main → instantiates the Agent, passing in the list of adapters.
- Agent receives a user prompt → consults an LLM (OpenAI/Gemini) → parses LLM response to find a tool invocation.
- Agent calls ToolAdapter.Execute(input) → adapter calls the underlying ToolFunction (the port implementation).
- ToolFunction may read/write files (via file_tools) or run interactions (via interaction_tools).
- Agent collects the result → possibly loops back to the LLM or returns final output to the user.

##### Architectural Patterns and Design Principles
- Hexagonal Architecture (Ports & Adapters)
- Clear separation of concerns:
- Ports (definitions.go) declare interfaces for tools
- Adapters (adapter.go) implement those interfaces
- Tool implementations contain business logic, isolated from agent orchestration
- Dependency inversion: the core Agent depends only on the Ports, not on concrete tool logic

##### Detail
- Exactly how definitions.go (Ports) sit alongside adapter.go (Adapters).
- Make it explicit that each ToolDefinition in definitions.go is a port interface, and ToolAdapter in adapter.go implements it.
- Fact that tools live in their own sub‐package, keeping the core agent independent of concrete implementations.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Orchestration Layer
    subgraph "Orchestration Layer"
        Orchestrator["main.go"]:::orchestration
    end

    %% Core Domain
    subgraph "Core Domain"
        Agent["agent/agent.go"]:::core
    end

    %% Ports Layer
    subgraph "Ports Layer"
        Ports["tools/definitions.go"]:::ports
    end

    %% Adapters Layer
    subgraph "Adapters Layer"
        Adapter["tools/adapter.go"]:::adapters
    end

    %% Tool Implementations
    subgraph "Tool Implementations"
        FileTools["tools/file_tools.go"]:::impl
        InteractionTools["tools/interaction_tools.go"]:::impl
    end

    %% External AI Providers
    subgraph "External AI Providers"
        OpenAI["OpenAI API"]:::external
        Gemini["Gemini API"]:::external
    end

    %% Relationships
    Orchestrator -->|"reads definitions & wires adapters"| Ports
    Orchestrator -->|"constructs ToolAdapters"| Adapter
    Orchestrator -->|"instantiates Agent with adapters"| Agent

    Agent -->|"calls Execute() on adapters"| Adapter
    Agent -->|"HTTP request to AI"| OpenAI
    Agent -->|"HTTP request to AI"| Gemini
    OpenAI -->|"response returns to"| Agent
    Gemini -->|"response returns to"| Agent

    Adapter -->|"invokes port implementation"| FileTools
    Adapter -->|"invokes port implementation"| InteractionTools

    %% Click Events
    click Orchestrator "https://github.com/matheusbuniotto/goagent/blob/main/main.go"
    click Agent "https://github.com/matheusbuniotto/goagent/blob/main/agent/agent.go"
    click Ports "https://github.com/matheusbuniotto/goagent/blob/main/tools/definitions.go"
    click Adapter "https://github.com/matheusbuniotto/goagent/blob/main/tools/adapter.go"
    click FileTools "https://github.com/matheusbuniotto/goagent/blob/main/tools/file_tools.go"
    click InteractionTools "https://github.com/matheusbuniotto/goagent/blob/main/tools/interaction_tools.go"

    %% Styles
    classDef orchestration fill:#FFD580,stroke:#E69A00,color:#000;
    classDef core fill:#B3E5FC,stroke:#039BE5,color:#000;
    classDef ports fill:#C8E6C9,stroke:#388E3C,color:#000;
    classDef adapters fill:#FFE0B2,stroke:#FB8C00,color:#000;
    classDef impl fill:#F0F4C3,stroke:#AFB42B,color:#000;
    classDef external fill:#E1BEE7,stroke:#8E24AA,color:#000;
```
