functional_technical_specification
revision 1.1
Chirr is a chat based collaboration tool. The functionality of the chat interface should be considered to be positioned somewhere between IRC and Slack.
In this functional definition we will describe the application from the point of view of the user Angelina.
Angelina has never used the application before. When she enters the application for the first time, of course she cannot login so she must register a user account
For basic user registration Angelina needs to enter a "nick" (user name), a photo and her email address and a password. She will receive a confirmation email which contains a link which will lead her directly to a simplified login screen without the register option (not shown) and the pre-filled user name. Angelina only has to confirm her password and after successful login she enters her "home" screen.
When Angelina enters the application for the first time she can see her "home screen". The screen contains a search bar which allows Angelina to search for "streams" and content in all public Streams.
Definition: a "stream" is a grouping of related topics or "flows". A "flow" contains the chat-based communication between participants. Each stream includes a default flow.
Search results will be displayed under the search bar in the center of the screen. Angelina can freely enter any stream and flow or download any file to which she has access.
After Angelina has been granted access to private streams, those will become visible to her as well.
The first time Angelina enters the home screen there are no streams showing in the result box. It should display a text like "Search for or create a new stream". At return visits the center results panel will by default show recently accessed public streams and all private streams to which Angelina has been granted access.
Angelina can access her configuration settings by clicking on the "gear" on the top right of the screen. This menu also contains the function to log out of the application.
Angelina can also create new streams herself by clicking on the button "create & open stream".
After creation she will become owner of that stream. A stream is by default always "public" but can optionally be made into a "private" stream. Angelina can grant access to other users in case of a private stream.
Once Angelina has entered a stream she can see the stream chat screen which consist of two columns. On the left she can see a "chat flow" column and on the right the "chat" column. The width of both columns can be changed by dragging the separation bar between the two columns. The chat flow column can be hidden or shown by clicking on the typical "double arrow" hide and show buttons.
The chat flows serve as a kind of sub-streams which allow particular topics to be discussed in isolation.
Definition: in the flow column on top there is always a "main" or default flow. When entering a stream this is the flow which will be shown. Under the main flow the remainder of the flows are stacked, ordered top-down- with the most recently active on top. Flows are pushed down in the stack when older. Flows can be created and renamed by any user. A flow can never be closed or deleted but they are hidden when not active for n days. Flows may display the number of unread messages (alternatively; new messages from certain time) after the flow name.
Angelina can see the most recent chats in the chat column when she enters the stream screen. The chat column will show the chats in the "main" flow. The chats are displayed sequentially with the most recent down. Text by Angelina will appear in the same column as the chats of the other users. The chat history must be scrollable upward like in Whatsapp. "Events" like flow and stream name changes need to be broadcasts in the relevant flow in case of the former and main flow in case of the latter. These events appear like chat entries and should be researchable.
The "gear" configuration menu now not only shows the possibility to change Angelina´s setting, but when the stream chat screen is shown that menu is extended with options to:
- rename or delete the stream
- add or remove users from the stream.
Angelina can add text by typing text in the text box below in the chat column. Text can be modified before being send to the stream. The "enter" key does not send the text but "shift-enter" or clicking on the "send" button on the right.
Files can be send, added to, the chat with the "+" floating button on the right (under the send button). Once it is uploaded, the file is being shown as an file icon. The file can be downloaded by clicking on the link.
Hyper-links pasted in the chat text should be recognized and - if possible - "expanded" and a preview of the referred content page should be shown in-line (not shown).
All new chat entries to a flow, chat text, hyper links, as well as file icons, are synced to all participating, on-line, members in real-time.
Files as well as hyper links embedded content should have an option to be "pinned" to the area in between the chat text box and the chat content (not shown). This allows for "shortcuts" to the files and hyper links to be always in view. The shortcuts can be added and removed by all members. The original file or hyper links are never affected. This allows the chat flow to be used as a kind of message board or file directory where essential content which is related to the flow can be aggregated.
Angelina can search through the group history with the "search" bar on the top right. All history of the group is searched and the results are shown in the order of current flow, then current group and ultimately the remaining public groups and all groups to which Angelina has been granted access. Per sub-category the results are ordered most recent first. If Angelina clicks on a result she will navigate directly to the respective group and/flow with the chat column showing the relevant content.
All content within Chirr should be content addressable. That means that all individual chat text entries, files, hyper links etc can be copied and accessed through an hyper link. If users are not authenticated than they should be taken to a simplified login screen (without option to register; not shown) and after successful authentication, directly taken to the content referred to in the URL. All content should be book-markable as well. This means that the application URL in the browser should change with each navigation action or click on content.
The back button should take the user back in the navigation history. It does not have to function as an "undo" button.
Chirr should work on modern "ever-green" browsers (IE10 + including). That means that it can make full use of HTML5.
Real time sending of chat text and chat window synchronization should be done by sending items over an open websocket window. As a fall-back option, this functionality should be replaced by ReST calls.
Content - chat text, groups and flow lists etc - should be cached in the local database. This information should be shown while newer information is in the process of being obtained from the server. This will substantially improve the perceived performance of the application
- login / register
- text chat - multiple streams (minimally: public / without flows)
- multiple flows per stream
- stream / flow / content search
- real time update over web socket
- file upload
- stream / flow renaming
- flow extras: unread messages / reordering etc
- local data caching
- private groups with user management
- event broadcasting
- pinnable content
- hyper links embedded content
- addressable content
- Must haves
- Should haves (partial)
- Should haves (partial)
- Could haves
- cleanup
- Nice to haves
Note that complex types are defined as Tagged Unions for documentation´s sake https://en.wikipedia.org/wiki/Tagged_union but this does not necessarily imply that it absolutely described the required data type "Either" should represent mutually exclusive ("either" means "one or the other") Success and Failure "options"
Note that the use of web socket implies a message driven protocol rather than a "procedure based" protocol. So "IN" represents "incoming messages" and "OUT" represents "outgoing messages", respectively.
connect(token) - OUT - connect with server sending token obtained with ReST login
disconnect() - OUT - explicit termination of connection. Equivalent to logout
send(flowId, text) - OUT - sending chat text to flow
error - IN - error event
updateFlow - IN - (flowid, List (item) - reception of new items for a particular flow
updateFlowList - IN - (streamId, List (item) - reception of updates to flow list
login(userid, password) -> Either (Error, token)
register(username, registerData) -> Either (Error, OK)
getStreams() -> List (stream)
searchStreams(searchTerm) -> List (result)
selectStream(streamId) -> Either (Error , (stream , List (items))) - get stream information with items from [default] flow OR Error
getFlows(streamId) -> Either (Error, List (flow))
selectFlow(flowId) -> Either (Error, (flow , List (item))) - get flow information with items or Error
send(flowId , text) -> Either (Error, OK) - sending chat text to flow
sendFile(flowId , file binary) -> Either (Error, OK) - Not ReST. Represents HTTP multipart/form-data POST
updateTopicFrom(flowId , lastItemid) -> List (item)
createStream(name) -> Either (Error, OK)
deleteStream(streamId) -> Either (Error, OK)
renameStream(streamId, newname) -> Either (Error, OK)
createFlow(streamId , name) -> Either (Error, OK)
renameFlowc(flowId, newnname) -> Either (Error, OK)