How Glitr is assembled
Glitr is a messenger whose “cloud” is a git repository you own. This page is the product map: which pieces talk to which, and what each one is for.
It is not a protocol specification. Glitr is research and development — subject to change. The Signal handshake library is open source; the rest of the messenger is not. Treat this as a picture of how the shipped stack fits together, not a claim of wire compatibility with the Signal app.
For the user story of mailboxes, ticks, and live links, start at Git as your mailbox. For what a host can see, see encryption visibility.
The pieces
These are the parts of the product path. Signal, ML-KEM, and PQXDH appear as libraries inside the recipient cascade, not as separate apps you run.
| Piece | What it does |
|---|---|
| whatsup-ui | The chat chrome: lists, threads, ticks. A related demo shell (whatsup) showcases that UI with mock data. The mailbox product is not that demo. |
| api-core | The in-process messaging API: connect, profile, contacts, send, poll, seal/unseal. It orchestrates storage and crypto. |
| db-core | A small GraphQL store over files. Documents and collections live in your git workdir. Types marked for sealing are password-wrapped on flush. |
| git-core | Git for that workdir. On a desktop it uses a native git library. In the browser it uses isomorphic-git and origin-private storage. |
| crypto-cascade | Encrypt to a person: AES-256-GCM, then RSA-OAEP-4096 hybrid, then Signal, then ML-KEM-1024, then PQXDH. |
| crypto-core | The primitives: AES, RSA, Argon2id password envelopes, and a generic cascade manager. Password sealing for your files lives here. It is not part of the recipient stack. |
| webrtc-core | The live path: git-brokered signaling, a data channel, chat frames that use the same cascade, and a fallback to git when the channel drops. |
| glitr-website | This documentation site. |
| glitr-domain | Hosting for glitr.io. It is not a chat server. |
The UI talks to api-core. api-core writes records through db-core, encrypts recipient payloads with crypto-cascade, and uses webrtc-core when both people are online. glitr-website and glitr-domain only publish this site.
Git mailbox: send and poll
You never write into someone else’s repository. You write outbound on yours. They keep a fetch-only clone of yours and ingest what is addressed to them. The product story is in Git as your mailbox; this is the same flow named by pieces.
Send also keeps a sent copy on your side (sealed at rest). Their poll writes inbox (also sealed). If they mark the message read, a read receipt appears on their repo; your later poll can drop the outbound row. Delivery ticks and latency live on Why not always instant.
Live path
Git is a mailbox, not an instant messenger. When both of you are here, Glitr publishes a signaling row on each repo (offer or answer, already cascaded to the other person), completes a WebRTC handshake, and carries new chat bodies on the data channel — the same cascade, not plaintext over DTLS.
Local sent and inbox still update so the thread does not forget what you just said. If the channel dies, the next send is git again. Details: Direct live links. Git and live share one protocol session per contact so the ratchet does not fork — see Data structures.
Two crypto jobs
These must stay separate.
| Recipient cascade | Password at rest | |
|---|---|---|
| Job | Encrypt a payload to a contact | Seal your documents so a host is not reading the file |
| Unlock | Their public bundles and the shared session | The encryption password you type at connect |
| Where | Outbound, signaling, live chat bodies | Contacts, inbox, sent, profile secrets, protocol sessions |
Stacking Signal plus a standalone ML-KEM wrap plus PQXDH is defense-in-depth, not a spec-recommended profile. PQXDH already includes X25519, ML-KEM-1024, and a ratchet. The extra layers are independent wraps on the same payload. Full wording: Signal and post-quantum. The encryption try path can toggle a password layer for teaching; the product recipient path never does.
Where it runs
- Cores are Rust libraries. They run in a desktop process and, compiled to WebAssembly, in the browser.
- The browser app uses those WASM builds plus origin-private storage for the git workdir.
- Try pages under Try Glitr point at Dioxus galleries — interactive demos of messaging, live, storage, and crypto. They are how you press the buttons; they are not a second messenger.
- glitr.io is this static documentation site. It does not hold mailboxes.
Next: Data structures — the records in a mailbox, what is public vs sealed, and what sits inside a ciphertext field.