# emarco177/langgraph-customer-support architecture

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

- Interactive diagram: https://gitdiagram.com/emarco177/langgraph-customer-support
- Repository: https://github.com/emarco177/langgraph-customer-support

## Overview

##### Project type and purpose
- This is a backend-focused AI-driven “customer support control flow” service built in Python/Flask.
- It orchestrates a multi-step conversation (“Human-in-the-Loop”), persists intermediate state in SQLite, and invokes LLMs via LangGraph/LangChain/MistralAI.

##### File structure
- app.py: Flask entry point / HTTP API.
- db/profile.json & SQLite files under `db/`: persistent store for conversation checkpoints.
- `support_agent/` package:
- consts.py: global constants/config.
- graph.py: builds and wires the LangGraph control-flow graph.
- state.py: graph-execution state management (persistence hooks).
- nodes/: discrete steps in the flow (e.g., verify_information, assistant_node, safe_agent).
- tools/: safe utility wrappers for external LLM tool calls.
- static/: assets (logo, docs).
- pyproject.toml: dependency management (Flask, LangGraph, LangChain, MistralAI SDK).

##### Extract additional insights from the README
- Human-in-Loop feature: the graph waits for user input until all required fields are gathered.
- Persistent Storage: after each node, the `state.py` module checkpoints the graph to SQLite.
- Execution ENV: Flask server uses environment variables for API keys and tracing.

##### Components
a. Client
- HTTP client (browser or CLI) that calls the Flask API endpoints.
b. Flask Server (app.py)
- Entry point exposing `/support` or similar endpoints.
- Parses requests, dispatches to Graph Engine.
c. Graph Engine (support_agent/graph.py)
- Orchestrates nodes in a directed control-flow graph.
d. Node Modules (support_agent/nodes)
- verify_information: collects and validates user data.
- safe_agent: enforces safety checks.
- assistant_node: formulates LLM responses.
- …any custom steps.
e. Tools Layer (support_agent/tools)
- safe_tools: wrappers around LangChain / MistralAI calls.
f. State Persistence (support_agent/state.py + SQLite)
- After each node execution, serialize the graph state to SQLite.
g. External Services
- LangChain / MistralAI endpoints (LLM inference).
- Tracing & telemetry (if LANGCHAIN_TRACING_V2 is enabled).

##### Relationships and data flow
- Client → Flask API (HTTP)
- Flask API → Graph Engine
- Graph Engine → Node Modules
- Node Modules → Tools Layer
- Tools Layer → External LLM APIs → Return response
- After each Node execution → State Persistence → SQLite
- At any point, Graph Engine reads from SQLite to resume

##### Architectural patterns & design principles
- Modular pipeline / directed graph pattern (LangGraph).
- Separation of concerns: API layer, graph orchestration, node logic, external tool integration, persistence.
- Human-in-the-Loop flow: nodes pause for user input.
- Checkpointing: event-sourcing style state persistence.

- Blue for internal services,
- Green for persistence,
- Orange for external dependencies.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client
    Client["Client\n(HTTP)"]:::external

    %% API Layer
    subgraph "API Layer"
        FlaskServer["Flask API Server\n(app.py)"]:::internal
    end

    %% Graph Engine Layer
    subgraph "Graph Engine"
        GraphEngine["Graph Executor\n(support_agent/graph.py)"]:::internal
        Config["Configuration\n(consts.py)"]:::internal
        subgraph "Nodes"
            Verify["verify_information Node\n(support_agent/nodes/verify_information.py)"]:::internal
            Safe["safe_agent Node\n(support_agent/nodes/safe_agent.py)"]:::internal
            Assistant["assistant_node Node\n(support_agent/nodes/assistant_node.py)"]:::internal
        end
        subgraph "Tools Layer"
            SafeTools["safe_tools\n(support_agent/tools/safe_tools.py)"]:::internal
        end
    end

    %% Persistence
    StatePersistence["State Persistence Module\n(support_agent/state.py)"]:::persistence
    SQLiteDB(("SQLite DB\n(db/profile.json & *.sqlite)")):::persistence

    %% External Services
    ExternalLLM["LLM Endpoints\n(LangChain / MistralAI)"]:::external
    Tracing["Tracing & Telemetry"]:::external

    %% Supporting Files
    pyproject["Dependency Config\n(pyproject.toml)"]:::internal
    Static["Static Assets\n(static/)"]:::internal
    Readme["Documentation\n(README.md)"]:::internal

    %% Data Flow
    Client -->|"HTTP JSON"| FlaskServer
    FlaskServer -->|"dispatch"| GraphEngine
    GraphEngine -->|"uses config"| Config
    GraphEngine -->|"execute step"| Verify
    GraphEngine -->|"execute step"| Safe
    GraphEngine -->|"execute step"| Assistant
    Verify -->|"invoke tool"| SafeTools
    Safe -->|"invoke tool"| SafeTools
    Assistant -->|"invoke tool"| SafeTools
    SafeTools -->|"HTTP API"| ExternalLLM
    ExternalLLM -->|"response"| SafeTools
    SafeTools -->|"result"| GraphEngine

    %% Persistence Flow
    Verify -->|"checkpoint"| StatePersistence
    Safe -->|"checkpoint"| StatePersistence
    Assistant -->|"checkpoint"| StatePersistence
    StatePersistence -->|"SQL"| SQLiteDB
    GraphEngine -->|"resume state"| SQLiteDB

    %% Tracing
    FlaskServer -->|"trace events"| Tracing
    SafeTools -->|"trace events"| Tracing

    %% Supporting Links
    FlaskServer --> pyproject
    FlaskServer --> Static
    FlaskServer --> Readme

    %% Click Events
    click FlaskServer "https://github.com/emarco177/langgraph-customer-support/blob/main/app.py"
    click GraphEngine "https://github.com/emarco177/langgraph-customer-support/blob/main/support_agent/graph.py"
    click Config "https://github.com/emarco177/langgraph-customer-support/blob/main/support_agent/consts.py"
    click StatePersistence "https://github.com/emarco177/langgraph-customer-support/blob/main/support_agent/state.py"
    click SQLiteDB "https://github.com/emarco177/langgraph-customer-support/blob/main/db/profile.json"
    click Verify "https://github.com/emarco177/langgraph-customer-support/blob/main/support_agent/nodes/verify_information.py"
    click Safe "https://github.com/emarco177/langgraph-customer-support/blob/main/support_agent/nodes/safe_agent.py"
    click Assistant "https://github.com/emarco177/langgraph-customer-support/blob/main/support_agent/nodes/assistant_node.py"
    click SafeTools "https://github.com/emarco177/langgraph-customer-support/blob/main/support_agent/tools/safe_tools.py"
    click pyproject "https://github.com/emarco177/langgraph-customer-support/blob/main/pyproject.toml"
    click Static "https://github.com/emarco177/langgraph-customer-support/tree/main/static/"
    click Readme "https://github.com/emarco177/langgraph-customer-support/blob/main/README.md"

    %% Styles
    classDef internal fill:#DAE8FC,stroke:#6C8EBF
    classDef persistence fill:#E2F0D9,stroke:#82B366
    classDef external fill:#FFE6CC,stroke:#D79B00
```
