Core Concepts

User Identity

Upstra's Development Kits do not store or manage any user data. This means that you do not have to import or migrate existing user profiles into Upstra's system, user management should be handled by your application code. Instead, every user is simply represented by an unique userID, which can be any string that uniquely identifies the user and is immutable throughout its lifetime.

A database primary key would make an ideal userID. Conversely, something like username or emails is not recommended as those values may change overtime.

If you wish to assign additional permissions for a user, for example moderation privileges or different sending limits, you can provide an array of roles to assign to this user. Roles are defined in the admin panel and can be tied to an unlimited number of users. Upstra does not store or manage any user data. This means that you do not have to import or migrate existing users into Upstra's system. It also means that Upstra cannot provide user management functionalities like provide lists of users, or limit actions of certain users (e.g. user permissions). Instead, these functionalities should be handled by the rest of your app and your server.

Messages and Channels

The messaging functionality of Upstra is simple, there are 2 main concepts you need to know: messages and channels. A channel represents a chat between a group of users. A channel supports up to 300,000 members and can contain an unlimited number of messages. Any message exchanged in the channels will be pushed to all other members of the channel in real-time.

Channels and Channel Memberships

When a user joins a channel, they are able to observe and chat with other users in that channel. They are also automatically considered a member of that channel. The SDK provides the ability to view which users are currently in the channel as well as invite other users to join the channel.

State Management

Upstra is designed to handle all state related to messaging, including network connection states. Ideally, you should be able to map the state exposed by Upstra directly to your application UI. You would only need to send the right actions to Upstra, and any update to the state will be emitted to you via LiveObject updates.

All methods in Upstra are designed to return synchronously, Upstra will automatically establish a connection to the server when needed and send the request to the server. If the server is not available, Upstra will queue up any requests and will automatically try to connect to the server with exponential backoff.

In order to provide the best user experience, Upstra will automatically persist its state to the user device's disk. All queries that return a LiveObject will use a cache then network strategy in order to ensure that relevant data is always presented to the user.

Live Objects

All queries in Upstra's Development Kits synchronously return LiveObjects. LiveObject represents a query that is always updated in real-time, informing you whenever the data in the query changes. It encapsulates all logic around using local cache, querying from the network, and receiving live events from the network into one simple interface.