Hacking Mekansm
===============

Mekansm is a microservice written in Python using the CherryPy web framework.

It has very clear separation between it's modules, to make it obvious
where to look for things, and where to put new things. The flow of control
is unidirectional and is enforced by strict imports.

The flow of control in order of usage is detailed below.

Web Framework
-------------

The Web Framework is what listens for connections and calls the
actual Mekansm code.

Handlers
--------

The handlers receive the calls from the web framework, and send back
the responses. In order to get the responses, the handlers call the
core layer.

Core
----

The core is where all the business logic is stored. It is completely isolated
from the other sections of the stack, and thus is designed to be easily
testable.

Dependency injection is implemented by passing an application context
as method arguments. This can either be a live context in production
or development, or stubs during testing.

Adapters
--------

Adapters communicate with external resources. When instantiated, they
will form a an application context that can be passed to the core
using dependency injection.


Maintaining Order
=================

Note that the design implies that each layer is as isolated as possible
from each other. ALso each part of Mekansm only talks to, at most, the
immediate lower layer, never to an upper layer. This is enforced by both
imports and dependency injection.

Running Tests
=============

Mekansm tests are implemented with pytest. As a convenience, you can use
`tox <https://tox.readthedocs.org/>`_, like so::

    $ tox

Which will run the tests in python 2.7 and pypy. Tox will handle the
installation of virtualenvs and dependencies for you.

By default, the tests will spawn a PostgreSQL database for you. If you
want to speed up things, and have a running database with privileged
access, you can use it in the test run by passing the DSN either directly
to py.test::

    $ py.test --postgres=postgresql://myuser@localhost:5432/mydb

or tox::

    $ tox -- --postgres=postgresql://myuser@localhost:5432/mydb

The tests will then create a database template with the fixtures installed,
and then create a new database for each test.

There is also a handy static check analysis alias that you can use::

    $ tox -e quality

It will run pylint and flake8 in the codebase.


Installing Mekansm
==================

You can run Mekansm locally by installing it in your environment::

    $ pip install -e .

Running Mekansm
===============

After installing Mekansm, you can run it like so::

    $ python -m mekansm
