# dpacheco2001/agentsbmemlayer architecture

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

- Interactive diagram: https://gitdiagram.com/dpacheco2001/agentsbmemlayer
- Repository: https://github.com/dpacheco2001/agentsbmemlayer

## Overview

##### Project Type and Purpose
- This is a full-stack research application demonstrating an AI agent with persistent, graph-based memory.
- The backend (Python + Flask/WebSockets) manages conversations, memory storage (Neo4j), and LLM calls.
- The frontend (React + Vite + Tailwind + Shadcn/UI) visualizes the memory graph in 3D and provides a chat interface.

##### File Structure Analysis
- Top level:
- app/frontend → React UI code (TSX, components, pages, UI primitives, hooks, services)
- app/main.py & app/main_ws.py → Python entry points (REST + WebSocket servers)
- app/myagent → Core “agent” logic: audio streaming, graph manipulation, state management, prompt tools.
- requirements.txt → Python dependencies (Flask, websockets, Neo4j driver, LangChain/LangGraph).
- import_relationships.py → Data-bootstrap script for Neo4j.
- Supporting folders: downloads (audio files), local_images, output_file.json.

##### Architectural Insights from README
- Communication: WebSocket between frontend and backend for real-time memory exploration.
- Persistence: Neo4j graph database for nodes/edges representing memories.
- Extensibility: Multi-model support via LangChain/LangGraph adapters.
- UI: React Force Graph for 3D graph, custom “neural” theme with Tailwind + Shadcn/UI.

##### Main Components
a. Frontend Layer
- Browser (React App)
- UI Sub-components: ChatInterface, BrainVisualization, GraphVisualization, NodeEditor/RelationshipEditor
- WebSocketService (frontend/src/services/websocketService.js)
b. Backend Layer
- WebSocket Server (main_ws.py) for real-time messages
- REST API Server (main.py) for auxiliary endpoints
- Agent Core (app/myagent):
- audio_streaming.py
- graph.py (build/update memory graph)
- utils/ (configuration, models, nodes_edges, prompts, state, tools, image_proxy)
c. Persistence Layer
- Neo4j Graph Database
d. External Services Layer
- LLM Providers (OpenAI, Anthropic, Google, DeepSeek, Ollama, etc.)
- Optional LangSmith tracing endpoint
e. Static/Data Assets
- Local image store (local_images)
- Downloaded audio (downloads)

##### Relationships & Data Flow
- User types in ChatInterface → Frontend WebSocketService sends message → Backend WebSocket Server.
- Backend routes to Agent Core →
- Query/Update Neo4j (memory retrieval/storage)
- Invoke LLM(s) via LangChain/LangGraph → generate response and memory updates.
- Agent Core returns new graph data and chat response via WebSocket → Frontend updates UI: GraphVisualization + ChatInterface.
- import_relationships.py populates Neo4j in advance; main.py exposes any RESTful diagnostics or config endpoints.

##### Architectural Patterns & Principles
- Layered Architecture: UI → API/Communication → Core Domain → Persistence → External Integrations
- Component-Based Frontend with reusable UI primitives (Shadcn/UI + Tailwind)
- Micro-service-style separation of realtime (WebSocket) vs. request/response (REST).
- Domain-driven design inside “myagent” package (clear separation of graph logic, prompts, state).

## Diagram (Mermaid)

```mermaid
graph TD
  %% Frontend Layer
  subgraph "Frontend App"
    direction TB
    DevServer["React/Vite Dev Server (port 8080)"]:::frontend
    ChatInterface["ChatInterface"]:::frontend
    BrainVis["BrainVisualization"]:::frontend
    GraphVis["GraphVisualization"]:::frontend
    NodeEditor["NodeEditor"]:::frontend
    RelEditor["RelationshipEditor"]:::frontend
    WebSocketService["WebSocketService"]:::frontend
    Hooks["Hooks (useWebSocket)"]:::frontend
    UIPrims["UI Primitives (Shadcn/UI + Tailwind)"]:::frontend
  end

  %% Backend Layer
  subgraph "Backend Services"
    direction TB
    RESTServer["REST API Server\n(main.py)"]:::backend
    WSServer["WebSocket Server\n(main_ws.py)"]:::backend

    subgraph "Agent Core"
      direction TB
      Audio["audio_streaming.py"]:::backend
      GraphMod["graph.py"]:::backend
      TestCore["test.py"]:::backend
      subgraph "Utils"
        direction TB
        Config["configuration.py"]:::backend
        ImageProxy["image_proxy.py"]:::backend
        Models["models.py"]:::backend
        NodesEdges["nodes_edges.py"]:::backend
        Prompts["prompts.py"]:::backend
        State["state.py"]:::backend
        Tools["tools.py"]:::backend
      end
    end
  end

  %% Persistence
  Neo4j["Neo4j Graph Database\n(bolt://localhost:7687)"]:::db
  Bootstrap["import_relationships.py"]:::db

  %% External Services
  subgraph "External Services"
    direction TB
    LLM["LLM Providers\n(OpenAI, Anthropic, Google, etc.)"]:::external
    LangSmith["LangSmith Tracing Endpoint"]:::external
  end

  %% Static Assets
  Downloads["downloads/"]:::static
  LocalImages["local_images/"]:::static

  %% Connections
  ChatInterface -->|"chat_message"| WebSocketService
  WebSocketService -->|"ws://localhost:6789"| WSServer
  DevServer --> ChatInterface
  DevServer --> BrainVis
  DevServer --> GraphVis
  BrainVis --> WebSocketService
  GraphVis --> WebSocketService
  NodeEditor --> WebSocketService
  RelEditor --> WebSocketService

  WSServer -->|"route to Agent"| GraphMod
  WSServer --> Audio
  WSServer --> TestCore
  GraphMod --> Neo4j
  GraphMod --> Bootstrap
  Audio --> Neo4j
  GraphMod --> Models
  GraphMod --> Prompts
  GraphMod --> State
  GraphMod --> NodesEdges
  GraphMod --> Tools
  GraphMod --> ImageProxy
  GraphMod --> Config
  GraphMod --> LLM
  GraphMod --> LangSmith

  RESTServer --> Neo4j
  RESTServer --> Config

  LLM -->|response| GraphMod
  Neo4j -->|memory data| GraphMod
  WSServer -->|"graph_update & chat_response"| WebSocketService
  WebSocketService --> ChatInterface
  WebSocketService --> BrainVis
  WebSocketService --> GraphVis

  %% Static
  Audio --> Downloads
  GraphMod --> LocalImages

  %% Click Events
  click DevServer "https://github.com/dpacheco2001/agentsbmemlayer/blob/main/app/frontend/src/main.tsx"
  click ChatInterface "https://github.com/dpacheco2001/agentsbmemlayer/blob/main/app/frontend/src/components/ChatInterface.jsx"
  click BrainVis "https://github.com/dpacheco2001/agentsbmemlayer/blob/main/app/frontend/src/components/BrainVisualization.jsx"
  click GraphVis "https://github.com/dpacheco2001/agentsbmemlayer/blob/main/app/frontend/src/components/GraphVisualization.tsx"
  click NodeEditor "https://github.com/dpacheco2001/agentsbmemlayer/blob/main/app/frontend/src/components/NodeEditor.tsx"
  click RelEditor "https://github.com/dpacheco2001/agentsbmemlayer/blob/main/app/frontend/src/components/RelationshipEditor.tsx"
  click WebSocketService "https://github.com/dpacheco2001/agentsbmemlayer/blob/main/app/frontend/src/services/websocketService.js"
  click Hooks "https://github.com/dpacheco2001/agentsbmemlayer/blob/main/app/frontend/src/hooks/useWebSocket.js"
  click UIPrims "https://github.com/dpacheco2001/agentsbmemlayer/tree/main/app/frontend/src/components/ui/"
  click RESTServer "https://github.com/dpacheco2001/agentsbmemlayer/blob/main/app/main.py"
  click WSServer "https://github.com/dpacheco2001/agentsbmemlayer/blob/main/app/main_ws.py"
  click Audio "https://github.com/dpacheco2001/agentsbmemlayer/blob/main/app/myagent/audio_streaming.py"
  click GraphMod "https://github.com/dpacheco2001/agentsbmemlayer/blob/main/app/myagent/graph.py"
  click TestCore "https://github.com/dpacheco2001/agentsbmemlayer/blob/main/app/myagent/test.py"
  click Config "https://github.com/dpacheco2001/agentsbmemlayer/blob/main/app/myagent/utils/configuration.py"
  click ImageProxy "https://github.com/dpacheco2001/agentsbmemlayer/blob/main/app/myagent/utils/image_proxy.py"
  click Models "https://github.com/dpacheco2001/agentsbmemlayer/blob/main/app/myagent/utils/models.py"
  click NodesEdges "https://github.com/dpacheco2001/agentsbmemlayer/blob/main/app/myagent/utils/nodes_edges.py"
  click Prompts "https://github.com/dpacheco2001/agentsbmemlayer/blob/main/app/myagent/utils/prompts.py"
  click State "https://github.com/dpacheco2001/agentsbmemlayer/blob/main/app/myagent/utils/state.py"
  click Tools "https://github.com/dpacheco2001/agentsbmemlayer/blob/main/app/myagent/utils/tools.py"
  click Bootstrap "https://github.com/dpacheco2001/agentsbmemlayer/blob/main/import_relationships.py"
  click Downloads "https://github.com/dpacheco2001/agentsbmemlayer/tree/main/downloads/"
  click LocalImages "https://github.com/dpacheco2001/agentsbmemlayer/tree/main/local_images/"

  %% Styles
  classDef frontend fill:#D0E8FF,stroke:#0366D6,color:#0366D6;
  classDef backend fill:#DFFFE0,stroke:#228B22,color:#228B22;
  classDef db fill:#FFE5B4,stroke:#FF8C00,color:#FF8C00;
  classDef external fill:#F3E6FF,stroke:#800080,color:#800080;
  classDef static fill:#F0F0F0,stroke:#808080,color:#808080;
```
