# crypto-wei/mlkem-from-scratch architecture

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

- Interactive diagram: https://gitdiagram.com/crypto-wei/mlkem-from-scratch
- Repository: https://github.com/crypto-wei/mlkem-from-scratch

## Overview

這是以 Python 從頭實作的 Kyber512 教學 KEM，公開工作流程為 KeyGen、Encaps 與 Decaps，後者對有效長度但遭竄改的密文執行 implicit rejection。圖保留 README 說明的 IND-CPA、編碼、取樣與數學層。部分核心模組只有介面或文件說明；未展示的呼叫關係不推測，資料模型與數學模組的連線僅在來源索引或文件支持時列出。

Main entry points: [`mlkem/core/kem.py`](https://github.com/crypto-wei/mlkem-from-scratch/blob/main/mlkem/core/kem.py) (KEM 核心流程), [`mlkem/encoding/packing.py`](https://github.com/crypto-wei/mlkem-from-scratch/blob/main/mlkem/encoding/packing.py) (打包與解碼), [`mlkem/algebra/polyvec.py`](https://github.com/crypto-wei/mlkem-from-scratch/blob/main/mlkem/algebra/polyvec.py) (多項式向量運算), [`mlkem/algebra/polynomial.py`](https://github.com/crypto-wei/mlkem-from-scratch/blob/main/mlkem/algebra/polynomial.py) (多項式運算)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["公開 API"]
  node_api["輸入驗證與隨機數<br/>[mlkem.py]"]
  node_params["Kyber512 參數<br/>[params.py]"]
end

subgraph group_kem["KEM 與 IND-CPA"]
  node_kemcore["KEM 核心流程<br/>[kem.py]"]
  node_indcpa["IND-CPA 加密層<br/>[indcpa.py]"]
end

subgraph group_encoding["編碼與取樣"]
  node_packing["打包與解碼<br/>[packing.py]"]
  node_sampling["矩陣與噪聲取樣<br/>[sampling.py]"]
  node_symmetric["雜湊與 PRF<br/>[symmetric.py]"]
end

subgraph group_algebra["代數與數學"]
  node_poly["多項式運算<br/>[polynomial.py]"]
  node_polyvec["多項式向量運算<br/>[polyvec.py]"]
  node_ntt["NTT 轉換<br/>[ntt.py]"]
  node_reduce["模數約簡<br/>[reduce.py]"]
end

node_caller(("呼叫端"))

node_caller -->|"呼叫"| node_api
node_api -->|"讀取長度"| node_params
node_api -->|"委派操作"| node_kemcore
node_kemcore -.->|"執行加解密"| node_indcpa
node_kemcore -.->|"編碼金鑰"| node_packing
node_kemcore -.->|"導出祕密"| node_symmetric
node_indcpa -.->|"取樣矩陣與噪聲"| node_sampling
node_indcpa -.->|"編解碼資料"| node_packing
node_packing -->|"序列化多項式"| node_poly
node_packing -->|"序列化向量"| node_polyvec
node_sampling -->|"產生多項式"| node_poly
node_sampling -->|"產生向量"| node_polyvec
node_polyvec -->|"使用多項式"| node_poly
node_poly -->|"讀取維度"| node_params
node_polyvec -->|"讀取維度"| node_params

click node_api "https://github.com/crypto-wei/mlkem-from-scratch/blob/main/mlkem/api/mlkem.py"
click node_params "https://github.com/crypto-wei/mlkem-from-scratch/blob/main/mlkem/config/params.py"
click node_kemcore "https://github.com/crypto-wei/mlkem-from-scratch/blob/main/mlkem/core/kem.py"
click node_indcpa "https://github.com/crypto-wei/mlkem-from-scratch/blob/main/mlkem/core/indcpa.py"
click node_packing "https://github.com/crypto-wei/mlkem-from-scratch/blob/main/mlkem/encoding/packing.py"
click node_sampling "https://github.com/crypto-wei/mlkem-from-scratch/blob/main/mlkem/randomness/sampling.py"
click node_symmetric "https://github.com/crypto-wei/mlkem-from-scratch/blob/main/mlkem/randomness/symmetric.py"
click node_poly "https://github.com/crypto-wei/mlkem-from-scratch/blob/main/mlkem/algebra/polynomial.py"
click node_polyvec "https://github.com/crypto-wei/mlkem-from-scratch/blob/main/mlkem/algebra/polyvec.py"
click node_ntt "https://github.com/crypto-wei/mlkem-from-scratch/blob/main/mlkem/math/ntt.py"
click node_reduce "https://github.com/crypto-wei/mlkem-from-scratch/blob/main/mlkem/math/reduce.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_api,node_params toneBlue
class node_kemcore,node_indcpa toneAmber
class node_packing,node_sampling,node_symmetric toneMint
class node_poly,node_polyvec,node_ntt,node_reduce toneRose
class node_caller toneIndigo
```

## Components

### 公開 API

- [輸入驗證與隨機數](https://github.com/crypto-wei/mlkem-from-scratch/blob/main/mlkem/api/mlkem.py): `mlkem/api/mlkem.py`
- [Kyber512 參數](https://github.com/crypto-wei/mlkem-from-scratch/blob/main/mlkem/config/params.py): `mlkem/config/params.py`

### KEM 與 IND-CPA

- [KEM 核心流程](https://github.com/crypto-wei/mlkem-from-scratch/blob/main/mlkem/core/kem.py): `mlkem/core/kem.py`
- [IND-CPA 加密層](https://github.com/crypto-wei/mlkem-from-scratch/blob/main/mlkem/core/indcpa.py): `mlkem/core/indcpa.py`

### 編碼與取樣

- [打包與解碼](https://github.com/crypto-wei/mlkem-from-scratch/blob/main/mlkem/encoding/packing.py): `mlkem/encoding/packing.py`
- [矩陣與噪聲取樣](https://github.com/crypto-wei/mlkem-from-scratch/blob/main/mlkem/randomness/sampling.py): `mlkem/randomness/sampling.py`
- [雜湊與 PRF](https://github.com/crypto-wei/mlkem-from-scratch/blob/main/mlkem/randomness/symmetric.py): `mlkem/randomness/symmetric.py`

### 代數與數學

- [多項式運算](https://github.com/crypto-wei/mlkem-from-scratch/blob/main/mlkem/algebra/polynomial.py): `mlkem/algebra/polynomial.py`
- [多項式向量運算](https://github.com/crypto-wei/mlkem-from-scratch/blob/main/mlkem/algebra/polyvec.py): `mlkem/algebra/polyvec.py`
- [NTT 轉換](https://github.com/crypto-wei/mlkem-from-scratch/blob/main/mlkem/math/ntt.py): `mlkem/math/ntt.py`
- [模數約簡](https://github.com/crypto-wei/mlkem-from-scratch/blob/main/mlkem/math/reduce.py): `mlkem/math/reduce.py`

### Other components

- **呼叫端**

## Connections

- 呼叫端 → 輸入驗證與隨機數: 呼叫 (evidence: `README.md`)
- 輸入驗證與隨機數 → Kyber512 參數: 讀取長度 (evidence: `mlkem/api/mlkem.py`)
- 輸入驗證與隨機數 → KEM 核心流程: 委派操作 (evidence: `mlkem/api/mlkem.py`)
- KEM 核心流程 → IND-CPA 加密層: 執行加解密
- KEM 核心流程 → 打包與解碼: 編碼金鑰
- KEM 核心流程 → 雜湊與 PRF: 導出祕密
- IND-CPA 加密層 → 矩陣與噪聲取樣: 取樣矩陣與噪聲
- IND-CPA 加密層 → 打包與解碼: 編解碼資料
- 打包與解碼 → 多項式運算: 序列化多項式 (evidence: `mlkem/encoding/packing.py`)
- 打包與解碼 → 多項式向量運算: 序列化向量 (evidence: `mlkem/encoding/packing.py`)
- 矩陣與噪聲取樣 → 多項式運算: 產生多項式 (evidence: `mlkem/randomness/sampling.py`)
- 矩陣與噪聲取樣 → 多項式向量運算: 產生向量 (evidence: `mlkem/randomness/sampling.py`)
- 多項式向量運算 → 多項式運算: 使用多項式 (evidence: `mlkem/algebra/polyvec.py`)
- 多項式運算 → Kyber512 參數: 讀取維度 (evidence: `mlkem/algebra/polynomial.py`)
- 多項式向量運算 → Kyber512 參數: 讀取維度 (evidence: `mlkem/algebra/polyvec.py`)
