# mainak9093/privacy-preserving-recommendation architecture

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

- Interactive diagram: https://gitdiagram.com/mainak9093/privacy-preserving-recommendation
- Repository: https://github.com/mainak9093/privacy-preserving-recommendation

## Overview

OblivRec combines private matrix-factorization training with private recommendation delivery. Training factors ratings under replicated 2-of-3 sharing; at serving time, a user reconstructs scores and selects items locally, then fetches each record with DPF-PIR. The graph also shows the cleartext modeling/evaluation path, PIR-query harvesting, and the MPC and FSS building blocks. Some subsystem links are based on README descriptions or the SOURCE INDEX; unsampled implementation details are not inferred.

Main entry points: [`src/apps/demo.cpp`](https://github.com/mainak9093/privacy-preserving-recommendation/blob/main/src/apps/demo.cpp) (Recommendation demo), [`src/pir/pir.cpp`](https://github.com/mainak9093/privacy-preserving-recommendation/blob/main/src/pir/pir.cpp) (DPF-PIR), [`src/mf/factor.cpp`](https://github.com/mainak9093/privacy-preserving-recommendation/blob/main/src/mf/factor.cpp) (Private factorization), [`src/mpc/mpc.cpp`](https://github.com/mainak9093/privacy-preserving-recommendation/blob/main/src/mpc/mpc.cpp) (Replicated MPC)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workflow["Product workflow"]
  node_train_app["Training runner<br/>[train.cpp]"]
  node_demo["Recommendation demo<br/>[demo.cpp]"]
  node_server["Serving server<br/>[server.cpp]"]
  node_serve["Shared-score serving<br/>[serve.cpp]"]
end

subgraph group_training["Private training"]
  node_factor["Private factorization<br/>[factor.cpp]"]
  node_clear_mf["Cleartext factorization<br/>[mf.py]"]
end

subgraph group_delivery["Private delivery"]
  node_pir["DPF-PIR<br/>[pir.cpp]"]
  node_dpf["DPF keys<br/>[dpf.cpp]"]
  node_catalogue[("Fixed-width catalogue<br/>[catalogue.cpp]")]
  node_harvest["Query harvesting<br/>[harvest.cpp]"]
  node_channel["TCP framing<br/>[tcp.cpp]"]
end

subgraph group_crypto["Cryptographic substrate"]
  node_mpc["Replicated MPC<br/>[mpc.cpp]"]
  node_mvp["Shared matrix-vector<br/>[mvp.cpp]"]
  node_nonlinear["Truncation and normalization<br/>[nonlinear.hpp]"]
  node_msnzb["FSS comparison gate<br/>[msnzb.cpp]"]
  node_shares["Replicated shares<br/>[share.hpp]"]
  node_prg["Pseudorandom generator<br/>[aes.cpp]"]
  node_csprng["System randomness<br/>[csprng.cpp]"]
end

subgraph group_modeling["Modeling and analysis"]
  node_data["Ratings data<br/>[data.py]"]
  node_metrics["Recommendation metrics<br/>[metrics.py]"]
  node_attack["Fetch-observer attack<br/>[attack.py]"]
  node_dp_study["Privacy study<br/>[dp_study.py]"]
  node_poison_study["Poisoning study<br/>[poison_study.py]"]
end

node_user(("User"))

node_user -->|"requests recommendations"| node_demo
node_train_app -->|"runs private training"| node_factor
node_factor -->|"computes shared products"| node_mpc
node_factor -->|"uses nonlinear protocols"| node_nonlinear
node_factor -->|"uses matrix-vector work"| node_mvp
node_mpc -->|"exchanges replicated shares"| node_shares
node_nonlinear -->|"uses MPC operations"| node_mpc
node_nonlinear -->|"uses comparison gate"| node_msnzb
node_demo -->|"scores shared embedding"| node_serve
node_demo -->|"fetches selected records"| node_pir
node_demo -->|"sends network frames"| node_channel
node_server -->|"answers PIR keys"| node_pir
node_server -->|"loads catalogue"| node_catalogue
node_pir -->|"evaluates query keys"| node_dpf
node_pir -->|"reads records"| node_catalogue
node_dpf -->|"expands pseudorandom tree"| node_prg
node_dpf -->|"generates key material"| node_csprng
node_harvest -->|"uses PIR queries"| node_pir
node_harvest -->|"shares harvested data"| node_mpc
node_clear_mf -->|"loads rating splits"| node_data
node_clear_mf -->|"evaluates predictions"| node_metrics
node_attack -->|"uses dataset"| node_data
node_attack -->|"fits baseline factors"| node_clear_mf
node_dp_study -->|"uses attack analysis"| node_attack
node_dp_study -->|"measures quality"| node_metrics
node_poison_study -->|"uses dataset"| node_data
node_poison_study -->|"measures quality"| node_metrics
node_train_app -.->|"provides trained model"| node_demo

click node_train_app "https://github.com/mainak9093/privacy-preserving-recommendation/blob/main/src/apps/train.cpp"
click node_demo "https://github.com/mainak9093/privacy-preserving-recommendation/blob/main/src/apps/demo.cpp"
click node_server "https://github.com/mainak9093/privacy-preserving-recommendation/blob/main/src/apps/server.cpp"
click node_serve "https://github.com/mainak9093/privacy-preserving-recommendation/blob/main/src/serve/serve.cpp"
click node_factor "https://github.com/mainak9093/privacy-preserving-recommendation/blob/main/src/mf/factor.cpp"
click node_clear_mf "https://github.com/mainak9093/privacy-preserving-recommendation/blob/main/model/mf.py"
click node_mpc "https://github.com/mainak9093/privacy-preserving-recommendation/blob/main/src/mpc/mpc.cpp"
click node_mvp "https://github.com/mainak9093/privacy-preserving-recommendation/blob/main/src/mpc/mvp.cpp"
click node_nonlinear "https://github.com/mainak9093/privacy-preserving-recommendation/blob/main/include/oblivrec/nonlinear.hpp"
click node_msnzb "https://github.com/mainak9093/privacy-preserving-recommendation/blob/main/src/mpc/nonlinear/msnzb.cpp"
click node_shares "https://github.com/mainak9093/privacy-preserving-recommendation/blob/main/include/oblivrec/share.hpp"
click node_pir "https://github.com/mainak9093/privacy-preserving-recommendation/blob/main/src/pir/pir.cpp"
click node_dpf "https://github.com/mainak9093/privacy-preserving-recommendation/blob/main/src/dpf/dpf.cpp"
click node_catalogue "https://github.com/mainak9093/privacy-preserving-recommendation/blob/main/src/pir/catalogue.cpp"
click node_harvest "https://github.com/mainak9093/privacy-preserving-recommendation/blob/main/src/pir/harvest.cpp"
click node_channel "https://github.com/mainak9093/privacy-preserving-recommendation/blob/main/src/net/tcp.cpp"
click node_prg "https://github.com/mainak9093/privacy-preserving-recommendation/blob/main/src/common/aes.cpp"
click node_csprng "https://github.com/mainak9093/privacy-preserving-recommendation/blob/main/src/common/csprng.cpp"
click node_data "https://github.com/mainak9093/privacy-preserving-recommendation/blob/main/model/data.py"
click node_metrics "https://github.com/mainak9093/privacy-preserving-recommendation/blob/main/model/metrics.py"
click node_attack "https://github.com/mainak9093/privacy-preserving-recommendation/blob/main/model/attack.py"
click node_dp_study "https://github.com/mainak9093/privacy-preserving-recommendation/blob/main/model/dp_study.py"
click node_poison_study "https://github.com/mainak9093/privacy-preserving-recommendation/blob/main/model/poison_study.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_train_app,node_demo,node_server,node_serve,node_user toneBlue
class node_factor,node_clear_mf toneAmber
class node_pir,node_dpf,node_catalogue,node_harvest,node_channel toneMint
class node_mpc,node_mvp,node_nonlinear,node_msnzb,node_shares,node_prg,node_csprng toneRose
class node_data,node_metrics,node_attack,node_dp_study,node_poison_study toneIndigo
```

## Components

### Product workflow

- [Training runner](https://github.com/mainak9093/privacy-preserving-recommendation/blob/main/src/apps/train.cpp): `src/apps/train.cpp`
- [Recommendation demo](https://github.com/mainak9093/privacy-preserving-recommendation/blob/main/src/apps/demo.cpp): `src/apps/demo.cpp`
- [Serving server](https://github.com/mainak9093/privacy-preserving-recommendation/blob/main/src/apps/server.cpp): `src/apps/server.cpp`
- [Shared-score serving](https://github.com/mainak9093/privacy-preserving-recommendation/blob/main/src/serve/serve.cpp): `src/serve/serve.cpp`

### Private training

- [Private factorization](https://github.com/mainak9093/privacy-preserving-recommendation/blob/main/src/mf/factor.cpp): `src/mf/factor.cpp`
- [Cleartext factorization](https://github.com/mainak9093/privacy-preserving-recommendation/blob/main/model/mf.py): `model/mf.py`

### Private delivery

- [DPF-PIR](https://github.com/mainak9093/privacy-preserving-recommendation/blob/main/src/pir/pir.cpp): `src/pir/pir.cpp`
- [DPF keys](https://github.com/mainak9093/privacy-preserving-recommendation/blob/main/src/dpf/dpf.cpp): `src/dpf/dpf.cpp`
- [Fixed-width catalogue](https://github.com/mainak9093/privacy-preserving-recommendation/blob/main/src/pir/catalogue.cpp): `src/pir/catalogue.cpp`
- [Query harvesting](https://github.com/mainak9093/privacy-preserving-recommendation/blob/main/src/pir/harvest.cpp): `src/pir/harvest.cpp`
- [TCP framing](https://github.com/mainak9093/privacy-preserving-recommendation/blob/main/src/net/tcp.cpp): `src/net/tcp.cpp`

### Cryptographic substrate

- [Replicated MPC](https://github.com/mainak9093/privacy-preserving-recommendation/blob/main/src/mpc/mpc.cpp): `src/mpc/mpc.cpp`
- [Shared matrix-vector](https://github.com/mainak9093/privacy-preserving-recommendation/blob/main/src/mpc/mvp.cpp): `src/mpc/mvp.cpp`
- [Truncation and normalization](https://github.com/mainak9093/privacy-preserving-recommendation/blob/main/include/oblivrec/nonlinear.hpp): `include/oblivrec/nonlinear.hpp`
- [FSS comparison gate](https://github.com/mainak9093/privacy-preserving-recommendation/blob/main/src/mpc/nonlinear/msnzb.cpp): `src/mpc/nonlinear/msnzb.cpp`
- [Replicated shares](https://github.com/mainak9093/privacy-preserving-recommendation/blob/main/include/oblivrec/share.hpp): `include/oblivrec/share.hpp`
- [Pseudorandom generator](https://github.com/mainak9093/privacy-preserving-recommendation/blob/main/src/common/aes.cpp): `src/common/aes.cpp`
- [System randomness](https://github.com/mainak9093/privacy-preserving-recommendation/blob/main/src/common/csprng.cpp): `src/common/csprng.cpp`

### Modeling and analysis

- [Ratings data](https://github.com/mainak9093/privacy-preserving-recommendation/blob/main/model/data.py): `model/data.py`
- [Recommendation metrics](https://github.com/mainak9093/privacy-preserving-recommendation/blob/main/model/metrics.py): `model/metrics.py`
- [Fetch-observer attack](https://github.com/mainak9093/privacy-preserving-recommendation/blob/main/model/attack.py): `model/attack.py`
- [Privacy study](https://github.com/mainak9093/privacy-preserving-recommendation/blob/main/model/dp_study.py): `model/dp_study.py`
- [Poisoning study](https://github.com/mainak9093/privacy-preserving-recommendation/blob/main/model/poison_study.py): `model/poison_study.py`

### Other components

- **User**

## Connections

- User → Recommendation demo: requests recommendations (evidence: `README.md`)
- Training runner → Private factorization: runs private training (evidence: `src/apps/train.cpp`)
- Private factorization → Replicated MPC: computes shared products
- Private factorization → Truncation and normalization: uses nonlinear protocols
- Private factorization → Shared matrix-vector: uses matrix-vector work
- Replicated MPC → Replicated shares: exchanges replicated shares
- Truncation and normalization → Replicated MPC: uses MPC operations (evidence: `include/oblivrec/nonlinear.hpp`)
- Truncation and normalization → FSS comparison gate: uses comparison gate (evidence: `src/mpc/nonlinear/msnzb.cpp`)
- Recommendation demo → Shared-score serving: scores shared embedding (evidence: `src/apps/demo.cpp`)
- Recommendation demo → DPF-PIR: fetches selected records (evidence: `src/apps/demo.cpp`)
- Recommendation demo → TCP framing: sends network frames (evidence: `src/apps/demo.cpp`)
- Serving server → DPF-PIR: answers PIR keys (evidence: `src/apps/server.cpp`)
- Serving server → Fixed-width catalogue: loads catalogue (evidence: `src/apps/server.cpp`)
- DPF-PIR → DPF keys: evaluates query keys
- DPF-PIR → Fixed-width catalogue: reads records
- DPF keys → Pseudorandom generator: expands pseudorandom tree
- DPF keys → System randomness: generates key material (evidence: `src/dpf/dpf.cpp`)
- Query harvesting → DPF-PIR: uses PIR queries
- Query harvesting → Replicated MPC: shares harvested data
- Cleartext factorization → Ratings data: loads rating splits (evidence: `model/mf.py`)
- Cleartext factorization → Recommendation metrics: evaluates predictions (evidence: `model/mf.py`)
- Fetch-observer attack → Ratings data: uses dataset (evidence: `model/attack.py`)
- Fetch-observer attack → Cleartext factorization: fits baseline factors (evidence: `model/attack.py`)
- Privacy study → Fetch-observer attack: uses attack analysis (evidence: `model/dp_study.py`)
- Privacy study → Recommendation metrics: measures quality (evidence: `model/dp_study.py`)
- Poisoning study → Ratings data: uses dataset (evidence: `model/poison_study.py`)
- Poisoning study → Recommendation metrics: measures quality (evidence: `model/poison_study.py`)
- Training runner → Recommendation demo: provides trained model (evidence: `README.md`)
