Architecture
What it is not
On this page
Pug Network is deliberately not a general-purpose chat platform. Each of the items on this page has been considered, and each has been left out for a reason. Requests to add them should be declined unless the philosophy in What is Pug Network? is being explicitly revisited.
Not in the product
Persistent message history
Stored history is something to leak, subpoena, exfiltrate, or back up accidentally. Pug Network exists for conversations where the absence of a record is the point. If you need a record, take notes elsewhere.
User accounts, OAuth, SSO
Accounts mean passwords, password resets, session tokens, and a directory of users — all of which is exactly the kind of long-lived identity surface Pug Network is built to avoid producing. The product's identity model is "anyone with the URL can join", and the URL itself carries the credentials.
Server-side search, indexing, or analytics on message contents
The server cannot read message contents — they are encrypted with a key it has never had. Even if it could, indexing them would create exactly the persistent record we are committed not to keep. Same logic applies to read receipts, typing indicators, and any feature that leaks per-message metadata to the server.
Federation, public room directories, room discovery
Pug Network rooms are discovered out-of-band, by sharing a URL with the people you want in the conversation. There is no global directory and no federation protocol — those would create cross-server metadata and a discovery surface that the trust model would have to defend.
File transfer or media storage on the server
File uploads are a major attack surface (parsers, virus scanners, storage backends, sharing URLs that outlive the room) and require persistent storage to be useful. Pug Network deliberately does not ship them. If you need to share a file, send a link to a file hosted somewhere designed for that.
Mobile push notifications
Push notifications require a push service (APNS, FCM) which means a per-device identifier registered on a third-party provider that knows which device is in which room and when. That is exactly the kind of cross-conversation metadata Pug Network is structured to avoid. The tradeoff is that you must have the room open to see new messages.
Voice, video, screen-sharing
Real-time media requires WebRTC signalling and (typically) TURN relays, which add a second protocol stack and a second pile of operational state. Pug Network is built to be small enough to audit in an afternoon — adding WebRTC would make that no longer true.
Invariants this page protects
The exclusions above exist to keep these invariants true. They MUST hold at all times. A change that violates one of them is a bug, regardless of how convenient the change is.
- A room MUST NOT outlive its TTL.
- Capacity MUST be enforced at join time, not after broadcast.
- Cleanup MUST remove timers, members, and lookup entries together. Partial cleanup is a leak.
- The server MUST NOT store, log, or otherwise persist message payloads, room secrets, or encryption keys.
- The server MUST NOT log IP addresses by default.
- All access checks (room secret, creator identity for purge) MUST use constant-time comparison.
- Realtime handlers MUST NOT have side effects outside the room/domain state.
- New features MUST NOT introduce persistent storage. If a feature genuinely requires it, that is a product-level decision and must be raised explicitly.
- The Go reference implementation MUST remain free of third-party dependencies.
If you want one of these features anyway
Pick the right tool for the job. How it compares is an honest map. Most of the time, "Pug Network plus the right tool for the long-lived part of the conversation" is a better fit than "Pug Network with feature X bolted on".