# ok/mirall architecture

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

- Interactive diagram: https://gitdiagram.com/ok/mirall
- Repository: https://github.com/ok/mirall

## Overview

Mirall is a local-first Electron desktop client for private, peer-to-peer file sharing and resumable transfers. A user creates or joins a cryptographically protected space, approves members, shares files or folders, and chooses what to download or mirror. The renderer presents spaces and transfer state; Electron hosts a Bare worker that owns the data layer and exposes requests to the UI. The README documents the peer network and security model; sampled source clarifies selected IPC and storage paths, but most domain implementations were not sampled, so uncertain links are omitted.

Main entry points: [`src/worker/main.js`](https://github.com/ok/mirall/blob/main/src/worker/main.js) (Worker entry), [`src/shared/network`](https://github.com/ok/mirall/tree/main/src/shared/network) (Encrypted peer network), [`src/shared/core/ipc.js`](https://github.com/ok/mirall/blob/main/src/shared/core/ipc.js) (IPC handlers), [`src/shared/spaces/space.js`](https://github.com/ok/mirall/blob/main/src/shared/spaces/space.js) (Spaces and membership)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Desktop interface"]
  node_renderer["Screens and navigation"]
  node_queries["Query cache<br/>[query-store.js]"]
  node_rendereripc["Renderer IPC<br/>[ipc.ts]"]
end

subgraph group_host["Electron host"]
  node_main["App lifecycle<br/>[main.js]"]
  node_workerhost["Worker host<br/>[worker-host.js]"]
  node_worker["Worker entry<br/>[main.js]"]
  node_ipc["IPC handlers<br/>[ipc.js]"]
  node_contracts["Request contracts<br/>[requests.js]"]
  node_storageipc["Storage requests<br/>[storage.js]"]
end

subgraph group_data["Spaces and identity"]
  node_boot["Worker bootstrap<br/>[boot.js]"]
  node_spaces[("Spaces and membership<br/>[space.js]")]
  node_profile[("Identity and profile<br/>[profile.js]")]
  node_storage["Storage accounting<br/>[storage.js]"]
end

subgraph group_sharing["Sharing and transfers"]
  node_folderpub["Folder publishing<br/>[publish-service.js]"]
  node_catalog[("Share catalog<br/>[shares.js]")]
  node_transfers["Content transfers"]
  node_mounts["Folder mounts"]
end

subgraph group_network["Peer network"]
  node_p2p["Encrypted peer network"]
  node_updates["P2P updates<br/>[updater.js]"]
end

node_user(("User"))

node_user -->|"uses"| node_renderer
node_renderer -->|"queries"| node_queries
node_queries -->|"fetches through"| node_rendereripc
node_rendereripc -.->|"requests"| node_ipc
node_main -->|"starts"| node_workerhost
node_workerhost -->|"hosts"| node_worker
node_worker -->|"bootstraps"| node_boot
node_worker -->|"creates"| node_ipc
node_ipc -->|"validates requests"| node_contracts
node_worker -->|"registers"| node_storageipc
node_storageipc -->|"reads"| node_storage
node_storage -->|"lists spaces"| node_spaces
node_user -->|"creates or joins"| node_spaces
node_spaces -->|"grants content key"| node_profile
node_user -->|"shares folders"| node_folderpub
node_folderpub -->|"writes metadata"| node_catalog
node_user -->|"requests downloads"| node_transfers
node_transfers -->|"fetches peer chunks"| node_p2p
node_p2p -->|"exchanges encrypted metadata"| node_catalog
node_user -->|"mirrors folders"| node_mounts
node_p2p -->|"distributes releases"| node_updates

click node_renderer "https://github.com/ok/mirall/tree/main/src/renderer/screens"
click node_queries "https://github.com/ok/mirall/blob/main/src/renderer/store/query-store.js"
click node_rendereripc "https://github.com/ok/mirall/blob/main/src/renderer/ipc/ipc.ts"
click node_main "https://github.com/ok/mirall/blob/main/src/main/main.js"
click node_workerhost "https://github.com/ok/mirall/blob/main/src/main/worker-host.js"
click node_worker "https://github.com/ok/mirall/blob/main/src/worker/main.js"
click node_ipc "https://github.com/ok/mirall/blob/main/src/shared/core/ipc.js"
click node_contracts "https://github.com/ok/mirall/blob/main/src/shared/contract/requests.js"
click node_boot "https://github.com/ok/mirall/blob/main/src/worker/boot.js"
click node_spaces "https://github.com/ok/mirall/blob/main/src/shared/spaces/space.js"
click node_profile "https://github.com/ok/mirall/blob/main/src/shared/spaces/profile.js"
click node_folderpub "https://github.com/ok/mirall/blob/main/src/shared/folders/publish-service.js"
click node_catalog "https://github.com/ok/mirall/blob/main/src/shared/shares/shares.js"
click node_transfers "https://github.com/ok/mirall/blob/main/src/shared/transfer/overlay/engine/transfer/transfer-manager.js"
click node_mounts "https://github.com/ok/mirall/tree/main/src/shared/folders"
click node_storageipc "https://github.com/ok/mirall/blob/main/src/worker/ipc/storage.js"
click node_storage "https://github.com/ok/mirall/blob/main/src/shared/storage/storage.js"
click node_p2p "https://github.com/ok/mirall/tree/main/src/shared/network"
click node_updates "https://github.com/ok/mirall/blob/main/src/main/updater.js"

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_renderer,node_queries,node_rendereripc,node_user toneBlue
class node_main,node_workerhost,node_worker,node_ipc,node_contracts,node_storageipc toneAmber
class node_boot,node_spaces,node_profile,node_storage toneMint
class node_folderpub,node_catalog,node_transfers,node_mounts toneRose
class node_p2p,node_updates toneIndigo
```

## Components

### Desktop interface

- [Screens and navigation](https://github.com/ok/mirall/tree/main/src/renderer/screens): `src/renderer/screens`
- [Query cache](https://github.com/ok/mirall/blob/main/src/renderer/store/query-store.js): `src/renderer/store/query-store.js`
- [Renderer IPC](https://github.com/ok/mirall/blob/main/src/renderer/ipc/ipc.ts): `src/renderer/ipc/ipc.ts`

### Electron host

- [App lifecycle](https://github.com/ok/mirall/blob/main/src/main/main.js): `src/main/main.js`
- [Worker host](https://github.com/ok/mirall/blob/main/src/main/worker-host.js): `src/main/worker-host.js`
- [Worker entry](https://github.com/ok/mirall/blob/main/src/worker/main.js): `src/worker/main.js`
- [IPC handlers](https://github.com/ok/mirall/blob/main/src/shared/core/ipc.js): `src/shared/core/ipc.js`
- [Request contracts](https://github.com/ok/mirall/blob/main/src/shared/contract/requests.js): `src/shared/contract/requests.js`
- [Storage requests](https://github.com/ok/mirall/blob/main/src/worker/ipc/storage.js): `src/worker/ipc/storage.js`

### Spaces and identity

- [Worker bootstrap](https://github.com/ok/mirall/blob/main/src/worker/boot.js): `src/worker/boot.js`
- [Spaces and membership](https://github.com/ok/mirall/blob/main/src/shared/spaces/space.js): `src/shared/spaces/space.js`
- [Identity and profile](https://github.com/ok/mirall/blob/main/src/shared/spaces/profile.js): `src/shared/spaces/profile.js`
- [Storage accounting](https://github.com/ok/mirall/blob/main/src/shared/storage/storage.js): `src/shared/storage/storage.js`

### Sharing and transfers

- [Folder publishing](https://github.com/ok/mirall/blob/main/src/shared/folders/publish-service.js): `src/shared/folders/publish-service.js`
- [Share catalog](https://github.com/ok/mirall/blob/main/src/shared/shares/shares.js): `src/shared/shares/shares.js`
- [Content transfers](https://github.com/ok/mirall/blob/main/src/shared/transfer/overlay/engine/transfer/transfer-manager.js): `src/shared/transfer/overlay/engine/transfer/transfer-manager.js`
- [Folder mounts](https://github.com/ok/mirall/tree/main/src/shared/folders): `src/shared/folders`

### Peer network

- [Encrypted peer network](https://github.com/ok/mirall/tree/main/src/shared/network): `src/shared/network`
- [P2P updates](https://github.com/ok/mirall/blob/main/src/main/updater.js): `src/main/updater.js`

### Other components

- **User**

## Connections

- User → Screens and navigation: uses (evidence: `README.md`)
- Screens and navigation → Query cache: queries
- Query cache → Renderer IPC: fetches through (evidence: `src/renderer/store/query-store.js`)
- Renderer IPC → IPC handlers: requests
- App lifecycle → Worker host: starts (evidence: `src/main/main.js`)
- Worker host → Worker entry: hosts (evidence: `README.md`)
- Worker entry → Worker bootstrap: bootstraps (evidence: `src/worker/main.js`)
- Worker entry → IPC handlers: creates (evidence: `src/worker/main.js`)
- IPC handlers → Request contracts: validates requests (evidence: `src/shared/core/ipc.js`)
- Worker entry → Storage requests: registers (evidence: `src/worker/main.js`)
- Storage requests → Storage accounting: reads (evidence: `src/worker/ipc/storage.js`)
- Storage accounting → Spaces and membership: lists spaces (evidence: `src/shared/storage/storage.js`)
- User → Spaces and membership: creates or joins (evidence: `README.md`)
- Spaces and membership → Identity and profile: grants content key (evidence: `README.md`)
- User → Folder publishing: shares folders (evidence: `README.md`)
- Folder publishing → Share catalog: writes metadata (evidence: `src/shared/folders/publish-service.js`)
- User → Content transfers: requests downloads (evidence: `README.md`)
- Content transfers → Encrypted peer network: fetches peer chunks (evidence: `README.md`)
- Encrypted peer network → Share catalog: exchanges encrypted metadata (evidence: `README.md`)
- User → Folder mounts: mirrors folders (evidence: `README.md`)
- Encrypted peer network → P2P updates: distributes releases (evidence: `README.md`)
