How to sketch out an event-driven system?

Question

I'm trying to design a system in Node.js (an attempt at solving one of my earlier problems, using Node's concurrency) but I'm running into trouble figuring out how to draw a plan of how the thing should operate.

I'm getting very tripped up thinking in terms of callbacks instead of returned values. The flow isn't linear, and it's really boggling my ability to draft it. How does one draw out an operational flow for an event-driven system?

I need something I can look at and say "Ok, yes, that's how it will work. I'll start it over here, and it will give me back these results over here."

Pictures would be very helpful for this one. Thanks.

Edit: I'm looking for something more granular than UML, specifically, something that will help me transition from a blocking and object-oriented programming structure, where I'm comfortable, to a non-blocking and event driven structure, where I'm unfamiliar.

Answer 1

Based on http://i.stack.imgur.com/9DDQP.png what you need is a good flow library that allows you to pipeline sync and async calls in node.

One such library is https://github.com/isaacs/slide-flow-control (look at the slide preso there too) and the code outline for what you need to do is below.

It is self documenting and as you see it is quite concise, pure nodejs, uml, img's etc. not required.

var chain = require("slide/chain")
    , asyncMap = require("slide/async-map")
    ;

// start processing
main_loop(function() { 
    console.log("its done"); // when finished
});

function main_loop(cb) {
    var res = [];
    // each entry in chain below fires sequentially i.e. after
    // the previous function completes
    chain
        ( [ [start_update_q, "user-foo"]
          , [get_followed_users, chain.last]
          , [get_favorites, chain.last]
          , [calc_new_q]
          , [push_results, chain.last]
          ]
          , res
          , cb
        )
}

function get_favorites(users, cb) {
    function fn(user, cb_) {
        get_one_users_favorites(user, cb_);
    }
    // this will run thru get_favorites in parallel
    // and after all user favorites are gotten it will fire 
    // callback cb
    asyncMap(users, fn, cb);
}

// code in the various functions in chain here,
// remember to either return the callback on completion.
// or pass it as an arg to the async call you make within the
// function as above i.e. asyncMap will fire cb on completion

Answer 2

UML might be appropriate. I'd look at the behavior diagrams.