Kallithea internals overview

[Thomas De Schampheleire]

On Thu, Jan 29, 2015 at 1:00 AM, Mads Kiilerich <mads at kiilerich.com> wrote:
> On 01/28/2015 08:14 PM, Thomas De Schampheleire wrote:
>>
>> Hi,
>>
>> What would be useful to me (and probably to other new contributors) is
>> a technical overview of Kallithea's internals.
>>
>> Browsing the code as a newcomer only provides so much insight; it's
>> difficult to get a good overview of the different components and how
>> they fit together.
>>
>> For example, there are
>> - templates
>> - controllers
>> - models
>> - ... ?
>>
>> and then there are technologies like pylons, cellery, rabbitmq,
>> fontello ... and various javascript libraries like mergely, select2,
>> jquery and what not.
>>
>> Even though I already know for some of them how they (more or less)
>> fit in the picture, a grand overview of all this would be a big help.
>> This could even be added in the documentation.
>
>
> If you make a first draft with the things you already have figured out and
> the qualified guesses you have made, then I will make a similar iteration
> and fix/add what I might be able to add on top of that.

Let me give this a try. It's not very structured, but it could become
better when the picture is more complete.



Frontend:
---------

URLs are connected to actual code using pyRoutes, configured at
config/routing.py.
The code that is called is part of controllers, but how to
define/describe a controller?

Templates (kallithea/templates) define the core of the user interface.
They intermix regular HTML with Javascript code (plain Javascript or
frameworks like jQuery, YUI, (others?)). The templates are parsed
using the 'mako' template library. Data regarding
commits/repositories/... is loaded dynamically from the server through
AJAX calls.


Question: what is the reasoning to both use jQuery and YUI? Can't we
select one framework and do everything in that?
Answer: according to the wiki 'future' list, YUI should be killed in
favor of jQuery.

Related question: a bird told me that it may be better to use a
higher-level framework like AngularJS instead of directly scripting
stuff either in plain Javascript or jQuery. Has there been any thought
about this before?

On the 'future' list, I see "move code from templates to controllers
and from controllers to libs or models". Can you clarify this a bit
more?

Question: how is the relation between the REST API (controllers/api)
and the AJAX calls? Is the API used internally in some way, or only
provided for external usage?

The codemirror JS library (http://codemirror.net/) is used to display
code files.

The mergely JS library (http://mergely.com) is used to display diffs
of code. Mergely is based on codemirror.

fontello is a library/service to create a font of symbols (instead of
using icons in image files). Did we create our own font or are we
using an existing one?
'font awesome' is a specific symbol font. How does it relate to fontello?

pygments: syntax highlighting

formencode: form validation

excanvas?

mousetrap?

native.history.js?


Backend:
--------

Revision information is obtained from the VCS library (lib/vcs), which
in case of Mercurial interacts directly with the Mercurial python
classes, and in case of git uses the dulwich python module.

models: this is a class representation of the database tables. Which
framework/component handles the relation between these classes and the
actual database? I guess using SQLAlchemy? How does this relate to
Django?

pylons: web framework, but what exactly does it do?
On the 'future' list, I see: 'more best practice for web apps and the
frameworks', can you clarify a bit more?

paste: ?

bcrypt: password hashing

celery: distributed task queue  (how is this used?)

whoosh: code indexing/search

Question: what is all this WSGI stuff? If you start Kallithea
according to the base instructions, it's hosting it's own web
interface (without WSGI?) How does WSGI work, what are the
advantages/disadvantages? Related to this, I see people running
Kallithea under Apache, advantages/disadvantages?


Thanks,
Thomas