# truewangsyutung/ufgraphfr architecture

> Architecture diagram of the GitHub repository truewangsyutung/ufgraphfr, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/truewangsyutung/ufgraphfr
- Repository: https://github.com/truewangsyutung/ufgraphfr

## Overview

UFGraphFR is a federated recommendation research system. Its principal workflow is to load interaction and user-profile data, encode profile text, train client recommendation models across rounds, aggregate client parameters into a server-side user-relation graph, and evaluate ranked recommendations. The graph preserves the documented transformer and optional noise capabilities. Source excerpts show the data, embedding, model, and graph-building pieces, but do not expose the full round orchestration; uncertain links are omitted rather than inferred.

Main entry points: [`train.py`](https://github.com/truewangsyutung/ufgraphfr/blob/main/train.py) (Training Orchestrator), [`engine.py`](https://github.com/truewangsyutung/ufgraphfr/blob/main/engine.py) (Federated Engine), [`mymodel.py`](https://github.com/truewangsyutung/ufgraphfr/blob/main/mymodel.py) (UFGraphFR Client Model), [`metrics.py`](https://github.com/truewangsyutung/ufgraphfr/blob/main/metrics.py) (Ranking Metrics)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Data and Features"]
  node_datasets[("Benchmark Data")]
  node_ingest["Data Preparation<br/>[train.py]"]
  node_sampling["Interaction Sampling<br/>[data.py]"]
  node_text["Profile Text Encoding<br/>[embedding.py]"]
end

subgraph group_learning["Federated Learning"]
  node_trainer["Training Orchestrator<br/>[train.py]"]
  node_federation["Federated Engine<br/>[engine.py]"]
  node_graph["User Graph Utilities<br/>[utils.py]"]
  node_privacy["Optional Noise<br/>[engine.py]"]
end

subgraph group_recommend["Recommendation Models"]
  node_ufmodel["UFGraphFR Client Model<br/>[mymodel.py]"]
  node_transformer["Sequence Transformer<br/>[mymodel.py]"]
  node_baseline["MLP Baseline<br/>[mlp.py]"]
end

subgraph group_evaluation["Evaluation"]
  node_metrics["Ranking Metrics<br/>[metrics.py]"]
  node_results["Evaluation Results<br/>[train.py]"]
end

node_operator(("Experiment Runner"))

node_operator -->|"runs"| node_trainer
node_trainer -->|"loads"| node_datasets
node_trainer -->|"prepares"| node_ingest
node_ingest -->|"uses"| node_sampling
node_trainer -->|"configures"| node_text
node_trainer -->|"selects engine"| node_federation
node_federation -->|"trains client"| node_ufmodel
node_federation -.->|"trains baseline"| node_baseline
node_federation -->|"constructs relation graph"| node_graph
node_federation -.->|"may add noise"| node_privacy
node_ufmodel -->|"uses attention"| node_transformer
node_federation -->|"initializes metrics"| node_metrics
node_trainer -->|"writes results"| node_results
node_trainer -.->|"evaluates"| node_metrics

click node_datasets "https://github.com/truewangsyutung/ufgraphfr/tree/main/data"
click node_ingest "https://github.com/truewangsyutung/ufgraphfr/blob/main/train.py"
click node_sampling "https://github.com/truewangsyutung/ufgraphfr/blob/main/data.py"
click node_text "https://github.com/truewangsyutung/ufgraphfr/blob/main/embedding.py"
click node_trainer "https://github.com/truewangsyutung/ufgraphfr/blob/main/train.py"
click node_federation "https://github.com/truewangsyutung/ufgraphfr/blob/main/engine.py"
click node_graph "https://github.com/truewangsyutung/ufgraphfr/blob/main/utils.py"
click node_privacy "https://github.com/truewangsyutung/ufgraphfr/blob/main/engine.py"
click node_ufmodel "https://github.com/truewangsyutung/ufgraphfr/blob/main/mymodel.py"
click node_transformer "https://github.com/truewangsyutung/ufgraphfr/blob/main/mymodel.py"
click node_baseline "https://github.com/truewangsyutung/ufgraphfr/blob/main/mlp.py"
click node_metrics "https://github.com/truewangsyutung/ufgraphfr/blob/main/metrics.py"
click node_results "https://github.com/truewangsyutung/ufgraphfr/blob/main/train.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_datasets,node_ingest,node_sampling,node_text toneBlue
class node_trainer,node_federation,node_graph,node_privacy toneAmber
class node_ufmodel,node_transformer,node_baseline toneMint
class node_metrics,node_results toneRose
class node_operator toneIndigo
```

## Components

### Data and Features

- [Benchmark Data](https://github.com/truewangsyutung/ufgraphfr/tree/main/data): `data`
- [Data Preparation](https://github.com/truewangsyutung/ufgraphfr/blob/main/train.py): `train.py`
- [Interaction Sampling](https://github.com/truewangsyutung/ufgraphfr/blob/main/data.py): `data.py`
- [Profile Text Encoding](https://github.com/truewangsyutung/ufgraphfr/blob/main/embedding.py): `embedding.py`

### Federated Learning

- [Training Orchestrator](https://github.com/truewangsyutung/ufgraphfr/blob/main/train.py): `train.py`
- [Federated Engine](https://github.com/truewangsyutung/ufgraphfr/blob/main/engine.py): `engine.py`
- [User Graph Utilities](https://github.com/truewangsyutung/ufgraphfr/blob/main/utils.py): `utils.py`
- [Optional Noise](https://github.com/truewangsyutung/ufgraphfr/blob/main/engine.py): `engine.py`

### Recommendation Models

- [UFGraphFR Client Model](https://github.com/truewangsyutung/ufgraphfr/blob/main/mymodel.py): `mymodel.py`
- [Sequence Transformer](https://github.com/truewangsyutung/ufgraphfr/blob/main/mymodel.py): `mymodel.py`
- [MLP Baseline](https://github.com/truewangsyutung/ufgraphfr/blob/main/mlp.py): `mlp.py`

### Evaluation

- [Ranking Metrics](https://github.com/truewangsyutung/ufgraphfr/blob/main/metrics.py): `metrics.py`
- [Evaluation Results](https://github.com/truewangsyutung/ufgraphfr/blob/main/train.py): `train.py`

### Other components

- **Experiment Runner**

## Connections

- Experiment Runner → Training Orchestrator: runs (evidence: `README.md`)
- Training Orchestrator → Benchmark Data: loads (evidence: `train.py`)
- Training Orchestrator → Data Preparation: prepares (evidence: `train.py`)
- Data Preparation → Interaction Sampling: uses (evidence: `train.py`)
- Training Orchestrator → Profile Text Encoding: configures (evidence: `train.py`)
- Training Orchestrator → Federated Engine: selects engine (evidence: `train.py`)
- Federated Engine → UFGraphFR Client Model: trains client (evidence: `engine.py`)
- Federated Engine → MLP Baseline: trains baseline (evidence: `mlp.py`)
- Federated Engine → User Graph Utilities: constructs relation graph (evidence: `engine.py`)
- Federated Engine → Optional Noise: may add noise (evidence: `README.md`)
- UFGraphFR Client Model → Sequence Transformer: uses attention (evidence: `mymodel.py`)
- Federated Engine → Ranking Metrics: initializes metrics (evidence: `engine.py`)
- Training Orchestrator → Evaluation Results: writes results (evidence: `train.py`)
- Training Orchestrator → Ranking Metrics: evaluates
