---
# System prepended metadata

title: Dash Chat Architecture
tags: [architecture]

---

# Dash Chat Architecture

## Requirements

Before reading this document, please read the [list of Dash Chat requirements](https://hackmd.io/qtaaE4AlTGyBVarM5fNKdQ).

## Tech Stack

- iroh: for QUIC direct p2p connections with NAT traversal.
- p2panda: p2p framework for core data types and synchronization.
- tauri: framework to produce native mobile and desktop apps from web based UIs and rust backends.
- svelte for the UI.
- tinySSB for LoRa?
- Axum for servers.
    - Cassandra as a distributed database for internet servers?

To learn more about the choice of p2p protocols see the [p2p Protocol Comparison](https://hackmd.io/Agc6m-3QTz2mIRpE9brytw).

## Architecture

This is a graphical overview of all the components for Dash Chat:

```mermaid
flowchart LR

iroh

iroh-->dash-router
epidemic-broadcast-->dash-router
dash-router-->tauri-app
local-message-server-->tauri-app
message-server-->internet-message-server
message-server-->local-message-server

subgraph transports
iroh
end

subgraph routing protocols
epidemic-broadcast
end

subgraph Infrastructure
push-notifications-server
internet-message-server
dash-chat-bootstrap
end
```

- Message server: asynchronous relaying of operations for when recipients are offline.
    - Two deployment strategies:
        - Internet message servers: servers hosted on the internet and run by Dash Chat.
        - Local message servers: bundled in the Dash Chat desktop app, turns a Dash Chat instance into a message server available in the LAN. 
    - [Basic Message Server Design](https://hackmd.io/RKZc5e3ySJCcmMXV_Sjy1A)
    - [Local Mailbox Mode Design](/_pDV2AoTRPaF1R7437LOfQ)
- Push Notifications Server: semi-centralized service that stores the service account key for Firebase Cloud Messaging, and pairs of public key <> FCM tokens.
    - [Basic Push Notifications Server Design](https://hackmd.io/9T7H8fs1Q5a9zFsbvci84Q)
- Dash Router: mesh network component that allows hopping of messages between a network of intermediary peers until it gets to its recipients. 
    - See [Peer Relay Design](https://hackmd.io/Q5jYDy9qTRCapymsHPC3jw) for a WIP document on Dash Router.

### Relaying operations

See the [3 pillars of message delivery](https://hackmd.io/54Hq5l4sQyWKo0rnxElK5Q) document for a comprehensive categorization of the methods of operation relaying.

## p2panda Design

https://github.com/p2panda/p2panda

### Topics

In p2panda, peers subscribe and publish operations to and from topics. All peers subscribed to a certain topic will *eventually* receive all operations published in that topic. 

> Topic privacy is achieved via secrecy: knowing the topic ID is enough to receive all operations in that topic.

- Inbox:
    - Each user can create ephemeral inbox topics to receive incoming contact requests.
    - Each QR code has a token that's configurable, only requests that come with an alive token will be processed. This token may have a name, so that you can revoke it later.
        - 1 time.
        - Time bound.

### Spaces

> p2panda-node is not ready yet, which means that we can't use spaces as of Q1 2026. We'll wait until p2panda-node is finished to start using p2panda-spaces. Up until then, we are going to treat the spaces designed here as normal topics.

https://p2panda.org/2025/07/28/access-control.html

Spaces are topics with built-in encryption and authorization. They provide an authorization model with 4 levels: 
- `Manage`: administrator level, can add and remove members from the space.
- `Write`: can publish operations to the space.
- `Read`: can decrypt and read operations from the space.
- `Pull`: can only receive the encrypted versions of the operations.

These are the space we are going to have in Dash Chat:

- DeviceGroup: each user has a private personal space that only linked devices join, where they store personal information like settings and contacts.
- Announcements: each user has a profile space with their personal information. Contacts subscribe to it.
    - Profile.
    - Linked Devices.
- Direct chat space: each direct message chat between two peers is its own space.
   - Each member of this space is the personal space of each peer.
- Group chat space: each group chat is its own space.
    - The members of this space are the personal spaces of each of the users.

We'll be using the [message encryption scheme](https://p2panda.org/2025/02/24/group-encryption.html#p2panda-message-encryption-with-double-ratchet) for all spaces.

### Operation Flows

#### Adding a contact

Assumption: an out of band code is shared between peers that already know each other before hand, only one way. This code is shared either through a QR code or via a link/text.

See [Add Contact Link](https://hackmd.io/u2zNqTVAQ06C_ADad567SQ) for sequence diagram and a description on how add contact deep links work.


#### Linking a device

Linking a device is similar to adding a contact.

See [Add Linked Device](/6GPAvWIzT_K-xcBAqKcYtw)

#### Group Invites

Group invites: a group invite link has you enter in a group with a "waiting" notice. The member that joins sends a push notification to the existing members of the group, waking them up and helping with the join process.

Question: how do we see the profile for people that are in the same group as we are but we are not friends with?

## Unknowns

Refer to [the Dash Chat unknowns document](https://hackmd.io/CqBDV7utQrSdP2ebDe5TTg).