braidchat / braid

Braid is a team-chat app with a novel UI that leads to better conversations.

Braid

Braid is an experimental team chat application with a novel UI: instead of chatrooms, it's based on many short conversations. You can think of Braid as an email/mailing-list/web-forum/chatroom hybrid, but without the constant interruptions and FOMO of Slack. It's particularly good for remote-first companies, developer teams and online communities. Braid is also open-source, so you can hack on it and host your own version.

You can read more about Braid and then give Braid a try.

If you'd like to use Braid with your team, but it's missing a certain something, let us know and we'll try to make it happen. If you'd like to contribute, even if you're not experienced with Clojure(script), we're available to pair remotely and help you get your first PR started.

• Raf ([email protected]) & James ([email protected])

Braid's not as polished as Slack yet, but it's got most of the features you'd expect from other chat clients:

• public and private conversations
• archives + search
• file sharing
• notifications
• email digests
• code formatting and emoji
• integrations support

It's been our daily driver for over a year, but there are still some rough edges and things we want to improve; notably:

• better mobile apps
• better 1:1 integrations
• polishing non-critical UI (ex. settings)
• moderation tools
• and more...

Contributing

1. If you like the concept, please let us know!

   Your feedback is the fuel that pushes us too keep working on Braid. Say hello on braid@braid, and let us know what you think.

2. Try Braid out on your team/group and give us feedback.

   You can set up a free team on braid.chat and message us on braid@braid to give feedback.

3. If you want to code...

   Check out the Getting Started instructions below. @rafd and @jamesnvc are available to pair remotely if you'd like help getting started. Message us on braid@braid and we can help match you with a good task and debug any issues you run into.

There's also opportunities to help with triaging issues, writing docs and other non-"dev" work.

Bugs and feature requests are tracked via Github Issues

Thank you to all of our contributors!

Getting Started

To get Braid working locally, see: Developing Braid

If you want to deploy it in production, see Deploying Braid

If you just want to use Braid, but not set it up yourself, you can get a hosted account at: https://www.braidchat.com

Repositories

• The Primary Repo

  https://github.com/braidchat/braid

  API server, desktop web client, docs

• Native Desktop Client

  https://github.com/braidchat/electron

  An Electron app that wraps the desktop web client

• Native Mobile Client

  https://github.com/braidchat/cordova

  A Cordova app that wraps the mobile web client

• Other Repos

  https://github.com/braidchat

  Other repos, including sample bots, marketing materials, and miscellany.

License

Braid may be freely used under the AGPL license.

As per the AGPL, you can use Braid for personal or commercial purposes for free, but, you must publically release any modifications to the software (under the same license). If you need to make private modifications you can purchase a commercial license by contacting [email protected]

braid's Issues

Add a user administration page (for admins only)

A task for new Braid contributors.

Goal:
To create a new page, for group admins, to easily manage the existing users in a group.
The page should list of users in a table (with their name, last-sign in) and buttons to remove user or make the user an admin. Later, add the ability to bulk invite users.

Feel free to make a PR for partial completion of this issue (for example, just listing name and "make user an admin" button; we can then make a new task for the remaining functionality).

Notes:

• This should be implemented a separate module
• braid.stars is a good reference for how to do modules
• braid.core.api already has a number of hooks that may be useful, (ex. "creating a group page"), but a few new ones may need to be added (ex. "adding item to admin menu")
• the list of users should already be available in the app state
• the user hover-card already includes a 'make an admin' button

Allow users to "boomerang" a thread to show up in their inbox again after some time

A task for new Braid contributors.

Goal:
Add the "boomerang" feature that's common in various email clients, where you can click a button to hide an email from your inbox and have it re-show-up after some time. In Braid, this would involve boomeranging a thread instead. (If there's a better term than boomerang for it, by all means, change the terminology).
You can show the option to boomerang in the thread menu (which shows on-hover of the close button). For now, a preset boomerang time (of, let's say, 48 hours) is sufficient.

Notes:

• This should be implemented as a new module
• braid.stars is a good reference for how to write modules
• you will likely need to create a job to check for threads to re-open; braid.core.api/register-daily-job! exists, but you may need to add an hourly version
• braid.core.api/register-thread-control! can be used to add a button to the thread menu

increase default font size

Display embeds for youtube links

A task for new Braid contributors.

Goal:
Detect youtube links in messages and show an embedded video below the message.

Notes:

• this should be implemented as a new module
• the braid.embeds module already provides functionality for registering 'embeds' based on message content. See braid.embeds.api.
• see braid.video-embeds for an example of a similar existing module (which detects links to movie files directly)

Show how long the user has been a member on user hover cards

A task for new Braid contributors.

Goal:
On user-hover-cards (cards that show up when hovering over a user mention), show how long the user has been a member.

Notes:

• the server will need to include this info in the exist user data that it sends to the client (we'll leave it to you to figure where that is)
• we currently don't explicitly store a timestamp for when a user joins a group, but, it can be figured out by getting the :db/txInstant of when the :group/user datom was created. Some example code:

(d/q
 '[:find [?inst ...]
 :in $ ?user-id ?group-id
 :where
 [?u :user/id ?user-id]
 [?g :group/id ?group-id]
 [?g :group/user ?t ?tx false]
 [?tx :db/txInstant ?inst]]
 (d/history (db/db))
 some-user-id
 some-group-id)

Embed map view for map links

A task for new Braid contributors.

Goal:
Detect google maps links in messages and show a map below the message.

Notes:

• this should be implemented as a new module
• the braid.embeds module already provides functionality for registering 'embeds' based on message content. See braid.embeds.api.
• see braid.video-embeds for an example of a similar existing module
• either use a static image or a secure iframe for embedding
  https://developers.google.com/maps/documentation/embed/guide
• probably need to make user of braid.core.api/register-config-var!

investigate high CPU usage when holding down key in new message

Latest changes to the Braid system start appear to cause issues for Emacs/Cider dev environment.

With the latest changes to the Braid system start, I can no longer reliably start it within Emacs/Cider.

Firstly, figwheel fails to compile cljs:

Failed to compile build :desktop-dev from ["src/braid" "src/retouch"] in 2.911 seconds.
----  Could not Analyze  target/classes/braid/core/modules_dummy.cljs  ----

  Could not locate braid/core/module_helpers__init.class or braid/core/module_helpers.clj on classpath. Please check that namespaces with dashes use underscores in the Clojure file name.

----  Analysis Error : Please see target/classes/braid/core/modules_dummy.cljs  ----

I'm unable to find that file or the gen-module-requires macro anywhere in the project.

Could it be that the module_helpers.cljs was forgotten on master?

Secondly, the change has an unfortunate effect of working against how Cider like to have the repls started. When I run cider-jack-in-clojurescript it starts lein repl and lein figwheel separately with piggieback and other dependencies injected that are compatible with other nrepl middleware(nrepl-refactor for example).

Cider provides cider-clojurescript-connect function, but I would need to add the right dependencies in the project itself.

Was it done to simplify the setup process in IDEs like Cursive? I understand that not everyone is using Emacs; the docs here https://github.com/braidchat/braid/blob/master/docs/dev/getting-up-and-running-in-development.md do need to be updated though(the Emacs portion).

increase max-display-length of tags

Search, scrolled, lost new conversation box

I searched for a string with a lot of results, scrolled far to the right, then when I closed the search, I lost the new conversation box.

Add a PM button to user hover cards

A task for new Braid contributors.

Goal:
Show a "PM" (private message) button on user hover cards. Clicking on the button should create a new private thread with that user.

Notes:

• braid.core.client.ui.views.user-hover-card is the namespace where you should add the button
• :new-message is the event to dispatch
• you can reference braid.core.client.ui.views.user-hover-card to see how :new-message is dispatched

End-to-end Tests

We have some unit tests for backend-code, but end-to-end tests would be valuable to help prevent future regressions.

There is a lot of implemented-but-untested functionality in Braid now, so having decent coverage will require a lot of work. Marking this as an 'ongoing-effort'.

With the effort to reorganize the codebase around modules , we don't have to test what is currently 'core', and instead, provide a way for modules to include end-to-end tests and have at least one basic happy-path end-to-end test for each module.

Progress:

• support end-to-end test in modules

Module Progress:

• quests
• emoji

Transition to Modules

There is an effort underway to significantly refactor the code-base to be organized as "modules".

Background

Most of Braid's code is organized around technical layers ("views", "client-side-state", "websocket-message-handlers", "db", etc.). Adding a feature (such as, say, "starring a thread") involves changes throughout the entire stack, and the code being peppered throughout multiple files:

                      server            client

             http      db      email      ui     ....
          |        |        |        |        |
emoji     |   e    |   m    |   o    |   ji   |
          |        |        |        |        |
          |        |        |        |        |
          |        |        |        |        |
search    |   s    |   e    |  a     |  rch   |
          |        |        |        |        |
          |        |        |        |        |
....      |        |        |        |        |

src/
  braid/
    client/
      desktop/
      gateway/
      mobile/
      bots/
      quests/
      ...
    server
      api/
      db/
      quests/
      search/
      crypto
      ...

"Modules" involves re-factoring the code so that each "feature" lives in its own folder. New functionality would be an addition of code, rather than a modification of previous code ("open to extension, closed to modification", "aspect oriented programming").

               msgs     db       ui      email
________________________________________________

emoji        e         mo       ji
________________________________________________

search     s     e     a       rch
________________________________________________

/src
  /braid
    /core
      ...lots of stuff here, organized similarly to now, smaller as we extract into modules
    /search
      ...one or more files, organized as necessary
    /emoji-provider
    /emoji-one
    /file-upload
    /file-upload-search
    /dropbox-file-upload
    /oauth-provider
    /github-oauth
    /google-oauth
    ... (lots of other modules)

One way to think about it is: currently, our separation-of-concerns is based only on "technical concerns", whereas the change to "modules" would add "product functionality" as concerns as well.

Motivations

Modules should hopefully:

• make it easier to understand the system by better separation-of-concerns
• make it easier to add new functionality without regressions
• make it easier for new developers to add features
• lead to "better" code (less coupling, more pleasant APIs, etc.)
• make testing easier
• foster the development of optional non-core functionality

Progress

We've thought a lot about the "api" of modules, and iterated it multiple times. Improvements to how "modules work" will continue, and tracked in this milestone and this issue .

We've transitioned the code into a core module, and extracted a few modules out of core (quests and various emoji modules).

The Braid Module Graph project exists to help visualize what modules could be extracted and how they could be related.

Next:

• decide on changes to 'how to do modules'
• refactor quests and emoji according to the changes
• come up with prioritized list of other modules to extract out of core (in this issue)
• gradually work through the list

Modules

• quests
• emoji
• emojione
• custom-emoji
• big-emoji

handle situation when last admin leaves, but other members remain

delete group when last member leaves

When the last member leaves a group, delete the group.

Should show a prompt to the user, along the lines of:

"You are the last member of the group. Leaving will destroy all content of the group. Are you sure you want to leave?"

add button to nickname edit field

add multiple states to messages (sending, waiting, error, sent, new, seen)

Change messages in the client to be in one of the following states:

• sending
• waiting to retry
• error (manual resend)
• sent
• new
• seen

Display each state slightly differently.

Get rid of the global 'message not sent' error

Store message drafts to local-storage

Adjust the "disconnected" warning to not prevent typing of messages

Website embeds should be "grayed out" in read threads

After the module refactor, this behaviour seems to have changed

Display a placeholder for long time gaps between messages

A task for new Braid contributors.

Goal:
In a thread, if the time between messages is very long (let's say... > 24 hours), include some UI between the messages, like "24 hours later..."

Notes:

• you'll probably need to change braid.core.client.ui.views.thread/messages-view
• you'll probably want to create a helper function to "display duration in a human-friendly way", ie. "24 hours" "3 days", etc. (in braid.core.client.helpers)
• Braid already includes https://github.com/andrewmcveigh/cljs-time cljs-time.coerce/from-date , cljs-time.core/now , cljs-time.core/days, cljs-time.core/hours and cljs-time.core/in-milis will probably be useful

investigate "freeze" when selecting github auth

Issues button in readme is broken

Links to non-existant (or at least non-public) repository https://github.com/braidchat/meta

Check this out!

Here is a video http://bit.ly/2qdc06N
Maybe there is inspiration in there

Test issue - Octocat bot should update braid group

In read-only-mode, show 'Join Group to Reply' button instead of message composer

A task for new Braid contributors.

Goal:
Braid has a read-only mode, where non-logged in users can see chat messages in a public group. Currently, in 'read-only-mode', there is no 'composer' textarea shown at the end of a thread. Instead of showing nothing, show a button "Join Group to Reply"

Notes:

• you can test read-only mode by:
• seeding
• logging in as [email protected]
• for one of the groups, [email protected] should have admin access; for that group, you can make it public by: admin-menu (in header)> group-settings> 'make public'
• you can then copy/paste the URL and open it in a private browser window
• braid.core.client.ui.views.thread is a relevant namespace
• reference braid.core.client.ui.views.header/readonly-header-view for how to trigger the login/join-group flow

Test issue - octocat bot should post to braid group

fix frequent "disconnects"

Auto-translate messages in a different language (via google translate)

A task for new Braid contributors.

Goal:
When a message is sent in non-English (for now), show a translation of the message below the message.

Potential extensions (for a separate PR):

• detect the language of the user's browser, use that as the 'default don't translate language'
• for other languages, show translations, but also show buttons: for example... 'always translate Russian', 'never translate Russian' (which would store that preference)

Notes:

• this should be implemented as a separate module
• translation can be done via an external API (microsoft? https://azure.microsoft.com/en-us/pricing/details/cognitive-services/translator-text-api/?cdn=disable)
• language detection should be done locally (either braid server or client); there are a few language detection libs available:
  https://github.com/optimaize/language-detector
  https://stackoverflow.com/questions/3227524/how-to-detect-language-of-user-entered-text
• braid.core.api/register-footer-view! can be used to display content after a message

Fix thread jumping when embeds load

Regression, presumably from when the logic for thread scrolling changed.

If one switches to a group with a long thread that has links in it, they'll see it starts scrolled to the bottom as expected, but then as the link previews load, the height changes & they end up scrolled up somewhat.

Module System Enhancements

Braid's code base is organized around "modules" (more about modules here ). How modules work in Braid has been iterated upon multiple times and will likely continue to evolve.

This issue and related milestone will track the ongoing effort to improve the module system.

Module Wishlist

• should make use of built-in clojure as much as possible
• module should not be aware of other modules that are extending it
• should be clear what is available for use and for extension (what is "public" vs "private")

v0

• a module can expose functionality ("the provider"), which another module can use ("the consumer")
• a module can be both a provider and a consumer
• the provider does not know about the consumers
• a module can span across client and server

v1

• a dependency graph can be generated
• modules can easily spec required inputs/outputs
• API docs for each module can be generated, ex:

xyz-module
depends on: 
"foo-event", 
"bar-event"
provides: 
"baz-event" params, docstring, expected return value
* [ ] unit tests can be defined per module
* [ ] e2e-tests can be defined per module

### v100
* [ ] modules can be turned on/off (via UI or system config)
* [ ] modules can be defined across repos (ie. for now, it's fine to have everything in a mega-repo)

## Potential Inspiration:
* ring pipeline / middleware
* re-frame events
* robert-hooke library 
* DOM event system
* component 
* mount
* defmulti
* pubsub

fix "disappearing thread" experience when sending a message

"If I scroll right in the list of the threads, then send a message to one of the threads, the thread disappears. I don't know where it's going, lol. I guess it should move to the left, because the threads are sorted by the latest message? I'm not sure, but it looks like it just disappears."

input loses focus after sending first message of a thread

When starting a new thread, after hitting enter, focus should go to the input of the newly created thread

way to view a single thread in "full screen"

make Braid web client more amenable to working on mobile

Add some responsive CSS to make the existing web client at least decent on mobile devices.

textarea stays large after sending a long message

fix fonts in gateway / login to be the same as in the rest of the app

Mail contact not working

I tried to write an email to [email protected] but got an delivery error.

Replies to messages

Another telegram feature. I don't know what you guys think about this, if it fits the conversation flow you're trying to create or deviates from it. I personally think replies help bring the chat together, removing ambiguities that might arise because someone sent a message just before yours, or because the message you're addressing has already been buried by others. What's your opinion on this matter?

Add ability to edit sent messages

People make mistakes. Let's help users undo them.

Suggested experience:

• an "edit" icon (similar to the ones for Mute and Permalink), but positioned right next to the timestamp, which enables editing
• pressing the up arrow while in the text box, which enables editing; escape cancels

Add a tag administration page (for admins only)

A task for new Braid contributors.

Goal:
To create a new page, for group admins, to be able to easily administer existing tags.
It should list all tags (with # of threads they are used it) and allow renaming. It should show a list of tags without any threads and allow deleting (this could be done as a second PR)

Notes:

• This should be implemented a separate module
• braid.stars is a good reference for how to do modules
• braid.core.api already has a number of hooks that may be useful, (ex. "creating a group page"), but a few new ones may need to be added (ex. "adding item to admin menu")
• the user subscription management page may be a useful reference (braid.core.client.ui.views.pages.tags)

Autocomplete list is occluded by thread top

This seems to be due to the recent thread styling changes.

change styling of login form to make alternate logins look less like a multiple-choice

Don't close thread on ESC keypress if there is an unsent draft

A task for new Braid contributors.

Goal:
Currently, hitting the ESC key while a thread is selected, closes/archives the thread. However... this can be really bad if the user is still typing a message (ie. has text in the composer). Change the existing ESC logic to not close the thread if there is content in the composer.

Notes:

• braid.core.client.ui.views.new-message and braid.core.client.ui.views.thread are likely relevant namespaces

Show date dividers in threads

A task for new Braid contributors.

Goal:
In a thread, show headers between messages at the start of a new day.
ie.

message
message
—— Jan 25 ——
message

Notes:

• this can all be done client-side
• you should be able to rely on the user's browser to figure out when a new day starts
• you'll probably need to change braid.core.client.ui.views.thread/messages-view
• Braid already includes https://github.com/andrewmcveigh/cljs-time cljs-time.coerce/from-date will probably be useful (and other functions)

extract reconnect-notice as module

A task for new Braid contributors.

We're extracting parts out of "Braid core" into loosely-coupled modules, to ease future development. As part of this effort, the functionality of the "reconnect-notice" can be extracted.
Currently, when the websocket is disconnected, a red notice bar is shown (you can trigger this by starting Braid in dev, then, in your repl, doing (stop!)).

Extract this functionality out of core and into a new module.

Notes:

• braid.core.client.ui.views.reconnect-overlay is where the view is now
• refer to braid.stars for how to write a module
• you should make use of braid.core.api/register-root-view!

feature request: automatic tag creation

Would it be a good idea to allow for automatic tag creation when a never-before-seen tag is utilized in a conversation? [I think it would be nice to save a step but then there is the problem with typos--i.e., inadvertently creating a new tag when attempting to reference an existing one].

Maybe a better solution altogether is to not allow free-form tags but rather display a list of existing tags when the '#' char is typed (and an empty slot at the bottom or top of the list to add a new one on-the-fly).

Convert all css mixins to functions

A task for new Braid contributors.

Goal:
Braid uses https://github.com/noprompt/garden for it's CSS. SASS/Less have a concept of mixins (effectively, functions that returns style rules that can be included in other places). With garden, we just use regular clojure(script) values. Currently, there is a mix of using constants and functions for mixin functionality. It would be nice if this was consistent -- just functions.
We'll call a mixin anything that returns either a map of css-rules {:foo "bar"} or a list of css-rules [:& {:foo "bar"}]. Values, such as "#00cc00" are not mixins.

For this task, convert all non-function mixins in braid.core.client.ui.styles.mixins into functions (and update wherever they are used).

Similarly, change all style blocks that are included in braid.core.client.ui.views.styles

If you happen to see mixins defined elsewhere that aren't functions, change those too.

allow autocomplete of tag names in the middle of a message

Not receiving password reset emails

Allow users to set and update their profiles

A task for new Braid contributors.

Goal:
Allow users to include some brief profile text. On their profile preferences page, show their profile and allow for editing it (a freeform text area). Include the description in user hover-cards.

Alternatively, allow admins to define certain fields that they want from their users, and show multiple input fields for the user.

Notes:

• Should be implemented as a separate module
• braid.stars is a good reference for how to do modules
• braid.core.api already has a number of hooks that may be useful, but a few new ones may need to be added

threads cover the "clear inbox" button, making it unclickable