# bsorrentino/langgraph4j architecture

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

- Interactive diagram: https://gitdiagram.com/bsorrentino/langgraph4j
- Repository: https://github.com/bsorrentino/langgraph4j

## Overview

##### Project type and purpose
- This is a multi-module, open-source Java framework (LangGraph4j) plus accompanying tools (CLI samples, code generator, web-based “studio”) for building stateful, multi-agent LLM applications.

##### File structure
- Top-level modules:
- core/ — the heart of the library (state graphs, nodes, edges, checkpointing, visualization).
- agent-executor/ — a CLI sample that uses core + LangChain4j or Spring AI to run agents.
- generator/ — a Java backend + Next.js “builder-webui” frontend to scaffold LangGraph code.
- langchain4j/, spring-ai/, spring-ai-agent/ — integration libraries and samples for different LLM stacks.
- studio/ — multiple server implementations (jetty/, quarkus/, springboot/) plus a pure frontend webui/ module.
- samples/ & how-tos/ — example projects and notebooks.
- pom.xml + CI workflows + scripts — build and deploy pipelines.

##### README for additional insights
- References to external LLM services (OpenAI, Azure OpenAI, custom tools).
- The “generator” is a visual builder linked in the docs.

a. Main components
- Core Library (langgraph4j-core)
- Integration Libraries (langchain4j, spring-ai modules)
- CLI Sample (agent-executor)
- Generator Service
- Generator Backend (Java)
- Builder-WebUI (Next.js)
- Studio Players
- Backend Servers (Jetty, Quarkus, Spring Boot)
- Frontend WebUI (static assets served by any server)
- External Systems
- LLM Providers (OpenAI, Azure, Ollama, etc.)
- Tool Endpoints (e.g., custom functions)
b. Relationships & interactions
1. Developer apps depend on Core → build graphs → at runtime call LLM Providers.
2. CLI Sample uses Core + Integration Lib to orchestrate agent loop.
3. Generator UI → calls Generator Backend → produces scaffolded Java code (uses Core).
4. Studio Frontend → issues HTTP requests to chosen Backend (Jetty/Quarkus/Spring Boot) → backends load Core + serializers + stateful graph engine → call LLM Providers and return streaming updates to UI.
5. How-tos and samples illustrate direct Core usage or integration patterns.
c. Architectural patterns & principles
- Multi-module Maven layering:
Core at the base → integration modules → tools & services → UIs.
- Plugin-style extensibility: each module plugs into Core via well-defined APIs (NodeAction, EdgeAction, Serializer).
- Microservice pattern for Studio: interchangeable servers serving the same WebUI.
- Reactive/async streaming between engine and UI (CompletableFuture & WebSockets or SSE).
d. Key technologies/frameworks
- Java 17, Maven multi-module
- Spring Boot, Quarkus, Jetty for servers
- Next.js for Builder-WebUI & WebUI frontend
- CompletableFuture & java-async-generator for streaming
- CI/CD via GitHub Actions (deploy to Maven Central & GitHub Pages)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User
    User["Developer / End User"]:::external

    %% Library Modules
    subgraph "Library Modules"
        direction TB
        Core["Core Library<br/>(langgraph4j-core)"]:::library
        LangChain4j["Integration Library<br/>(langchain4j)"]:::library
        SpringAI["Integration Library<br/>(spring-ai)"]:::library
        SpringAIAgent["Sample Executor<br/>(spring-ai-agent)"]:::library
        AgentCLI["CLI Sample<br/>(agent-executor)"]:::library
    end

    %% Generator
    subgraph "Generator Service"
        direction TB
        BuilderUI["Builder-WebUI<br/>(Next.js)"]:::ui
        GenBackend["Generator Backend<br/>(Java)"]:::backend
    end

    %% Studio
    subgraph "Studio"
        direction TB
        StudioWebUI["Studio Frontend WebUI"]:::ui
        subgraph "Studio Servers"
            direction TB
            StudioBase["Studio Base Module"]:::library
            Jetty["Jetty Server"]:::backend
            Quarkus["Quarkus Server"]:::backend
            SpringBoot["Spring Boot Server"]:::backend
        end
    end

    %% Samples & How-tos
    subgraph "Examples & Guides"
        direction TB
        Samples["Sample Projects"]:::doc
        HowTos["How-tos & Notebooks"]:::doc
    end

    %% External Systems
    subgraph "External Services"
        direction TB
        LLM["LLM Providers"]:::external
        Tools["Tool Endpoints"]:::external
    end

    %% Dependencies (compile-time)
    LangChain4j -->|depends on| Core
    SpringAI -->|depends on| Core
    SpringAIAgent -->|depends on| Core
    AgentCLI -->|depends on| Core
    AgentCLI -->|uses| LangChain4j
    AgentCLI -->|uses| SpringAI

    GenBackend -->|depends on| Core

    StudioBase -->|depends on| Core
    Jetty -->|extends| StudioBase
    Quarkus -->|extends| StudioBase
    SpringBoot -->|extends| StudioBase

    %% Runtime interactions
    User -->|uses| BuilderUI
    BuilderUI -->|HTTP API| GenBackend
    GenBackend -->|generates code via| Core

    User -->|uses| StudioWebUI
    StudioWebUI -->|HTTP requests| Jetty
    StudioWebUI -->|HTTP requests| Quarkus
    StudioWebUI -->|HTTP requests| SpringBoot

    Jetty -->|loads| Core
    Quarkus -->|loads| Core
    SpringBoot -->|loads| Core

    Core -->|calls| LLM
    Core -->|invokes| Tools

    User -->|views| Samples
    User -->|views| HowTos

    %% Click events
    click Core "https://github.com/bsorrentino/langgraph4j/tree/main/core/"
    click AgentCLI "https://github.com/bsorrentino/langgraph4j/tree/main/agent-executor/"
    click LangChain4j "https://github.com/bsorrentino/langgraph4j/tree/main/langchain4j/"
    click SpringAI "https://github.com/bsorrentino/langgraph4j/tree/main/spring-ai/"
    click SpringAIAgent "https://github.com/bsorrentino/langgraph4j/tree/main/spring-ai-agent/"
    click GenBackend "https://github.com/bsorrentino/langgraph4j/tree/main/generator/src/"
    click BuilderUI "https://github.com/bsorrentino/langgraph4j/tree/main/generator/builder-webui/"
    click StudioBase "https://github.com/bsorrentino/langgraph4j/tree/main/studio/base/"
    click Jetty "https://github.com/bsorrentino/langgraph4j/tree/main/studio/jetty/"
    click Quarkus "https://github.com/bsorrentino/langgraph4j/tree/main/studio/quarkus/"
    click SpringBoot "https://github.com/bsorrentino/langgraph4j/tree/main/studio/springboot/"
    click StudioWebUI "https://github.com/bsorrentino/langgraph4j/tree/main/studio/webui/"
    click HowTos "https://github.com/bsorrentino/langgraph4j/tree/main/how-tos/"
    click Samples "https://github.com/bsorrentino/langgraph4j/tree/main/samples/"

    %% Styling
    classDef library fill:#add8e6,stroke:#000,color:#000
    classDef backend fill:#90ee90,stroke:#000,color:#000
    classDef ui fill:#ffffe0,stroke:#000,color:#000
    classDef external fill:#f08080,stroke:#000,color:#000
    classDef doc fill:#f0e68c,stroke:#000,color:#000
```
