# nullspook/libpsijent architecture

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

- Interactive diagram: https://gitdiagram.com/nullspook/libpsijent
- Repository: https://github.com/nullspook/libpsijent

## Overview

libpsijent is a C library that produces random bits and bytes from jitter measured using hardware timestamps. Its main workflow initializes per-generator state, samples timing deltas, converts their low bits into output bits with optional decorrelation, PRNG masking, and bias amplification, then packs bits into bytes. The same measurement core supports raw-delta access and an initialization-time entropy estimate. Source excerpts show these runtime relationships; no separate storage or service subsystem is evident.

Main entry points: [`src/psijent.h`](https://github.com/nullspook/libpsijent/blob/develop/src/psijent.h) (Generator API), [`src/psijent.c`](https://github.com/nullspook/libpsijent/blob/develop/src/psijent.c) (Unpacked bits), [`src/hwtimestamp.h`](https://github.com/nullspook/libpsijent/blob/develop/src/hwtimestamp.h) (Hardware timestamps)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Public API"]
  node_api["Generator API<br/>[psijent.h]"]
  node_lifecycle["State lifecycle<br/>[psijent.c]"]
  node_raw["Raw deltas<br/>[psijent.c]"]
  node_estimate["Entropy estimate<br/>[psijent.c]"]
end

subgraph group_entropy["Jitter Source"]
  node_state["Generator state<br/>[psijent.c]"]
  node_measure["Delta measurement<br/>[psijent.c]"]
  node_timestamps["Hardware timestamps<br/>[hwtimestamp.h]"]
end

subgraph group_processing["Bit Processing"]
  node_entropic["Entropy bit<br/>[psijent.c]"]
  node_decorrelate["LFSR decorrelation<br/>[psijent.c]"]
  node_mask["PRNG masking<br/>[psijent.c]"]
  node_amplify["Bias amplification<br/>[psijent.c]"]
  node_unpacked["Unpacked bits<br/>[psijent.c]"]
  node_pack["Byte packing<br/>[psijent.c]"]
end

node_consumer(("Library caller"))

node_consumer -->|"calls"| node_api
node_api -->|"invokes"| node_lifecycle
node_api -->|"invokes"| node_raw
node_api -->|"invokes"| node_estimate
node_api -->|"invokes"| node_unpacked
node_api -->|"invokes"| node_pack
node_lifecycle -->|"allocates state"| node_state
node_lifecycle -->|"checks entropy"| node_estimate
node_raw -->|"samples deltas"| node_measure
node_estimate -->|"samples bits"| node_entropic
node_entropic -->|"measures"| node_measure
node_measure -->|"updates memory state"| node_state
node_measure -->|"reads counter"| node_timestamps
node_unpacked -->|"gets bits"| node_entropic
node_unpacked -.->|"optionally transforms"| node_decorrelate
node_unpacked -.->|"optionally XORs"| node_mask
node_unpacked -->|"amplifies bias"| node_amplify
node_pack -->|"requests bits"| node_unpacked
node_pack -->|"returns bytes"| node_consumer

click node_api "https://github.com/nullspook/libpsijent/blob/develop/src/psijent.h"
click node_lifecycle "https://github.com/nullspook/libpsijent/blob/develop/src/psijent.c"
click node_raw "https://github.com/nullspook/libpsijent/blob/develop/src/psijent.c"
click node_estimate "https://github.com/nullspook/libpsijent/blob/develop/src/psijent.c"
click node_state "https://github.com/nullspook/libpsijent/blob/develop/src/psijent.c"
click node_measure "https://github.com/nullspook/libpsijent/blob/develop/src/psijent.c"
click node_timestamps "https://github.com/nullspook/libpsijent/blob/develop/src/hwtimestamp.h"
click node_entropic "https://github.com/nullspook/libpsijent/blob/develop/src/psijent.c"
click node_decorrelate "https://github.com/nullspook/libpsijent/blob/develop/src/psijent.c"
click node_mask "https://github.com/nullspook/libpsijent/blob/develop/src/psijent.c"
click node_amplify "https://github.com/nullspook/libpsijent/blob/develop/src/psijent.c"
click node_unpacked "https://github.com/nullspook/libpsijent/blob/develop/src/psijent.c"
click node_pack "https://github.com/nullspook/libpsijent/blob/develop/src/psijent.c"

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_api,node_lifecycle,node_raw,node_estimate toneBlue
class node_state,node_measure,node_timestamps toneAmber
class node_entropic,node_decorrelate,node_mask,node_amplify,node_unpacked,node_pack toneMint
class node_consumer toneIndigo
```

## Components

### Public API

- [Generator API](https://github.com/nullspook/libpsijent/blob/develop/src/psijent.h): `src/psijent.h`
- [State lifecycle](https://github.com/nullspook/libpsijent/blob/develop/src/psijent.c): `src/psijent.c`
- [Raw deltas](https://github.com/nullspook/libpsijent/blob/develop/src/psijent.c): `src/psijent.c`
- [Entropy estimate](https://github.com/nullspook/libpsijent/blob/develop/src/psijent.c): `src/psijent.c`

### Jitter Source

- [Generator state](https://github.com/nullspook/libpsijent/blob/develop/src/psijent.c): `src/psijent.c`
- [Delta measurement](https://github.com/nullspook/libpsijent/blob/develop/src/psijent.c): `src/psijent.c`
- [Hardware timestamps](https://github.com/nullspook/libpsijent/blob/develop/src/hwtimestamp.h): `src/hwtimestamp.h`

### Bit Processing

- [Entropy bit](https://github.com/nullspook/libpsijent/blob/develop/src/psijent.c): `src/psijent.c`
- [LFSR decorrelation](https://github.com/nullspook/libpsijent/blob/develop/src/psijent.c): `src/psijent.c`
- [PRNG masking](https://github.com/nullspook/libpsijent/blob/develop/src/psijent.c): `src/psijent.c`
- [Bias amplification](https://github.com/nullspook/libpsijent/blob/develop/src/psijent.c): `src/psijent.c`
- [Unpacked bits](https://github.com/nullspook/libpsijent/blob/develop/src/psijent.c): `src/psijent.c`
- [Byte packing](https://github.com/nullspook/libpsijent/blob/develop/src/psijent.c): `src/psijent.c`

### Other components

- **Library caller**

## Connections

- Library caller → Generator API: calls
- Generator API → State lifecycle: invokes
- Generator API → Raw deltas: invokes
- Generator API → Entropy estimate: invokes
- Generator API → Unpacked bits: invokes
- Generator API → Byte packing: invokes
- State lifecycle → Generator state: allocates state
- State lifecycle → Entropy estimate: checks entropy
- Raw deltas → Delta measurement: samples deltas
- Entropy estimate → Entropy bit: samples bits
- Entropy bit → Delta measurement: measures
- Delta measurement → Generator state: updates memory state
- Delta measurement → Hardware timestamps: reads counter
- Unpacked bits → Entropy bit: gets bits
- Unpacked bits → LFSR decorrelation: optionally transforms
- Unpacked bits → PRNG masking: optionally XORs
- Unpacked bits → Bias amplification: amplifies bias
- Byte packing → Unpacked bits: requests bits
- Byte packing → Library caller: returns bytes