# yonom/assistant-ui-langgraph-fastapi architecture

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

- Interactive diagram: https://gitdiagram.com/yonom/assistant-ui-langgraph-fastapi
- Repository: https://github.com/yonom/assistant-ui-langgraph-fastapi

## Overview

##### Project type and purpose
- This is a full-stack demonstration app combining:
– A LangGraph AI agent running in Python via FastAPI
– Real-time token streaming from backend to frontend using assistant-stream
– A modern chat UI built with Next.js and assistant-ui

##### File structure
Top-level:
- backend/ : FastAPI application, LangGraph agent modules, Dockerfile, pyproject.toml
– app/server.py: main FastAPI server, mounts streaming endpoints
– app/add_langgraph_route.py: registers LangGraph routes
– app/langgraph/: agent.py (agent logic), state.py (conversation state), tools.py (external tool wrappers)
- frontend/ : Next.js + assistant-ui client
– app/page.tsx & components/MyAssistant.tsx: chat UI and integration with assistant-stream
– next.config.ts, tailwind.config.ts, postcss.config.mjs: build and styling configuration

##### Extract additional architectural insights from README
- Backend spun up via “poetry run python -m app.server”
- Frontend launched via “yarn dev”
- .env file in backend for API keys and configuration

a. Main components to include:
1. Frontend UI
– Next.js app
– assistant-ui chat component
2. Streaming Layer
– assistant-stream client (in frontend)
– assistant-stream endpoint (in FastAPI backend)
3. FastAPI Backend
– HTTP/WebSocket server
– LangGraph route registrations
4. LangGraph Agent
– agent.py (core decision logic)
– state.py (conversation memory)
– tools.py (external API/tool connectors)
5. External Tools/APIs
– Any third-party APIs or services invoked by tools.py
6. Infrastructure
– Docker container for backend (optional)
– Environment variables store (.env)

b. Relationships and data flow
1. User types a message in the chat UI
2. Frontend assistant-stream client opens a streaming connection to FastAPI
3. FastAPI receives user input, forwards to the LangGraph Agent
4. Agent processes input, updates state, calls external tools as needed
5. Agent yields tokens/partials back to FastAPI
6. FastAPI pushes tokens over the streaming connection to the frontend
7. Frontend renders tokens in real time in the chat UI

c. Architectural patterns and design principles
- Two-tier, decoupled frontend/backend
- Streaming architecture for real-time updates (event-driven)
- Modular agent design: separate state management, tool integration, decision logic
- Containerization for backend isolation and reproducible deployments

d. Key technologies and frameworks
- Frontend: Next.js, assistant-ui, Tailwind CSS, TypeScript
- Streaming: assistant-stream
- Backend: FastAPI, Python 3.11, LangChain CLI, LangGraph
- Deployment: Docker (backend)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User Interaction
    User["User"]:::external
    User -->|types message| UI

    %% Frontend Layer
    subgraph "Frontend Layer"
        direction TB
        UI["Next.js App"]:::ui
        Page["page.tsx"]:::ui
        Layout["layout.tsx"]:::ui
        Globals["globals.css"]:::ui
        MyAssistant["MyAssistant.tsx"]:::ui
    end

    UI --> Page
    UI --> Layout
    UI --> Globals
    UI --> MyAssistant

    %% Streaming Layer
    subgraph "Streaming Layer"
        direction TB
        Client["assistant-stream Client"]:::streaming
        Endpoint["assistant-stream Endpoint"]:::streaming
    end

    MyAssistant -->|opens WS/HTTP stream| Client
    Client -->|connects| Endpoint

    %% Backend Layer
    subgraph "Backend Layer"
        direction TB
        Server["server.py (FastAPI)"]:::backend
        AddRoute["add_langgraph_route.py"]:::backend
    end

    Endpoint -->|HTTP/WebSocket| Server
    Server --> AddRoute

    %% LangGraph Agent
    subgraph "LangGraph Agent"
        direction TB
        AgentCore["agent.py"]:::agent
        AgentState["state.py"]:::agent
        AgentTools["tools.py"]:::tools
    end

    AddRoute --> AgentCore
    AgentCore --> AgentState
    AgentCore --> AgentTools

    %% External Tools/APIs
    External["External Tools/APIs"]:::external
    AgentTools -->|invokes| External

    %% Infrastructure
    subgraph "Infrastructure & Config"
        direction TB
        PyProject["pyproject.toml"]:::infra
        Dockerfile["Dockerfile"]:::infra
        Gitignore[".gitignore"]:::infra
        NextConfig["next.config.ts"]:::infra
        TailwindConfig["tailwind.config.ts"]:::infra
        PostcssConfig["postcss.config.mjs"]:::infra
        Tsconfig["tsconfig.json"]:::infra
    end

    Server --> PyProject
    Server --> Dockerfile
    Server --> Gitignore
    UI --> NextConfig
    UI --> TailwindConfig
    UI --> PostcssConfig
    UI --> Tsconfig

    %% Response Flow
    AgentCore -->|yields tokens| Server
    Server -->|stream tokens| Endpoint
    Endpoint -->|stream tokens| Client
    Client -->|renders tokens| MyAssistant

    %% Click Events
    click Page "https://github.com/yonom/assistant-ui-langgraph-fastapi/blob/main/frontend/app/page.tsx"
    click Layout "https://github.com/yonom/assistant-ui-langgraph-fastapi/blob/main/frontend/app/layout.tsx"
    click Globals "https://github.com/yonom/assistant-ui-langgraph-fastapi/blob/main/frontend/app/globals.css"
    click MyAssistant "https://github.com/yonom/assistant-ui-langgraph-fastapi/blob/main/frontend/components/MyAssistant.tsx"
    click Server "https://github.com/yonom/assistant-ui-langgraph-fastapi/blob/main/backend/app/server.py"
    click AddRoute "https://github.com/yonom/assistant-ui-langgraph-fastapi/blob/main/backend/app/add_langgraph_route.py"
    click AgentCore "https://github.com/yonom/assistant-ui-langgraph-fastapi/blob/main/backend/app/langgraph/agent.py"
    click AgentState "https://github.com/yonom/assistant-ui-langgraph-fastapi/blob/main/backend/app/langgraph/state.py"
    click AgentTools "https://github.com/yonom/assistant-ui-langgraph-fastapi/blob/main/backend/app/langgraph/tools.py"
    click PyProject "https://github.com/yonom/assistant-ui-langgraph-fastapi/blob/main/backend/pyproject.toml"
    click Dockerfile "https://github.com/yonom/assistant-ui-langgraph-fastapi/tree/main/backend/Dockerfile"
    click Gitignore "https://github.com/yonom/assistant-ui-langgraph-fastapi/blob/main/backend/.gitignore"
    click NextConfig "https://github.com/yonom/assistant-ui-langgraph-fastapi/blob/main/frontend/next.config.ts"
    click TailwindConfig "https://github.com/yonom/assistant-ui-langgraph-fastapi/blob/main/frontend/tailwind.config.ts"
    click PostcssConfig "https://github.com/yonom/assistant-ui-langgraph-fastapi/blob/main/frontend/postcss.config.mjs"
    click Tsconfig "https://github.com/yonom/assistant-ui-langgraph-fastapi/blob/main/frontend/tsconfig.json"

    %% Styles
    classDef ui fill:#E0F7FA,stroke:#006064,color:#004D40
    classDef streaming fill:#FFF3E0,stroke:#E65100,color:#BF360C
    classDef backend fill:#E8EAF6,stroke:#1A237E,color:#0D47A1
    classDef agent fill:#F3E5F5,stroke:#4A148C,color:#6A1B9A
    classDef tools fill:#E1F5FE,stroke:#01579B,color:#0277BD
    classDef infra fill:#F1F8E9,stroke:#33691E,color:#558B2F
    classDef external fill:#FFEBEE,stroke:#C62828,color:#B71C1C
```
