# ruc-gsai/yulan-rec architecture

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

- Interactive diagram: https://gitdiagram.com/ruc-gsai/yulan-rec
- Repository: https://github.com/ruc-gsai/yulan-rec

## Overview

##### Project Type & Purpose
- Full-stack, Python-backed multi-agent user behavior simulation platform with a React/TypeScript front end.

##### Key Architectural Layers & Components
A. Frontend (UI folder)
– React single-page application (TypeScript, Vite)
– Components: AgentCard, ChatCard, Graph, SettingsForm, etc.
– State management via React Context (DisplayedAgentContext, UiSettingsContext)
– API hooks under src/hooks/api (agent, relationship, state) for communicating with the backend.
B. API Server / Backend Entry Point
– backend.py (likely FastAPI or Flask) exposes HTTP endpoints consumed by the UI.
– test.js (root) demonstrates raw API calls.
– shell scripts (backend.sh, nohup.sh) to start the server.
C. Simulation Engine
– simulator.py / run_demo.py / demo.py orchestrate simulation rounds.
– Uses config/config.yaml for parameters (LLM choice, data paths, agent count, scheduling).
– Agents directory: recagent.py, recagent_memory.py, roleagent.py implement agent behavior and memory.
– llm directory: custom_llm.py, local_llm.py wrap OpenAI or local LLM API calls.
– recommender directory:
- data/data.py reads item/user/relationship CSVs
- model/* implements MF, random, base interfaces
- recommender.py trains/invokes the recommendation model each round.
– utils: helper modules for event scheduling, messaging, persisting checkpoints.
D. Data Layer
– CSV files under data/ (user.csv, item.csv, relationship.csv)
– FAISS index under data/faiss_index for fast item lookup
– JSON output (messages.json) and logs for simulation records
– config/config.yaml for runtime settings
E. External Services
– OpenAI API (or other LLM endpoints)
– (Optionally) local LLM service
F. Deployment & Orchestration
– Shell scripts: simulator.sh to run simulation headless
– Nohup.sh for background execution
– Docker (not provided, but could be added)

##### Relationships & Data Flows
– Frontend ←→ Backend/API: all user interactions (start/pause/reset, settings) go via REST calls.
– Backend Simulation Engine invokes:
- Agent modules → consult Memory module → request next action
- Recommender module → returns item recommendations
- LLM module → calls out to OpenAI or local LLM, returns generated text
– Simulation Engine writes events to Data Layer (CSV / FAISS / JSON logs).
– Frontend polls or opens a WebSocket (if implemented) to receive real-time updates on agent state, logs, graphs.

##### Architectural Patterns & Design Principles
– Layered Architecture:
- Presentation (React UI)
- API / Controller (backend.py)
- Simulation Services (Simulator, Agents, Recommender, LLM, Utils)
- Data Access (CSV readers, FAISS index)
- External Integration (OpenAI)
– Separation of Concerns: each folder/package has clear responsibility.
– Plugin-style Recommender & LLM: easy to extend with new algorithms or LLM providers.
– Config-driven: almost every behavior (agent count, memory type, model choice) comes from YAML.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Frontend (UI)"
        direction TB
        AgentCard["AgentCard"]:::frontend
        ChatCard["ChatCard"]:::frontend
        Graph["Graph"]:::frontend
        SettingsForm["SettingsForm"]:::frontend
        DisplayedCtx["DisplayedAgentContext"]:::frontend
        UiSettingsCtx["UiSettingsContext"]:::frontend
        agentAPI["agent.ts"]:::frontend
        relAPI["relationship.ts"]:::frontend
        stateAPI["state.ts"]:::frontend
    end

    subgraph "Backend API / Controller"
        direction TB
        Backend["backend.py"]:::controller
        TestJS["test.js"]:::controller
        ShellBackend["backend.sh"]:::controller
        ShellNoHup["nohup.sh"]:::controller
    end

    subgraph "Simulation Engine"
        direction TB
        SimMain["simulator.py"]:::core
        RunDemo["run_demo.py"]:::core
        Demo["demo.py"]:::core
        ShellSim["simulator.sh"]:::core

        subgraph "Agent Module"
            direction TB
            RecAgent["recagent.py"]:::core
            RecMem["recagent_memory.py"]:::core
            RoleAgent["roleagent.py"]:::core
        end

        subgraph "LLM Module"
            direction TB
            CustomLLM["custom_llm.py"]:::core
            LocalLLM["local_llm.py"]:::core
        end

        subgraph "Recommender Module"
            direction TB
            DataPy["data.py"]:::core
            BaseModel["base.py"]:::core
            MFModel["mf.py"]:::core
            RandModel["random.py"]:::core
            RecMod["recommender.py"]:::core
        end

        subgraph "Utilities"
            direction TB
            Conn["connect.py"]:::core
            Event["event.py"]:::core
            Interval["interval.py"]:::core
            Msg["message.py"]:::core
            Utils["utils.py"]:::core
        end
    end

    subgraph "Data Layer"
        direction TB
        CSVUser["user.csv"]:::data
        CSVItem["item.csv"]:::data
        CSVRel["relationship.csv"]:::data
        CSVInter["interaction.csv"]:::data
        FAISSIdx["index.faiss"]:::data
        FAISSPkl["index.pkl"]:::data
        ConfigYAML["config.yaml"]:::data
    end

    External["OpenAI API"]:::external

    %% Connections
    AgentCard -->|use API| Backend
    ChatCard -->|use API| Backend
    Graph -->|use API| Backend
    SettingsForm -->|use API| Backend
    Backend -->|invoke| SimMain
    TestJS -->|invoke| Backend
    ShellBackend -->|starts| Backend
    ShellNoHup -->|starts| Backend
    ShellSim -->|runs| SimMain
    SimMain -->|orchestrates| RecAgent
    SimMain -->|orchestrates| RecMod
    SimMain -->|uses| Conn
    SimMain -->|uses| Event
    SimMain -->|uses| Interval
    SimMain -->|uses| Msg
    SimMain -->|uses| Utils
    RecAgent -->|updates| RecMem
    RecAgent -->|requests| CustomLLM
    RecAgent -->|requests| LocalLLM
    RecMod -->|reads| DataPy
    RecMod -->|loads| BaseModel
    RecMod -->|loads| MFModel
    RecMod -->|loads| RandModel
    RecMod -->|writes| FAISSIdx
    RecMod -->|writes| FAISSPkl
    SimMain -->|writes logs| CSVInter
    SimMain -->|writes config| ConfigYAML
    SimMain -->|writes users| CSVUser
    SimMain -->|writes items| CSVItem
    SimMain -->|writes relationships| CSVRel
    External -->|responds| CustomLLM
    External -->|responds| LocalLLM
    SimMain -->|logs| CSVInter
    CSVInter -->|visualized| Graph

    %% UI data flow
    Graph -->|polls data| Backend

    %% Click Events
    click AgentCard "https://github.com/ruc-gsai/yulan-rec/blob/main/ui/src/components/AgentCard.tsx"
    click ChatCard "https://github.com/ruc-gsai/yulan-rec/blob/main/ui/src/components/ChatCard.tsx"
    click Graph "https://github.com/ruc-gsai/yulan-rec/blob/main/ui/src/components/Graph.tsx"
    click SettingsForm "https://github.com/ruc-gsai/yulan-rec/blob/main/ui/src/components/SettingsForm.tsx"
    click DisplayedCtx "https://github.com/ruc-gsai/yulan-rec/blob/main/ui/src/context/DisplayedAgentContext.ts"
    click UiSettingsCtx "https://github.com/ruc-gsai/yulan-rec/blob/main/ui/src/context/UiSettingsContext.ts"
    click agentAPI "https://github.com/ruc-gsai/yulan-rec/blob/main/ui/src/hooks/api/agent.ts"
    click relAPI "https://github.com/ruc-gsai/yulan-rec/blob/main/ui/src/hooks/api/relationship.ts"
    click stateAPI "https://github.com/ruc-gsai/yulan-rec/blob/main/ui/src/hooks/api/state.ts"
    click Backend "https://github.com/ruc-gsai/yulan-rec/blob/main/backend.py"
    click TestJS "https://github.com/ruc-gsai/yulan-rec/blob/main/test.js"
    click ShellBackend "https://github.com/ruc-gsai/yulan-rec/blob/main/backend.sh"
    click ShellNoHup "https://github.com/ruc-gsai/yulan-rec/blob/main/nohup.sh"
    click SimMain "https://github.com/ruc-gsai/yulan-rec/blob/main/simulator.py"
    click RunDemo "https://github.com/ruc-gsai/yulan-rec/blob/main/run_demo.py"
    click Demo "https://github.com/ruc-gsai/yulan-rec/blob/main/demo.py"
    click ShellSim "https://github.com/ruc-gsai/yulan-rec/blob/main/simulator.sh"
    click RecAgent "https://github.com/ruc-gsai/yulan-rec/blob/main/agents/recagent.py"
    click RecMem "https://github.com/ruc-gsai/yulan-rec/blob/main/agents/recagent_memory.py"
    click RoleAgent "https://github.com/ruc-gsai/yulan-rec/blob/main/agents/roleagent.py"
    click CustomLLM "https://github.com/ruc-gsai/yulan-rec/blob/main/llm/custom_llm.py"
    click LocalLLM "https://github.com/ruc-gsai/yulan-rec/blob/main/llm/local_llm.py"
    click DataPy "https://github.com/ruc-gsai/yulan-rec/blob/main/recommender/data/data.py"
    click BaseModel "https://github.com/ruc-gsai/yulan-rec/blob/main/recommender/model/base.py"
    click MFModel "https://github.com/ruc-gsai/yulan-rec/blob/main/recommender/model/mf.py"
    click RandModel "https://github.com/ruc-gsai/yulan-rec/blob/main/recommender/model/random.py"
    click RecMod "https://github.com/ruc-gsai/yulan-rec/blob/main/recommender/recommender.py"
    click Conn "https://github.com/ruc-gsai/yulan-rec/blob/main/utils/connect.py"
    click Event "https://github.com/ruc-gsai/yulan-rec/blob/main/utils/event.py"
    click Interval "https://github.com/ruc-gsai/yulan-rec/blob/main/utils/interval.py"
    click Msg "https://github.com/ruc-gsai/yulan-rec/blob/main/utils/message.py"
    click Utils "https://github.com/ruc-gsai/yulan-rec/blob/main/utils/utils.py"
    click CSVUser "https://github.com/ruc-gsai/yulan-rec/blob/main/data/user.csv"
    click CSVItem "https://github.com/ruc-gsai/yulan-rec/blob/main/data/item.csv"
    click CSVRel "https://github.com/ruc-gsai/yulan-rec/blob/main/data/relationship.csv"
    click CSVInter "https://github.com/ruc-gsai/yulan-rec/blob/main/data/interaction.csv"
    click FAISSIdx "https://github.com/ruc-gsai/yulan-rec/blob/main/data/faiss_index/index.faiss"
    click FAISSPkl "https://github.com/ruc-gsai/yulan-rec/blob/main/data/faiss_index/index.pkl"
    click ConfigYAML "https://github.com/ruc-gsai/yulan-rec/blob/main/config/config.yaml"

    %% Styles
    classDef frontend fill:#CCF,stroke:#333,stroke-width:1px
    classDef controller fill:#CFC,stroke:#333,stroke-width:1px
    classDef core fill:#FFC,stroke:#333,stroke-width:1px
    classDef data fill:#DDD,stroke:#333,stroke-width:1px
    classDef external fill:#FDD,stroke:#333,stroke-width:1px
```
