# chiang-yuan/llamp architecture

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

- Interactive diagram: https://gitdiagram.com/chiang-yuan/llamp
- Repository: https://github.com/chiang-yuan/llamp

## Overview

##### Project Type and Purpose
- **Type**: Full-stack retrieval-augmented generation (RAG) framework.
- **Purpose**: Expose a Python-based LLaMP core (hierarchical ReAct agents grounded on Materials Project, ArXiv, ASE, Atomate2) via a web UI, so users can chat with a materials-aware large language model over HTTP/SSE.

##### High-Level Components
a. **Browser / Frontend (Web container)**
- Tech: Svelte, Skeleton CSS, Tailwind, Vite.
- Responsibilities: Render chat UI, manage user settings, open Server-Sent Events (SSE) to stream token-by-token responses.

b. **API / Backend (API container)**
- Tech: Python, FastAPI (implied), LangChain, Redis (for streaming), Uvicorn/Gunicorn.
- Responsibilities:
- HTTP endpoints for chat and agent triggers
- SSE endpoint powering incremental tokens
- Agent orchestrator modules under `api/src/llamp/…`
- Call external LLM services (OpenAI, etc.)
- Call Materials Project REST API, ArXiv, ASE, Atomate2

c. **External Services & Data Stores**
- **LLM Provider** (OpenAI / HuggingFace)
- **Materials Project API**
- **ArXiv API**
- **ASE / Atomate2** (local simulation libraries, optional)
- **Redis** (or in-memory pub/sub for SSE callbacks)
- *(Optional)* Docker registry, GitHub Actions for CI

##### Relationships and Data Flow
1. **User** in browser sends a chat request via HTTP POST → **Frontend**
2. **Frontend** forwards JSON to **Backend API**
3. **Backend API** spins up a Hierarchical ReAct agent:
- May fetch schema/tools from `mp_openapi.json`, ASE utilities, Atomate2
- Issues sub-requests to **Materials Project**, **ArXiv**, or runs **ASE/Atomate2** code
- Sends prompts to **OpenAI** (or other LLM)
- Streams tokens back via **Redis** callbacks → SSE
4. **Frontend** listens to SSE, renders streaming responses token-by-token
5. End of conversation cycle
6. *(Optional)* Logging / metrics stored or forwarded to CI / monitoring

##### Architectural Patterns & Principles
- **Containerized micro-services**: Separate Web and API containers managed by `docker-compose.yml`
- **Modular plugin-style agents**: Each domain (mp, arxiv, ase, atomate2) is a plugin under `llamp/…`
- **ReAct pattern**: Agents “Reason+Act” recursively
- **Retrieval-Augmented Generation (RAG)**: Grounding LLM with high-fidelity data
- **Server-Sent Events (SSE)** for low-latency streaming
- **Docker-first local dev** with `.env`, `.env.example`, `Dockerfile.dev`, GitHub Actions

##### Detailed Capture of Essential Elements
- **Docker-compose orchestration**
- At the bottom, show `docker-compose.yml` linking Web ↔ API
- **CI/CD**
- **Experiments & Lab**
- (Optional) Side note: “Jupyter Notebooks” folder that directly imports `llamp` Python library — not part of production

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Frontend Layer
    subgraph "Web UI (Svelte + Tailwind)" 
        direction TB
        UI["Browser / Frontend"]:::frontend
        MsgComp["Message.svelte"]:::frontend
        SideComp["SideBar.svelte"]:::frontend
        PageComp["+page.svelte"]:::frontend
        ChatUtil["chatUtils.ts"]:::frontend
        Store["store.ts"]:::frontend
    end

    %% Backend Layer
    subgraph "API: Python/FastAPI/LangChain" 
        direction TB
        APIServer["LLaMP API"]:::backend
        subgraph "Agents & Handlers"
            direction TB
            Orchestrator["Agent Orchestrator"]:::backend
            MPAgent["MP Agent"]:::backend
            ArxivAgent["ArXiv Agent"]:::backend
            ASEAgent["ASE Agent"]:::backend
            AtomateAgent["Atomate2 Agent"]:::backend
            SSEHandler["SSE Callback Handler"]:::backend
        end
    end

    %% External Services & Data Stores
    subgraph "External Services" 
        direction TB
        OpenAI["OpenAI / HuggingFace"]:::external
        MPAPI["Materials Project API"]:::external
        ArxivAPI["ArXiv API"]:::external
        ASELib["ASE / Atomate2"]:::external
    end

    Redis["Redis Pub/Sub"]:::datastore
    DockerComp["docker-compose.yml"]:::infra
    CI["GitHub Actions CI"]:::ci

    %% Connections
    UI -->|"REST POST"| APIServer
    UI -.->|"SSE Stream"| SSEHandler
    APIServer --> Orchestrator
    Orchestrator --> MPAgent
    Orchestrator --> ArxivAgent
    Orchestrator --> ASEAgent
    Orchestrator --> AtomateAgent
    MPAgent -->|"API Call"| MPAPI
    ArxivAgent -->|"API Call"| ArxivAPI
    ASEAgent -->|"Library Call"| ASELib
    AtomateAgent -->|"Library Call"| ASELib
    SSEHandler -->|"Pub/Sub"| Redis
    Orchestrator -->|"LLM Prompt"| OpenAI
    DockerComp --> UI
    DockerComp --> APIServer
    CI --> APIServer

    %% Click Events
    click MsgComp "https://github.com/chiang-yuan/llamp/blob/main/web/src/lib/components/Message.svelte"
    click SideComp "https://github.com/chiang-yuan/llamp/blob/main/web/src/lib/components/SideBar.svelte"
    click PageComp "https://github.com/chiang-yuan/llamp/blob/main/web/src/routes/+page.svelte"
    click ChatUtil "https://github.com/chiang-yuan/llamp/blob/main/web/src/lib/chatUtils.ts"
    click Store "https://github.com/chiang-yuan/llamp/blob/main/web/src/lib/store.ts"
    click APIServer "https://github.com/chiang-yuan/llamp/tree/main/api/"
    click SSEHandler "https://github.com/chiang-yuan/llamp/blob/main/api/src/llamp/sse.py"
    click MPAgent "https://github.com/chiang-yuan/llamp/blob/main/api/src/llamp/mp/agents.py"
    click ArxivAgent "https://github.com/chiang-yuan/llamp/blob/main/api/src/llamp/arxiv/agents.py"
    click ASEAgent "https://github.com/chiang-yuan/llamp/blob/main/api/src/llamp/ase/tools.py"
    click ASEAgent "https://github.com/chiang-yuan/llamp/blob/main/api/src/llamp/ase/schemas.py"
    click ASEAgent "https://github.com/chiang-yuan/llamp/blob/main/api/src/llamp/ase/utils.py"
    click AtomateAgent "https://github.com/chiang-yuan/llamp/blob/main/api/src/llamp/atomate2/agents.py"
    click AtomateAgent "https://github.com/chiang-yuan/llamp/blob/main/api/src/llamp/atomate2/schemas.py"
    click AtomateAgent "https://github.com/chiang-yuan/llamp/blob/main/api/src/llamp/atomate2/tools.py"
    click MPAgent "https://github.com/chiang-yuan/llamp/blob/main/api/src/llamp/mp/mp_openapi.json"
    click MPAgent "https://github.com/chiang-yuan/llamp/blob/main/api/src/llamp/mp/mp_openapi_selected.json"
    click MPAgent "https://github.com/chiang-yuan/llamp/blob/main/api/src/llamp/mp/material_functions.json"
    click MPAgent "https://github.com/chiang-yuan/llamp/blob/main/api/src/llamp/mp/schemas.py"
    click MPAgent "https://github.com/chiang-yuan/llamp/blob/main/api/src/llamp/mp/tools.py"
    click Orchestrator "https://github.com/chiang-yuan/llamp/blob/main/api/src/llamp/__init__.py"
    click APIServer "https://github.com/chiang-yuan/llamp/blob/main/api/pyproject.toml"
    click APIServer "https://github.com/chiang-yuan/llamp/tree/main/api/Dockerfile"
    click APIServer "https://github.com/chiang-yuan/llamp/blob/main/api/Dockerfile.dev"
    click DockerComp "https://github.com/chiang-yuan/llamp/blob/main/docker-compose.yml"
    click DockerComp "https://github.com/chiang-yuan/llamp/blob/main/dc-prod.yml"
    click CI "https://github.com/chiang-yuan/llamp/blob/main/api/.github/workflows/test.yml"

    %% Styles
    classDef frontend fill:#E0F7FA,stroke:#006064,color:#006064;
    classDef backend fill:#E8F5E9,stroke:#1B5E20,color:#1B5E20;
    classDef external fill:#ECEFF1,stroke:#607D8B,color:#37474F;
    classDef datastore fill:#FFF3E0,stroke:#E65100,color:#E65100;
    classDef infra fill:#F3E5F5,stroke:#6A1B9A,color:#4A148C;
    classDef ci fill:#FFEBEE,stroke:#B71C1C,color:#B71C1C;
```
