<div id="api_guide">
<h2>Kidney Exchange Application Server Architecture</h2>

<div id="input_format_contents">
  <h3>Table of Contents</h3>
  <ul>
    <li><a href="#intro">Introduction</a></li>
    <li><a href="#platform">Application platform</a></li>
    <li><a href="#rails">Ruby on rails application</a></li>
    <li><a href="#gem">Kidney exchange ruby gem</a></li>
    <li><a href="#cpp">C++ libraries</a>
      <ul>
        <li><a href="#base">kidney_base_lib</a></li>
        <li><a href="#ip">kidney_ip_lib</a></li>
        <li><a href="#open">kidney_open_ip_lib</a></li>
      </ul>
	</li>
  </ul>
</div>

<div id="intro" class="formats">
  <h3>Introduction</h3>

  <p>
    The kidney exchange application server exposes an API for finding the optimal (as defined in the optimality
    criteria
    <%= link_to 'optimality criteria', {:action => 'optimality'} %> ) set of exchanges for an instance of the NHSBT
    matching results data set.
  </p>

  <p>
    The application is composed of several components with the two main parts of the system comprising a Ruby on Rails
    application and C++ native library. A complete overview of the system is shown below. How these components make up
    the system are then discussed in the preceding sections.
  </p>

  <p align="center">
    <%= image_tag("top_level_architecture.png", :size => "500x600", :alt => "Architecture diagram") %>
  </p>
</div>

<div id="platform" class="formats">
  <h2>Application platform</h2>

  <p>
    It is recommended that the Ruby on Rails application be hosted using Nginx
    (<a href="http://nginx.org">http://nginx.org</a>) as a proxy for the ruby web server thin
    (<a href="http://code.macournoyer.com/thin">http://code.macournoyer.com/thin</a>). The choice here is made for its
    simplicity of setup and configuration. However, it should be possible to use other servers/proxies to achieve the
    same objective.
  </p>

  <p>
    A sample nginx configuration file is shown below. Lines 1-5 set up a simple round-robin
    load-balancing. In general, this tends to be a good strategy for ruby web services as web servers such as thin are single thread
    and
    therefore only able to process one request at a time. In reality a single web service is probably ok for the kidney exchange application.
    The <code>server</code> component starting at line 7 sets up our virtual host. In
    this case we are only hosting one application on this server so we can allow this to be the default host listening
    on
    port 80 and do not need to do any name based virtual hosting. Many of the components of the server section are
    obvious and
    so we'll skip to the location section of the file (line 16). Here we set up how the server talks to our other
    (thin)
    server. It does
    various things like
    pass on the IP address and host name (lines 20-23), checks if an index file is available at the location (lines
    22-24), checks if the file is just static content and if so serves it (lines 26-28), and finally if it these
    conditions are not met is passes the url on to a thin web server to handle (lines 30-33).
  </p>
  
  <pre class="brush:js">
    upstream kidney {
      server 127.0.0.1:3000;
      server 127.0.0.1:3001;
      server 127.0.0.1:3002;
    }

    server {
      listen   80 default;

      access_log /opt/www/kidney/log/access.log;
      error_log /opt/www/kidney/log/error.log;

      root   /opt/www/kidney/kidney_server/public/;
      index  index.html;

      location / {
        proxy_set_header  X-Real-IP  $remote_addr;
        proxy_set_header  X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header Host $http_host;
        proxy_redirect off;

        if (-f $request_filename/index.html) {
          rewrite (.*) $1/index.html break;
        }

        if (-f $request_filename.html) {
          rewrite (.*) $1.html break;
        }

        if (!-f $request_filename) {
          proxy_pass http://kidney;
          break;
        }
      }
    }
  </pre>

  <p>
    Below we show a sample thin server configuration file. It's not essential to understand the details of this
    file as they are normally
    auto-generated by the thin command <code>thin config</code>. To generate the file shown below we used the command
    <code>thin config -C /etc/thin/kidney.yaml -c /opt/www/kidney --servers 3 -e development</code>.
    This command infroms thin to
    to create a config file at <code>/etc/thin/kidney.yaml</code>, where the location of our ruby application is
    <code>/opt/www/kidney</code>, it should start 3 thin server processes, and the ruby application should be run in
    development mode - this means detailed information is displayed to the logs, the alternative here is production mode.
    By default the first server will start on port 3000, the next on 3001, etc, unless we specify otherwise. As you
    can
    see ties back with the ports specified in the <code>upstream</code> part of our nginx config section.
  </p>

    <pre class="brush:js">
      ---
      pid: tmp/pids/thin.pid
      wait: 30
      log: log/thin.log
      port: 3000
      max_conns: 1024
      timeout: 30
      max_persistent_conns: 512
      environment: development
      chdir: /opt/www/kidney
      require: []

      servers: 3
      address: 0.0.0.0
      daemonize: true
    </pre>
</div>

<div id="rails" class="formats">
  <h2>Ruby on rails application</h2>

  <p>
    This application exposes both the REST and SOAP APIs. This is a standard rails 2.3.8 application for the REST API
    calls and uses the actionwebservice gem to support SOAP requests. It is worth noting that this application uses
    an older version of rails than is currently available in order to support SOAP requests that have largely been
    deprecated from the latest rails libraries.
  </p>

  <p>
    The application is quite simple in nature and largely passes on much of the work to the kidney exchange ruby gem
    documented below. However, the web based (HTML) interface is also provided through this code and included is a
    data
    model that is used to parse the JSON output from the REST API.
  </p>
</div>

<div id="gem" class="formats">
  <h2>Kidney exchange ruby gem</h2>

  <p>
    This ruby gem provides a bridge to the C++ libraries that actually carry out the task of finding the set of
    exchanges. In order to call the C++ libraries we use swig which is a third party tool that allows ruby to
    integrate effectively with C++ - technically ruby extensions must be in C and swig provides us with a way of
    easily calling our C++ library with C linkage but also helps integrate C applications with the ruby native API.
  </p>
</div>

<div id="cpp" class="formats">
  <h2>C++ libraries</h2>

  <p>The ruby gem uses our <code>kidney_open_ip_lib</code> C++ library to interact directly with the IP (Interger
    Programming) solver. This library contains the code for building an integer program using the third party (open
    source) COIN-CBC integer programming toolkit. Into this library is compiled two other C++ libraries, namely
    <code>kidney_base_lib</code> and <code>kidney_ip_lib</code>. We discuss the high level features and services
	provided by these libraries in the sections below.
  </p>

  <div id="base">

  <h4>kidney_base_lib</h4>

  <p>The <code>kidney_base_lib</code> is a C++ library that contains, amongst other things, data structures for
    holding the instance data, the implementation of the pairwise exchange algorithm for calculating the correct
    number of effective pairwise exchanges using the <a href="http://lemon.cs.elte.hu/trac/lemon">LEMON</a> maximum
    matching algorithm, the tab, xml and json parsers and other classes associated with providing a framework for
    kidney exchange.</p>
  </div>

  <div id="ip">

  <h4>kidney_ip_lib</h4>

  <p>This library builds a framework around modelling paired/pooled dontation as an integer program, thus enabling 
    various IP toolkits to be used without the need to have repeated
    boilerplate code. In this library we can find, code representations of, strategies (i.e. the set of steps or integer programs)  
	used to find a set of exchanges, for example we
    have strategies for finding an optimal exchange (<code>optimal</code>), or a set of exchanges with maximum weight
    and maximum cardinality (<code>maxcard</code>). This enables us to define the strategy that is required to find a
    set of exchanges with the required properties once and so is not required for each individual IP toolkit. Each
    strategy is created from a set of constraint objects and objective functions that are suppiled with this
    library.</p>
  </div>
  
  <div id="open">

  <h4>kidney_open_ip_lib</h4>

  <p>In this library we use the two libraries described above to supply the set of classes and interfaces that are
    required
    to build both the model and run the solver using COIN-CBC. We build a matrix representation of our IP model
    using the constraint objects described in the previous section. The supplied objective object is then used to
    generate the objective function for the COIN branch and cut algorithm.</p>
  </div>

  </div>
</div>