qTe Docs — AT Protocol Network

AT Protocol Network

Decentralized identity, storage, contacts, messaging, and file sharing over AT Protocol

Network Overview

qTe uses the AT Protocol (atproto) — the same decentralized protocol behind Bluesky — for all networking. There is no central server or database. Your data lives in your own Personal Data Server (PDS) using private custom lexicon collections that are invisible to the public Bluesky feed.

DECENTRALIZED NETWORK ARCHITECTURE Your Device qTeApp / qTeLite Local files (offsets, metadata) qte_offsets / qte_network qte_metadata / qte_thumbnails XRPC Your PDS bsky.social (or self-hosted) app.qte.storage.* (PRIVATE) app.qte.share.* (shared) Blobs up to 1MB each qte.app Hub Syndication broadcast app.qte.syndication Contact's PDS Their qTe data repo File shares, messages Key Principle: No Central Database All data is stored in YOUR PDS repo using private lexicons. Nothing appears in public Bluesky feeds. File sharing writes to recipient's repo. Syndication writes to the qte.app hub account.

AT Protocol Client

ATProtocolClient handles all XRPC communication with the PDS. It manages authentication sessions, CRUD operations on records, and blob uploads.

Authentication Flow

  1. User provides handle (e.g., user.bsky.social) and app password
  2. Client calls com.atproto.server.createSession on the PDS
  3. PDS returns ATSession with access JWT, refresh JWT, DID, and handle
  4. All subsequent requests use the access JWT for authorization
  5. Token refresh happens automatically when the access JWT expires

Key Properties

PropertyDescription
IsAuthenticatedWhether a valid session exists
DidThe user's Decentralized Identifier
HandleThe user's AT Protocol handle
PdsHostPDS server URL (default: https://bsky.social)

Custom Lexicons

qTe defines private custom lexicon collections for organized data storage. These follow AT Protocol naming conventions but are not indexed by Bluesky's feed generators.

Storage Collections (Private)

LexiconPurpose
app.qte.storage.offsetEncoded offset data (binary blobs)
app.qte.storage.metadataSymphMetadata JSON records
app.qte.storage.blockchainBlockchain entries
app.qte.storage.binaryblobLarge binary data chunks
app.qte.storage.contactsContact/address book data
app.qte.storage.collectionsCollection definitions
app.qte.storage.messagesConversation messages
app.qte.storage.meme.thumbnailMeme thumbnails (64×64 JPEG blobs)
app.qte.storage.meme.imageCompressed meme images (640×640 max)

Network Collections (Shared)

LexiconPurpose
app.qte.share.fileFile share records sent to contacts
app.qte.share.passwordPassword shares for protected files
app.qte.message.directDirect messages between contacts
app.qte.contactContact records
app.qte.contact.requestContact request invitations
app.qte.collectionPublic collection records (lexicon)
app.qte.syndicationSyndication feed entries

AtProtoStorageManager

AtProtoStorageManager is a singleton that manages AT Protocol remote storage for all qTe data. It handles uploading offsets, metadata, and binary data as blobs, and downloading them during sync.

Blob limit: AT Protocol allows blobs up to 1MB. qTe uses 900KB as a safe limit. Files larger than 900KB are split into multiple blob records.

Key Operations

  • Upload offset: Reads .qTe file, uploads as blob to app.qte.storage.offset
  • Upload metadata: Serializes SymphMetadata to JSON, stores in app.qte.storage.metadata
  • Download offset: Retrieves blob from PDS, writes to local qte_offsets folder
  • Record cache: Maintains in-memory cache of stored record info to avoid redundant uploads

QteNetworkManager

QteNetworkManager is the high-level singleton that orchestrates all network operations: connection management, contact management, file sharing, messaging, and syndication.

QteNetworkManager RESPONSIBILITIES QteNetwork Manager Singleton Connections Contacts File Sharing Messaging Syndication Auto-Import

Events

EventRaised When
FeedUpdatedSyndication feed is refreshed
MessageReceivedNew direct message arrives
FileShareReceivedA contact shares a file
ConnectionStatusChangedConnect/disconnect state changes

Contacts & Address Book

Contacts are managed by the AddressBook singleton and stored in the qte_network folder as JSON. Each contact has a DID, handle, display name, and trust level.

Contact Workflow

  1. Send request: Write a app.qte.contact.request record to the contact's repo
  2. Accept request: Recipient writes a app.qte.contact record back
  3. Sync contacts: Pull contacts from AT Proto, merge with local address book
  4. File sharing: Only allowed between accepted contacts

Messaging & Conversations

ConversationManager handles all messaging. Messages are stored locally in the qte_conversations folder and synced to AT Proto via app.qte.message.direct.

Message Types

  • Text messages: Plain text direct messages between contacts
  • File share messages: Includes a Symph reference to shared encoded data
  • Password share messages: Securely shares a decoding password for protected files

Sync Workflow

SYNC WORKFLOW (PULL-ONLY DURING REGULAR SYNC) Pull Sync (Regular) 1. List remote records in app.qte.storage.* 2. Download missing offsets + metadata 3. Download new messages + file shares 4. Never modify remote records Push (Encode/Explicit Only) 1. Initial encoding → upload offset + metadata 2. Explicit "sync from local" action 3. Never push during pull sync 4. Never remove existing remote records ⚠ Push to AT Proto ONLY during initial encoding or explicit "sync from local" Never push during regular pull sync. Never modify or remove existing remote records. Auto-import runs on a configurable timer (default 60s) — pull-only
Syncing Rule: Push metadata to AT Proto should ONLY happen during initial encoding or explicit "sync from local" action. Never push during regular pull sync. Never modify or remove existing remote records during sync.