# menonsamir/spiral architecture

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

- Interactive diagram: https://gitdiagram.com/menonsamir/spiral
- Repository: https://github.com/menonsamir/spiral

## Overview

Spiral is a research implementation of single-server private information retrieval (PIR) using fully homomorphic encryption. Its principal workflow is a client-generated encrypted query, server-side expansion and database computation, then client-side decryption; the C++ executable contains both client and server work. The README also documents streaming, packing, and high-rate variants, plus implicit or explicit database representations. The excerpts show only parts of the runtime, so the graph omits unverified internal transitions; variant capabilities are included where documented.

Main entry points: [`src/spiral.cpp`](https://github.com/menonsamir/spiral/blob/main/src/spiral.cpp) (PIR runtime), [`src/client.cpp`](https://github.com/menonsamir/spiral/blob/main/src/client.cpp) (Client crypto), [`src/poly.cpp`](https://github.com/menonsamir/spiral/blob/main/src/poly.cpp) (Polynomial operations), [`src/core.cpp`](https://github.com/menonsamir/spiral/blob/main/src/core.cpp) (NTT and sampling)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_pir["PIR runtime"]
  node_client["Client crypto<br/>[client.cpp]"]
  node_runtime["PIR runtime<br/>[spiral.cpp]"]
  node_query["Query generation<br/>[spiral.cpp]"]
  node_setup["Server setup<br/>[spiral.cpp]"]
  node_expansion["Query expansion<br/>[spiral.cpp]"]
  node_dbcompute["Database computation<br/>[spiral.cpp]"]
  node_database[("Database input<br/>[spiral.cpp]")]
end

subgraph group_crypto["Crypto primitives"]
  node_poly["Polynomial operations<br/>[poly.cpp]"]
  node_core["NTT and sampling<br/>[core.cpp]"]
  node_utils["Gadget utilities<br/>[util.cpp]"]
  node_parameters["PIR parameters<br/>[values.h]"]
end

subgraph group_variants["PIR variants"]
  node_packing["Response packing<br/>[testing.cpp]"]
  node_streaming["Streaming mode<br/>[spiral.cpp]"]
  node_highrate["High-rate mode<br/>[spiral.cpp]"]
end

node_user(("PIR user"))

node_user -.->|"requests privately"| node_client
node_client -.->|"generates query"| node_query
node_query -.->|"submits query"| node_runtime
node_runtime -->|"generates setup"| node_setup
node_runtime -->|"generates query"| node_query
node_runtime -.->|"expands query"| node_expansion
node_runtime -.->|"computes response"| node_dbcompute
node_database -.->|"supplies records"| node_dbcompute
node_dbcompute -.->|"returns ciphertext"| node_client
node_client -->|"uses operations"| node_poly
node_poly -->|"uses NTT"| node_core
node_poly -->|"uses helpers"| node_utils
node_runtime -->|"uses parameters"| node_parameters
node_runtime -.->|"supports packing"| node_packing
node_runtime -->|"supports streaming"| node_streaming
node_runtime -.->|"supports high rate"| node_highrate

click node_client "https://github.com/menonsamir/spiral/blob/main/src/client.cpp"
click node_runtime "https://github.com/menonsamir/spiral/blob/main/src/spiral.cpp"
click node_query "https://github.com/menonsamir/spiral/blob/main/src/spiral.cpp"
click node_setup "https://github.com/menonsamir/spiral/blob/main/src/spiral.cpp"
click node_expansion "https://github.com/menonsamir/spiral/blob/main/src/spiral.cpp"
click node_dbcompute "https://github.com/menonsamir/spiral/blob/main/src/spiral.cpp"
click node_database "https://github.com/menonsamir/spiral/blob/main/src/spiral.cpp"
click node_poly "https://github.com/menonsamir/spiral/blob/main/src/poly.cpp"
click node_core "https://github.com/menonsamir/spiral/blob/main/src/core.cpp"
click node_utils "https://github.com/menonsamir/spiral/blob/main/src/util.cpp"
click node_parameters "https://github.com/menonsamir/spiral/blob/main/include/values.h"
click node_packing "https://github.com/menonsamir/spiral/blob/main/src/testing.cpp"
click node_streaming "https://github.com/menonsamir/spiral/blob/main/src/spiral.cpp"
click node_highrate "https://github.com/menonsamir/spiral/blob/main/src/spiral.cpp"

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_client,node_runtime,node_query,node_setup,node_expansion,node_dbcompute,node_database,node_user toneBlue
class node_poly,node_core,node_utils,node_parameters toneAmber
class node_packing,node_streaming,node_highrate toneMint
```

## Components

### PIR runtime

- [Client crypto](https://github.com/menonsamir/spiral/blob/main/src/client.cpp): `src/client.cpp`
- [PIR runtime](https://github.com/menonsamir/spiral/blob/main/src/spiral.cpp): `src/spiral.cpp`
- [Query generation](https://github.com/menonsamir/spiral/blob/main/src/spiral.cpp): `src/spiral.cpp`
- [Server setup](https://github.com/menonsamir/spiral/blob/main/src/spiral.cpp): `src/spiral.cpp`
- [Query expansion](https://github.com/menonsamir/spiral/blob/main/src/spiral.cpp): `src/spiral.cpp`
- [Database computation](https://github.com/menonsamir/spiral/blob/main/src/spiral.cpp): `src/spiral.cpp`
- [Database input](https://github.com/menonsamir/spiral/blob/main/src/spiral.cpp): `src/spiral.cpp`

### Crypto primitives

- [Polynomial operations](https://github.com/menonsamir/spiral/blob/main/src/poly.cpp): `src/poly.cpp`
- [NTT and sampling](https://github.com/menonsamir/spiral/blob/main/src/core.cpp): `src/core.cpp`
- [Gadget utilities](https://github.com/menonsamir/spiral/blob/main/src/util.cpp): `src/util.cpp`
- [PIR parameters](https://github.com/menonsamir/spiral/blob/main/include/values.h): `include/values.h`

### PIR variants

- [Response packing](https://github.com/menonsamir/spiral/blob/main/src/testing.cpp): `src/testing.cpp`
- [Streaming mode](https://github.com/menonsamir/spiral/blob/main/src/spiral.cpp): `src/spiral.cpp`
- [High-rate mode](https://github.com/menonsamir/spiral/blob/main/src/spiral.cpp): `src/spiral.cpp`

### Other components

- **PIR user**

## Connections

- PIR user → Client crypto: requests privately (evidence: `README.md`)
- Client crypto → Query generation: generates query (evidence: `README.md`)
- Query generation → PIR runtime: submits query (evidence: `README.md`)
- PIR runtime → Server setup: generates setup (evidence: `src/spiral.cpp`)
- PIR runtime → Query generation: generates query (evidence: `src/spiral.cpp`)
- PIR runtime → Query expansion: expands query (evidence: `src/spiral.cpp`)
- PIR runtime → Database computation: computes response (evidence: `src/spiral.cpp`)
- Database input → Database computation: supplies records (evidence: `src/spiral.cpp`)
- Database computation → Client crypto: returns ciphertext (evidence: `README.md`)
- Client crypto → Polynomial operations: uses operations
- Polynomial operations → NTT and sampling: uses NTT
- Polynomial operations → Gadget utilities: uses helpers
- PIR runtime → PIR parameters: uses parameters
- PIR runtime → Response packing: supports packing (evidence: `README.md`)
- PIR runtime → Streaming mode: supports streaming (evidence: `README.md`)
- PIR runtime → High-rate mode: supports high rate (evidence: `README.md`)