flow

The information tracking and publication system designed for complicated, busy environments.

This is a theoretical README as if the project really exists. It doesn't yet, so you can ignore this!

Backstory

Today we live in incredibly complicated environments where dozens of teams are making changes to hundreds of projects on a daily basis. Trying to keep on top of all of this information is an exercise in pain. People try to do their best, but with constant shifts in who-does-what and what-is-where it becomes non-trivial to ensure you get the right information at the right time.

Controlling how much of the firehose you tap is a balancing act between how much effort people put in to curating their output (and categorizing it) and how much effort you put into figuring out what and where to consume.

The purpose of flow is to make it easier. Taking inspiration from Twitter, one of the most effective ways of communicating chaotic information at a global scale, and tying in some of the best practices from modern information architecture (tagging, subscriptions, etc) we believe that flow can help the modern organization increase its communication effectiveness.

After all, life's too short to read a bunch of email.

Getting Started

The basic unit in flow is a "topic" and an "event". If you think of Twitter, an event is a single tweet. Some unit of information being expressed and delivered to some people who have expressed interest ("subscribed").

Topics

This is the organizational unit of information. Broadly speaking, everything informational is about something. It can be as broad (and useless) as a category such as "Miscellaneous" or it could be as small and focused as a particular project: "Green Lantern - Launch".

Topics can be created within topics. The particular usefulness of this is up to you and your team, but this allows for the usefulness of hierarchical information. For example, one might define topics for the organization:

Engineering
- Infrastructure
  - Messaging Team
    - Direct Email Service
    - Bulk Email Service
  - Database Team
    - MySQL
    - ...
- Engine
  - ...
Users
- mark
- sean
- john

This shows a possible organization of topics, which is useful because it allows people to subscribe to the level of detail that they want. If they are interested in all Engineering updates, they can get them; else, if you are only interested in a particular project, you can limit your subscription to just the smallest unit that interests you.

This type of organization places a bit of effort at the beginning to figure out where new topics go, but once that's done, you can concern yourself only with the individual topics. Publishing events on your project topic should be a trivial operation.

A given topic will contain a limited set of metadata about it. Since we expect there to be topics for projects, you might imagine a metadata set could contain things like:

owner: Responsible party to contact about this topic.
due date: When this project is expected to be complete.
tags: See more in the Tags section below.
priority: Simple expression

The one special topic area is the "Users" topic, which contains each of the users of the site. This is how we handle who sees what, by publishing messages to a given topic.

Events

Everything that happens within flow generates an event. Some of them are automatically generated such as when a new topic is created, an event is generated up the tree in case people are interested in further actions with that topic.

Many other events are generated by humans when they want to say something. The general idea is that these are announcement style messages or updates about the topic. You might imagine someone saying "deprioritized to Q2" or even "service is down" or similar updates. What you say might depend on what kind of topic it is: a project, a service, or something else entirely.

Events can also be tagged, and automated events are tagged with a hopefully useful amount of metadata. Manually created events should be tagged with information that might include:

type: Maybe announcement, informational, etc?
severity: Or maybe this is something like CRIT, WARN, INFO, DEBUG.

There are probably other metadata that might apply.

Deleting/Editing Events

Given the nature of the system, events probably have to be implemented with "generation counters" and that way all of the items that link back to them link to an "event+generation" and can handle the case where the thing that spawned them changed.

The tough case is where someone accidentally publishes something with a high criticality or whatever and that causes various subscriptions to send push notifications. The user then edits their event, but subscriptions have already fired.

Perhaps the solution here is a built-in short timer that allows people the chance to edit their event before it's locked? Once an event is locked, the only thing that can be done is editing the text and/or deleting it? Do we even want to allow deleting?

Subscriptions

This is the meat of the system. We basically allow people to create subscriptions, which can be based on topics, tags, or some combination of both. The model that flow follows is sort of "ifttt" in essence, you can express something like:

if topic-with-subtopics "Engineering"
- and tag "severity" in ("CRIT", "WARN")
- then ACTION, ACTION, ...

By default you probably don't want to actually edit the subscriptions with such detail. Most of the time you will probably just see events and then you'll click on a tag/topic and click "subscribe" which will just show more messages that match that filter in your personal topic.

All subscriptions are created on a topic. I.e., when you subscribe to something, what is happening is that your personal topic (see above) gets a subscription. This causes your personal topic to include the subscribed content.

This also means that if you want to, say, create a view for a team, then you would create a topic for the team and then add subscriptions to that topic. So the "Engineering" topic might have a subscription to "Global Company Announcements", and then all messages in the latter appear in the former.

Actions

Possible additional actions that a subscription could include:

rublish to $topic (think retweeting, but to a particular topic, this is also how you see things in your feed... since your feed is just a topic)
send email to $address
send push notification

Several actions can be defined for a subscription and all of them will be performed when the subscription is triggered.

Licensing and Copyright

Please see the LICENSE file.

zorkian/flow