# alberthupa/langgraph_skeleton architecture

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

- Interactive diagram: https://gitdiagram.com/alberthupa/langgraph_skeleton
- Repository: https://github.com/alberthupa/langgraph_skeleton

## Overview

##### Project Type and Purpose
- The project is a skeleton (scaffold) for the Langgraph system used in the project “Scaled Stewardship”. Its purpose is to provide a basic, modular framework to run conversational workflows with language model (LLM) integration.
- It is not a full-fledged full-stack application—instead, it concentrates on internal logic, state management, workflow orchestration, and LLM-based agents with prompt management. There’s also a hint on integration being planned but not yet implemented (no frontend or deployment details).

##### Analyzing the File Structure
- Top-Level Files:
- run.py: Serves as the entry point where workflows (static or interactive) are initiated.
- requirements.txt and .gitignore: Standard project configuration.
- src Directory: The heart of the code.
- agents/: Contains different agent implementations (intent_catcher, vanilla_agent_a, vanilla_agent_b). These represent logical modules that process or pass along conversation parts.
- graph/: Holds the core components of the application’s logic:
▪ state.py: Defines the data structure (AgentState) that holds session/user data and other placeholders.
▪ workflow.py: Contains two workflows – a simple one and another specially crafted for intent catching.
- llm_clients.py: Provides integration with external language model clients (for now, an AzureChatOpenAI example).
- prompt_fetcher.py and prompts folder: Handle the retrieval of preset prompt texts used throughout the system for standard agent responses.
- auxiliary_code_snippets: Contains experimental or integration-related snippets (as seen with Databricks).

##### Core Components & Their Relationships
- Application Entry Point (run.py):
- This file manages command-line parameters for interactive/stream vs. static modes and orchestrates the initiation of the correct workflow.
- Graph Module (src/graph):
- “state.py” defines how the state is maintained (all message data, user data, and developer options).
- “workflow.py” outlines the data flow logic—both the simple conversational chain (e.g., vanilla agents passing conversation) and the intent-catching chain.
- Agents (src/agents):
- They are invoked within the workflows to process user inputs. For example, the “intent_catcher” agent is specially designed to process and reframe user intent before handing it off to additional LLM-based agents.
- LLM Clients (src/llm_clients.py):
- Connects to external LLM services, abstracting away API complexities.
- Prompt Fetcher & Prompts (src/prompt_fetcher.py and src/prompts):
- Dynamically load text prompts needed by agents (e.g., system prompts for intent catching, scope definitions for retrieval).
- Auxiliary Code:
- The code snippets under “auxiliary_code_snippets” reflect experimental integrations (like Databricks) that might be used for additional functionalities such as stream output handling.

##### Architectural Patterns and Design Principles
- Modularity: The code is divided into discrete modules (agents, graph, LLM clients, prompt fetching) that interact via well-defined interfaces.
- Workflow Orchestration: The “graph” directory separates the state definition from the workflow processes, indicating a clear separation of concerns (state management vs. process logic).
- Extensibility: With separate agents and a prompt management system, additional functionalities can be added without disturbing existing components.
- Environment Configuration: The use of a .env file indicates that sensitive configuration data (API keys, endpoints) is externalized from the code.

##### Final Assembly
- Detail the “workflow” path for a conversation:
- From run.py (which selects static or interactive mode) → to graph state initialization and workflow execution → leading to sequential (or branching) calls to agents → interactions with LLM Client for responses → prompt fetching as needed.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Core Components
    A["Entry Point (run.py)"]:::core
    B["Workflow Manager (graph/workflow.py)"]:::core
    C["State Management (graph/state.py)"]:::core
    A -->|"triggers"| B
    B -->|"initializes_state"| C

    %% Agents Layer
    subgraph "Agents Layer"
        D["Intent Catcher (Agent)"]:::agent
        E["Vanilla Agent A"]:::agent
        F["Vanilla Agent B"]:::agent
    end
    B -->|"invokes_agents"| D
    B -->|"invokes_agents"| E
    B -->|"invokes_agents"| F

    %% External Integrations
    subgraph "External Integrations"
        G["LLM Client (llm_clients.py)"]:::external
        H["Prompt Fetcher & Prompts"]:::external
        I["Auxiliary Code (Databricks)"]:::aux
    end
    %% Connections between Agents and LLM Client
    D ---|"calls_API"| G
    E ---|"calls_API"| G
    F ---|"calls_API"| G

    %% Agents fetching prompts
    D ---|"retrieves_prompt"| H
    E ---|"retrieves_prompt"| H
    F ---|"retrieves_prompt"| H

    %% Workflow Manager interactions with external services
    B ---|"communicates_with"| G
    G -->|"returns_response"| B

    %% Configuration (non-clickable; external config file)
    J["Configuration (.env)"]:::config
    A ---|"loads_config"| J
    G ---|"loads_config"| J

    %% Click Events
    click A "https://github.com/alberthupa/langgraph_skeleton/blob/main/run.py"
    click B "https://github.com/alberthupa/langgraph_skeleton/blob/main/src/graph/workflow.py"
    click C "https://github.com/alberthupa/langgraph_skeleton/blob/main/src/graph/state.py"
    click D "https://github.com/alberthupa/langgraph_skeleton/blob/main/src/agents/intent_catcher.py"
    click E "https://github.com/alberthupa/langgraph_skeleton/blob/main/src/agents/vanilla_agent_a.py"
    click F "https://github.com/alberthupa/langgraph_skeleton/blob/main/src/agents/vanilla_agent_b.py"
    click G "https://github.com/alberthupa/langgraph_skeleton/blob/main/src/llm_clients.py"
    click H "https://github.com/alberthupa/langgraph_skeleton/blob/main/src/prompt_fetcher.py"
    click I "https://github.com/alberthupa/langgraph_skeleton/blob/main/src/auxiliary_code_snippets/databricks/output_message_catcher_for_stream.py"

    %% Styles
    classDef core fill:#AED6F1,stroke:#1B4F72,stroke-width:2px;
    classDef agent fill:#F5B7B1,stroke:#922B21,stroke-width:2px;
    classDef external fill:#DAF7A6,stroke:#145A32,stroke-width:2px;
    classDef aux fill:#D7BDE2,stroke:#4A235A,stroke-width:2px,stroke-dasharray: 5 5;
    classDef config fill:#FAD7A0,stroke:#7D6608,stroke-width:2px;
```
