# olvid-io/olvid-aws-server architecture

> Architecture diagram of the GitHub repository olvid-io/olvid-aws-server, 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/olvid-io/olvid-aws-server
- Repository: https://github.com/olvid-io/olvid-aws-server

## Overview

Olvid’s AWS-hosted message distribution server accepts app requests through REST and WebSocket Lambda endpoints, manages identity and server sessions, distributes encrypted messages and attachments, and supports device transfer. The README documents the principal send–notify–download–receipt workflow and other capabilities. Many endpoint implementations are unsampled, so their documented relationships are cited to the README; the transfer server’s internal relationships are limited to SOURCE INDEX references.

Main entry points: [`dynamodb/src/uploadMessageAndGetUids/java/io/olvid/server/UploadMessageAndGetUids.java`](https://github.com/olvid-io/olvid-aws-server/blob/main/dynamodb/src/uploadMessageAndGetUids/java/io/olvid/server/UploadMessageAndGetUids.java) (Upload message), [`dynamodb/src/getToken/java/io/olvid/server/GetToken.java`](https://github.com/olvid-io/olvid-aws-server/blob/main/dynamodb/src/getToken/java/io/olvid/server/GetToken.java) (Issue token), [`dynamodb/src/downloadMessagesAndListAttachments/java/io/olvid/server/DownloadMessagesAndListAttachments.java`](https://github.com/olvid-io/olvid-aws-server/blob/main/dynamodb/src/downloadMessagesAndListAttachments/java/io/olvid/server/DownloadMessagesAndListAttachments.java) (Download messages), [`dynamodb/src/CryptoLib/java/io/olvid/server/Base64RequestStreamHandler.java`](https://github.com/olvid-io/olvid-aws-server/blob/main/dynamodb/src/CryptoLib/java/io/olvid/server/Base64RequestStreamHandler.java) (Request codec)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and sessions"]
  node_request_codec["Request codec"]
  node_challenge["Request challenge"]
  node_token["Issue token<br/>[GetToken.java]"]
  node_pow["Proof of work"]
end

subgraph group_messaging["Message delivery"]
  node_upload["Upload message"]
  node_monitor["Monitor attachments"]
  node_download["Download messages"]
  node_extended["Download preview"]
  node_receipt["Upload receipt"]
  node_ws_receipt["Send receipts"]
  node_push["Push notifications"]
  node_attachment_api["Attachment endpoints"]
end

subgraph group_devices["Devices and accounts"]
  node_devices_api["Device management"]
  node_discovery["Device discovery"]
  node_account_data["User data<br/>[PutUserData.java]"]
  node_backup["Backups<br/>[BackupCreate.java]"]
  node_group_blobs["Group blobs"]
end

subgraph group_transfer["Device transfer"]
  node_transfer_source["Transfer source<br/>[Source.java]"]
  node_transfer_relay["Transfer relay<br/>[Relay.java]"]
  node_transfer_target["Transfer target<br/>[Target.java]"]
end

subgraph group_shared["Shared runtime"]
  node_encoding["Binary encoding<br/>[Encoded.java]"]
  node_crypto["Cryptography<br/>[Suite.java]"]
  node_identity["Identity model<br/>[Identity.java]"]
  node_api_keys["API key utilities<br/>[ApiKeyUtil.java]"]
end

node_app(("Olvid app"))
node_rest["REST API Gateway"]
node_ws["WebSocket Gateway"]
node_dynamo[("DynamoDB")]
node_s3[("Amazon S3")]
node_sns["Amazon SNS"]
node_websocket(("Device WebSocket"))

node_app -->|"sends requests"| node_rest
node_app -->|"opens connection"| node_ws
node_rest -->|"routes requests"| node_request_codec
node_request_codec -.->|"dispatches request"| node_upload
node_app -->|"requests challenge"| node_challenge
node_app -->|"requests token"| node_token
node_app -->|"requests challenge"| node_pow
node_app -->|"uploads message"| node_upload
node_app -->|"uploads attachment"| node_s3
node_s3 -->|"triggers on upload"| node_monitor
node_monitor -->|"notifies completion"| node_push
node_push -->|"publishes notification"| node_sns
node_app -->|"lists messages"| node_download
node_app -->|"downloads preview"| node_extended
node_app -->|"downloads attachment"| node_s3
node_app -->|"uploads receipt"| node_receipt
node_dynamo -->|"triggers on receipt"| node_ws_receipt
node_ws_receipt -->|"sends receipt"| node_websocket
node_app -.->|"manages attachments"| node_attachment_api
node_app -.->|"manages devices"| node_devices_api
node_app -.->|"discovers devices"| node_discovery
node_app -.->|"manages user data"| node_account_data
node_app -.->|"manages backups"| node_backup
node_app -.->|"manages group blobs"| node_group_blobs
node_transfer_relay -->|"uses request type"| node_transfer_source
node_transfer_target -.->|"exchanges transfer data"| node_transfer_relay
node_request_codec -->|"decodes payload"| node_encoding
node_token -->|"uses identity"| node_identity
node_token -->|"uses cryptography"| node_crypto
node_token -->|"checks API keys"| node_api_keys
node_upload -->|"uses encoding"| node_encoding
node_upload -->|"uses identity"| node_identity
node_download -->|"uses identity"| node_identity
node_download -->|"uses encoding"| node_encoding
node_upload -.->|"stores message"| node_dynamo
node_upload -->|"creates upload URL"| node_s3
node_download -.->|"reads messages"| node_dynamo

click node_request_codec "https://github.com/olvid-io/olvid-aws-server/blob/main/dynamodb/src/CryptoLib/java/io/olvid/server/Base64RequestStreamHandler.java"
click node_challenge "https://github.com/olvid-io/olvid-aws-server/blob/main/dynamodb/src/requestChallenge/java/io/olvid/server/RequestChallenge.java"
click node_token "https://github.com/olvid-io/olvid-aws-server/blob/main/dynamodb/src/getToken/java/io/olvid/server/GetToken.java"
click node_pow "https://github.com/olvid-io/olvid-aws-server/blob/main/dynamodb/src/getPoWChallenge/java/io/olvid/server/ProofOfWorkEngine.java"
click node_upload "https://github.com/olvid-io/olvid-aws-server/blob/main/dynamodb/src/uploadMessageAndGetUids/java/io/olvid/server/UploadMessageAndGetUids.java"
click node_monitor "https://github.com/olvid-io/olvid-aws-server/blob/main/dynamodb/src/monitorS3AttachmentChunks/java/io/olvid/server/MonitorS3AttachmentChunks.java"
click node_download "https://github.com/olvid-io/olvid-aws-server/blob/main/dynamodb/src/downloadMessagesAndListAttachments/java/io/olvid/server/DownloadMessagesAndListAttachments.java"
click node_extended "https://github.com/olvid-io/olvid-aws-server/blob/main/dynamodb/src/downloadMessageExtendedContent/java/io/olvid/server/DownloadMessageExtendedContent.java"
click node_receipt "https://github.com/olvid-io/olvid-aws-server/blob/main/dynamodb/src/uploadReturnReceipt/java/io/olvid/server/UploadReturnReceipt.java"
click node_ws_receipt "https://github.com/olvid-io/olvid-aws-server/blob/main/dynamodb/src/wsSendReturnReceipts/java/io/olvid/server/WsSendReturnReceipts.java"
click node_push "https://github.com/olvid-io/olvid-aws-server/blob/main/dynamodb/src/PushLib/java/io/olvid/server/PushNotificationUtil.java"
click node_attachment_api "https://github.com/olvid-io/olvid-aws-server/blob/main/dynamodb/src/uploadAttachment/java/io/olvid/server/UploadAttachment.java"
click node_devices_api "https://github.com/olvid-io/olvid-aws-server/blob/main/dynamodb/src/deviceManagement/java/io/olvid/server/DeviceManagement.java"
click node_discovery "https://github.com/olvid-io/olvid-aws-server/blob/main/dynamodb/src/deviceDiscovery/java/io/olvid/server/DeviceDiscovery.java"
click node_account_data "https://github.com/olvid-io/olvid-aws-server/blob/main/dynamodb/src/putUserData/java/io/olvid/server/PutUserData.java"
click node_backup "https://github.com/olvid-io/olvid-aws-server/blob/main/dynamodb/src/backupCreate/java/io/olvid/server/BackupCreate.java"
click node_group_blobs "https://github.com/olvid-io/olvid-aws-server/blob/main/dynamodb/src/groupBlobCreate/java/io/olvid/server/GroupBlobCreate.java"
click node_transfer_source "https://github.com/olvid-io/olvid-aws-server/blob/main/transfer.olvid.io/src/source/java/io/olvid/transfer/Source.java"
click node_transfer_relay "https://github.com/olvid-io/olvid-aws-server/blob/main/transfer.olvid.io/src/relay/java/io/olvid/transfer/Relay.java"
click node_transfer_target "https://github.com/olvid-io/olvid-aws-server/blob/main/transfer.olvid.io/src/target/java/io/olvid/transfer/Target.java"
click node_encoding "https://github.com/olvid-io/olvid-aws-server/blob/main/dynamodb/src/CryptoLib/java/io/olvid/server/encoder/Encoded.java"
click node_crypto "https://github.com/olvid-io/olvid-aws-server/blob/main/dynamodb/src/CryptoLib/java/io/olvid/server/crypto/Suite.java"
click node_identity "https://github.com/olvid-io/olvid-aws-server/blob/main/dynamodb/src/CryptoLib/java/io/olvid/server/crypto/Identity.java"
click node_api_keys "https://github.com/olvid-io/olvid-aws-server/blob/main/dynamodb/src/ApiKeyLib/java/io/olvid/server/ApiKeyUtil.java"

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_request_codec,node_challenge,node_token,node_pow toneBlue
class node_upload,node_monitor,node_download,node_extended,node_receipt,node_ws_receipt,node_push,node_attachment_api,node_dynamo,node_s3 toneAmber
class node_devices_api,node_discovery,node_account_data,node_backup,node_group_blobs,node_rest toneMint
class node_transfer_source,node_transfer_relay,node_transfer_target toneRose
class node_encoding,node_crypto,node_identity,node_api_keys,node_app,node_ws,node_sns,node_websocket toneIndigo
```

## Components

### API and sessions

- [Request codec](https://github.com/olvid-io/olvid-aws-server/blob/main/dynamodb/src/CryptoLib/java/io/olvid/server/Base64RequestStreamHandler.java): `dynamodb/src/CryptoLib/java/io/olvid/server/Base64RequestStreamHandler.java`
- [Request challenge](https://github.com/olvid-io/olvid-aws-server/blob/main/dynamodb/src/requestChallenge/java/io/olvid/server/RequestChallenge.java): `dynamodb/src/requestChallenge/java/io/olvid/server/RequestChallenge.java`
- [Issue token](https://github.com/olvid-io/olvid-aws-server/blob/main/dynamodb/src/getToken/java/io/olvid/server/GetToken.java): `dynamodb/src/getToken/java/io/olvid/server/GetToken.java`
- [Proof of work](https://github.com/olvid-io/olvid-aws-server/blob/main/dynamodb/src/getPoWChallenge/java/io/olvid/server/ProofOfWorkEngine.java): `dynamodb/src/getPoWChallenge/java/io/olvid/server/ProofOfWorkEngine.java`

### Message delivery

- [Upload message](https://github.com/olvid-io/olvid-aws-server/blob/main/dynamodb/src/uploadMessageAndGetUids/java/io/olvid/server/UploadMessageAndGetUids.java): `dynamodb/src/uploadMessageAndGetUids/java/io/olvid/server/UploadMessageAndGetUids.java`
- [Monitor attachments](https://github.com/olvid-io/olvid-aws-server/blob/main/dynamodb/src/monitorS3AttachmentChunks/java/io/olvid/server/MonitorS3AttachmentChunks.java): `dynamodb/src/monitorS3AttachmentChunks/java/io/olvid/server/MonitorS3AttachmentChunks.java`
- [Download messages](https://github.com/olvid-io/olvid-aws-server/blob/main/dynamodb/src/downloadMessagesAndListAttachments/java/io/olvid/server/DownloadMessagesAndListAttachments.java): `dynamodb/src/downloadMessagesAndListAttachments/java/io/olvid/server/DownloadMessagesAndListAttachments.java`
- [Download preview](https://github.com/olvid-io/olvid-aws-server/blob/main/dynamodb/src/downloadMessageExtendedContent/java/io/olvid/server/DownloadMessageExtendedContent.java): `dynamodb/src/downloadMessageExtendedContent/java/io/olvid/server/DownloadMessageExtendedContent.java`
- [Upload receipt](https://github.com/olvid-io/olvid-aws-server/blob/main/dynamodb/src/uploadReturnReceipt/java/io/olvid/server/UploadReturnReceipt.java): `dynamodb/src/uploadReturnReceipt/java/io/olvid/server/UploadReturnReceipt.java`
- [Send receipts](https://github.com/olvid-io/olvid-aws-server/blob/main/dynamodb/src/wsSendReturnReceipts/java/io/olvid/server/WsSendReturnReceipts.java): `dynamodb/src/wsSendReturnReceipts/java/io/olvid/server/WsSendReturnReceipts.java`
- [Push notifications](https://github.com/olvid-io/olvid-aws-server/blob/main/dynamodb/src/PushLib/java/io/olvid/server/PushNotificationUtil.java): `dynamodb/src/PushLib/java/io/olvid/server/PushNotificationUtil.java`
- [Attachment endpoints](https://github.com/olvid-io/olvid-aws-server/blob/main/dynamodb/src/uploadAttachment/java/io/olvid/server/UploadAttachment.java): `dynamodb/src/uploadAttachment/java/io/olvid/server/UploadAttachment.java`

### Devices and accounts

- [Device management](https://github.com/olvid-io/olvid-aws-server/blob/main/dynamodb/src/deviceManagement/java/io/olvid/server/DeviceManagement.java): `dynamodb/src/deviceManagement/java/io/olvid/server/DeviceManagement.java`
- [Device discovery](https://github.com/olvid-io/olvid-aws-server/blob/main/dynamodb/src/deviceDiscovery/java/io/olvid/server/DeviceDiscovery.java): `dynamodb/src/deviceDiscovery/java/io/olvid/server/DeviceDiscovery.java`
- [User data](https://github.com/olvid-io/olvid-aws-server/blob/main/dynamodb/src/putUserData/java/io/olvid/server/PutUserData.java): `dynamodb/src/putUserData/java/io/olvid/server/PutUserData.java`
- [Backups](https://github.com/olvid-io/olvid-aws-server/blob/main/dynamodb/src/backupCreate/java/io/olvid/server/BackupCreate.java): `dynamodb/src/backupCreate/java/io/olvid/server/BackupCreate.java`
- [Group blobs](https://github.com/olvid-io/olvid-aws-server/blob/main/dynamodb/src/groupBlobCreate/java/io/olvid/server/GroupBlobCreate.java): `dynamodb/src/groupBlobCreate/java/io/olvid/server/GroupBlobCreate.java`

### Device transfer

- [Transfer source](https://github.com/olvid-io/olvid-aws-server/blob/main/transfer.olvid.io/src/source/java/io/olvid/transfer/Source.java): `transfer.olvid.io/src/source/java/io/olvid/transfer/Source.java`
- [Transfer relay](https://github.com/olvid-io/olvid-aws-server/blob/main/transfer.olvid.io/src/relay/java/io/olvid/transfer/Relay.java): `transfer.olvid.io/src/relay/java/io/olvid/transfer/Relay.java`
- [Transfer target](https://github.com/olvid-io/olvid-aws-server/blob/main/transfer.olvid.io/src/target/java/io/olvid/transfer/Target.java): `transfer.olvid.io/src/target/java/io/olvid/transfer/Target.java`

### Shared runtime

- [Binary encoding](https://github.com/olvid-io/olvid-aws-server/blob/main/dynamodb/src/CryptoLib/java/io/olvid/server/encoder/Encoded.java): `dynamodb/src/CryptoLib/java/io/olvid/server/encoder/Encoded.java`
- [Cryptography](https://github.com/olvid-io/olvid-aws-server/blob/main/dynamodb/src/CryptoLib/java/io/olvid/server/crypto/Suite.java): `dynamodb/src/CryptoLib/java/io/olvid/server/crypto/Suite.java`
- [Identity model](https://github.com/olvid-io/olvid-aws-server/blob/main/dynamodb/src/CryptoLib/java/io/olvid/server/crypto/Identity.java): `dynamodb/src/CryptoLib/java/io/olvid/server/crypto/Identity.java`
- [API key utilities](https://github.com/olvid-io/olvid-aws-server/blob/main/dynamodb/src/ApiKeyLib/java/io/olvid/server/ApiKeyUtil.java): `dynamodb/src/ApiKeyLib/java/io/olvid/server/ApiKeyUtil.java`

### Other components

- **Olvid app**
- **REST API Gateway**
- **WebSocket Gateway**
- **DynamoDB**
- **Amazon S3**
- **Amazon SNS**
- **Device WebSocket**

## Connections

- Olvid app → REST API Gateway: sends requests (evidence: `README.md`)
- Olvid app → WebSocket Gateway: opens connection (evidence: `README.md`)
- REST API Gateway → Request codec: routes requests (evidence: `README.md`)
- Request codec → Upload message: dispatches request (evidence: `dynamodb/src/uploadMessageAndGetUids/java/io/olvid/server/UploadMessageAndGetUids.java`)
- Olvid app → Request challenge: requests challenge (evidence: `README.md`)
- Olvid app → Issue token: requests token (evidence: `README.md`)
- Olvid app → Proof of work: requests challenge (evidence: `README.md`)
- Olvid app → Upload message: uploads message (evidence: `README.md`)
- Olvid app → Amazon S3: uploads attachment (evidence: `README.md`)
- Amazon S3 → Monitor attachments: triggers on upload (evidence: `README.md`)
- Monitor attachments → Push notifications: notifies completion (evidence: `README.md`)
- Push notifications → Amazon SNS: publishes notification (evidence: `dynamodb/src/PushLib/java/io/olvid/server/PushNotificationUtil.java`)
- Olvid app → Download messages: lists messages (evidence: `README.md`)
- Olvid app → Download preview: downloads preview (evidence: `README.md`)
- Olvid app → Amazon S3: downloads attachment (evidence: `README.md`)
- Olvid app → Upload receipt: uploads receipt (evidence: `README.md`)
- DynamoDB → Send receipts: triggers on receipt (evidence: `README.md`)
- Send receipts → Device WebSocket: sends receipt (evidence: `README.md`)
- Olvid app → Attachment endpoints: manages attachments
- Olvid app → Device management: manages devices
- Olvid app → Device discovery: discovers devices
- Olvid app → User data: manages user data
- Olvid app → Backups: manages backups
- Olvid app → Group blobs: manages group blobs
- Transfer relay → Transfer source: uses request type (evidence: `transfer.olvid.io/src/relay/java/io/olvid/transfer/Relay.java`)
- Transfer target → Transfer relay: exchanges transfer data
- Request codec → Binary encoding: decodes payload (evidence: `dynamodb/src/CryptoLib/java/io/olvid/server/Base64RequestStreamHandler.java`)
- Issue token → Identity model: uses identity (evidence: `dynamodb/src/getToken/java/io/olvid/server/GetToken.java`)
- Issue token → Cryptography: uses cryptography (evidence: `dynamodb/src/getToken/java/io/olvid/server/GetToken.java`)
- Issue token → API key utilities: checks API keys (evidence: `dynamodb/src/getToken/java/io/olvid/server/GetToken.java`)
- Upload message → Binary encoding: uses encoding (evidence: `dynamodb/src/uploadMessageAndGetUids/java/io/olvid/server/UploadMessageAndGetUids.java`)
- Upload message → Identity model: uses identity (evidence: `dynamodb/src/uploadMessageAndGetUids/java/io/olvid/server/UploadMessageAndGetUids.java`)
- Download messages → Identity model: uses identity (evidence: `dynamodb/src/downloadMessagesAndListAttachments/java/io/olvid/server/DownloadMessagesAndListAttachments.java`)
- Download messages → Binary encoding: uses encoding (evidence: `dynamodb/src/downloadMessagesAndListAttachments/java/io/olvid/server/DownloadMessagesAndListAttachments.java`)
- Upload message → DynamoDB: stores message
- Upload message → Amazon S3: creates upload URL (evidence: `README.md`)
- Download messages → DynamoDB: reads messages