# thomas-vilte/mls-go architecture

> Architecture diagram of the GitHub repository thomas-vilte/mls-go, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/thomas-vilte/mls-go
- Repository: https://github.com/thomas-vilte/mls-go

## Overview

mls-go is a pure-Go MLS (RFC 9420) library. Its principal workflow creates a client and KeyPackage, creates a group, invites a member through a commit and Welcome, then protects and receives application messages. The graph also preserves proposal/commit processing, external joins, tree synchronization, key scheduling, extensions, and storage as distinct capabilities. Edges are limited to relationships shown in the README or source-index references; unsampled implementation details are not inferred.

Main entry points: [`group/group.go`](https://github.com/thomas-vilte/mls-go/blob/main/group/group.go) (Group Lifecycle), [`treesync/tree.go`](https://github.com/thomas-vilte/mls-go/blob/main/treesync/tree.go) (Ratchet Tree), [`client.go`](https://github.com/thomas-vilte/mls-go/blob/main/client.go) (MLS Client), [`group/welcome.go`](https://github.com/thomas-vilte/mls-go/blob/main/group/welcome.go) (Welcome Join)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Client API"]
  node_client["MLS Client<br/>[client.go]"]
  node_memory_store[("Memory Storage<br/>[memory.go]")]
  node_file_store[("File Storage<br/>[file.go]")]
end

subgraph group_protocol["MLS Protocol"]
  node_keypackages["KeyPackages<br/>[key_packages.go]"]
  node_group["Group Lifecycle<br/>[group.go]"]
  node_commits["Commit Processing<br/>[commit.go]"]
  node_welcome["Welcome Join<br/>[welcome.go]"]
  node_messages["Wire Messages<br/>[messages.go]"]
  node_framing["Message Framing<br/>[private_message.go]"]
  node_extensions["MLS Extensions<br/>[extensions.go]"]
  node_external_senders["External Senders"]
end

subgraph group_crypto["Crypto and State"]
  node_treesync["Ratchet Tree<br/>[tree.go]"]
  node_tree_nodes["Tree Nodes<br/>[node.go]"]
  node_tree_encoding["Tree Serialization<br/>[serialization.go]"]
  node_schedule["Key Schedule<br/>[schedule.go]"]
  node_hpke["HPKE<br/>[hpke.go]"]
  node_cipher_suite["Cipher Suites<br/>[ciphersuite.go]"]
end

subgraph group_interop["Interop Service"]
  node_interop_server["Interop gRPC Server<br/>[handler.go]"]
  node_interop_runner["Interop Runner<br/>[main.go]"]
end

node_user(("Application"))

node_user -->|"uses"| node_client
node_client -->|"creates"| node_keypackages
node_client -->|"manages"| node_group
node_client -->|"defaults to"| node_memory_store
node_client -->|"can configure"| node_file_store
node_client -->|"protects messages"| node_framing
node_group -.->|"processes"| node_commits
node_group -->|"joins with"| node_welcome
node_group -->|"uses"| node_treesync
node_group -->|"uses"| node_schedule
node_group -->|"uses"| node_extensions
node_welcome -->|"encodes Welcome"| node_messages
node_welcome -->|"uses"| node_schedule
node_welcome -->|"validates tree"| node_treesync
node_framing -->|"uses"| node_hpke
node_framing -->|"uses"| node_cipher_suite
node_framing -.->|"uses ratchet"| node_treesync
node_treesync -->|"uses"| node_tree_nodes
node_treesync -.->|"serializes via"| node_tree_encoding
node_keypackages -->|"uses"| node_cipher_suite
node_keypackages -->|"uses"| node_treesync
node_extensions -->|"encodes ratchet tree"| node_treesync
node_extensions -.->|"includes"| node_external_senders
node_interop_runner -->|"calls gRPC"| node_interop_server
node_interop_server -->|"handles MLS operations"| node_group

click node_client "https://github.com/thomas-vilte/mls-go/blob/main/client.go"
click node_keypackages "https://github.com/thomas-vilte/mls-go/blob/main/keypackages/key_packages.go"
click node_group "https://github.com/thomas-vilte/mls-go/blob/main/group/group.go"
click node_commits "https://github.com/thomas-vilte/mls-go/blob/main/group/commit.go"
click node_welcome "https://github.com/thomas-vilte/mls-go/blob/main/group/welcome.go"
click node_messages "https://github.com/thomas-vilte/mls-go/blob/main/messages/messages.go"
click node_framing "https://github.com/thomas-vilte/mls-go/blob/main/framing/private_message.go"
click node_extensions "https://github.com/thomas-vilte/mls-go/blob/main/extensions/extensions.go"
click node_external_senders "https://github.com/thomas-vilte/mls-go/blob/main/extensions/external_senders.go"
click node_treesync "https://github.com/thomas-vilte/mls-go/blob/main/treesync/tree.go"
click node_tree_nodes "https://github.com/thomas-vilte/mls-go/blob/main/treesync/node.go"
click node_tree_encoding "https://github.com/thomas-vilte/mls-go/blob/main/treesync/serialization.go"
click node_schedule "https://github.com/thomas-vilte/mls-go/blob/main/schedule/schedule.go"
click node_hpke "https://github.com/thomas-vilte/mls-go/blob/main/ciphersuite/hpke.go"
click node_cipher_suite "https://github.com/thomas-vilte/mls-go/blob/main/ciphersuite/ciphersuite.go"
click node_memory_store "https://github.com/thomas-vilte/mls-go/blob/main/storage/memory/memory.go"
click node_file_store "https://github.com/thomas-vilte/mls-go/blob/main/storage/file/file.go"
click node_interop_server "https://github.com/thomas-vilte/mls-go/blob/main/interop/server/handler.go"
click node_interop_runner "https://github.com/thomas-vilte/mls-go/blob/main/interop/testrunner/main.go"

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_memory_store,node_file_store toneBlue
class node_keypackages,node_group,node_commits,node_welcome,node_messages,node_framing,node_extensions,node_external_senders toneAmber
class node_treesync,node_tree_nodes,node_tree_encoding,node_schedule,node_hpke,node_cipher_suite toneMint
class node_interop_server,node_interop_runner toneRose
class node_user toneIndigo
```

## Components

### Client API

- [MLS Client](https://github.com/thomas-vilte/mls-go/blob/main/client.go): `client.go`
- [Memory Storage](https://github.com/thomas-vilte/mls-go/blob/main/storage/memory/memory.go): `storage/memory/memory.go`
- [File Storage](https://github.com/thomas-vilte/mls-go/blob/main/storage/file/file.go): `storage/file/file.go`

### MLS Protocol

- [KeyPackages](https://github.com/thomas-vilte/mls-go/blob/main/keypackages/key_packages.go): `keypackages/key_packages.go`
- [Group Lifecycle](https://github.com/thomas-vilte/mls-go/blob/main/group/group.go): `group/group.go`
- [Commit Processing](https://github.com/thomas-vilte/mls-go/blob/main/group/commit.go): `group/commit.go`
- [Welcome Join](https://github.com/thomas-vilte/mls-go/blob/main/group/welcome.go): `group/welcome.go`
- [Wire Messages](https://github.com/thomas-vilte/mls-go/blob/main/messages/messages.go): `messages/messages.go`
- [Message Framing](https://github.com/thomas-vilte/mls-go/blob/main/framing/private_message.go): `framing/private_message.go`
- [MLS Extensions](https://github.com/thomas-vilte/mls-go/blob/main/extensions/extensions.go): `extensions/extensions.go`
- [External Senders](https://github.com/thomas-vilte/mls-go/blob/main/extensions/external_senders.go): `extensions/external_senders.go`

### Crypto and State

- [Ratchet Tree](https://github.com/thomas-vilte/mls-go/blob/main/treesync/tree.go): `treesync/tree.go`
- [Tree Nodes](https://github.com/thomas-vilte/mls-go/blob/main/treesync/node.go): `treesync/node.go`
- [Tree Serialization](https://github.com/thomas-vilte/mls-go/blob/main/treesync/serialization.go): `treesync/serialization.go`
- [Key Schedule](https://github.com/thomas-vilte/mls-go/blob/main/schedule/schedule.go): `schedule/schedule.go`
- [HPKE](https://github.com/thomas-vilte/mls-go/blob/main/ciphersuite/hpke.go): `ciphersuite/hpke.go`
- [Cipher Suites](https://github.com/thomas-vilte/mls-go/blob/main/ciphersuite/ciphersuite.go): `ciphersuite/ciphersuite.go`

### Interop Service

- [Interop gRPC Server](https://github.com/thomas-vilte/mls-go/blob/main/interop/server/handler.go): `interop/server/handler.go`
- [Interop Runner](https://github.com/thomas-vilte/mls-go/blob/main/interop/testrunner/main.go): `interop/testrunner/main.go`

### Other components

- **Application**

## Connections

- Application → MLS Client: uses
- MLS Client → KeyPackages: creates (evidence: `client.go`)
- MLS Client → Group Lifecycle: manages (evidence: `client.go`)
- MLS Client → Memory Storage: defaults to (evidence: `client.go`)
- MLS Client → File Storage: can configure (evidence: `client.go`)
- MLS Client → Message Framing: protects messages (evidence: `client.go`)
- Group Lifecycle → Commit Processing: processes
- Group Lifecycle → Welcome Join: joins with (evidence: `group/group.go`)
- Group Lifecycle → Ratchet Tree: uses (evidence: `group/group.go`)
- Group Lifecycle → Key Schedule: uses (evidence: `group/group.go`)
- Group Lifecycle → MLS Extensions: uses
- Welcome Join → Wire Messages: encodes Welcome (evidence: `messages/messages.go`)
- Welcome Join → Key Schedule: uses (evidence: `group/welcome.go`)
- Welcome Join → Ratchet Tree: validates tree (evidence: `group/welcome.go`)
- Message Framing → HPKE: uses (evidence: `framing/private_message.go`)
- Message Framing → Cipher Suites: uses (evidence: `framing/private_message.go`)
- Message Framing → Ratchet Tree: uses ratchet
- Ratchet Tree → Tree Nodes: uses (evidence: `treesync/tree.go`)
- Ratchet Tree → Tree Serialization: serializes via
- KeyPackages → Cipher Suites: uses (evidence: `keypackages/key_packages.go`)
- KeyPackages → Ratchet Tree: uses (evidence: `keypackages/key_packages.go`)
- MLS Extensions → Ratchet Tree: encodes ratchet tree
- MLS Extensions → External Senders: includes
- Interop Runner → Interop gRPC Server: calls gRPC (evidence: `interop/testrunner/main.go`)
- Interop gRPC Server → Group Lifecycle: handles MLS operations (evidence: `interop/server/handler.go`)
