The Library Directory

The Library Directory (hakemisto.kirjastot.fi) is to our knowledge the first completely open public sector IT project in Finland.

Not only is the whole source code is available at GitHub, but also the revision history has been public since day one and the project is open for collaboration. Anybody who finds a flaw can file a bug. Heck, anybody with enough skill could even write code and make pull requests if they want to improve their public service. Also other cities and governments could reuse it to improve the level of their e-services, quickly and at a low cost.

The customer City of Helsinki and nation wide library services wanted a website where the visitors can easily locate their nearest libraries, search for services, view opening times, contact information etc as a modern rich web experience.

The service was built as multi-lingual from ground up using both established and emerging best-of-breed open source technologies. Currently the service is available in Finnish, Swedish and English languages.

In the following chapters we will look inside the application framework and its components.

Project hosting and code repository

The project is publicly hosted at GitHub. GitHub provides hosting and tools for many significant open source projects and their developers to work with.

GitHub provides a web based graphical interface to a distributed version control system (Git) with easy access to view code changes across time and different versions.

The main GitHub services are: version control system / source code repository, project forking, documentation wiki and issue tracker.

Unlike commercial software projects in general, this project was by customer request publicly available at GitHub from the beginning, to take (and give) maximum advantage of the open source ecosystem.

Project architecture

The project builds upon many open source technologies and leverages their unique abilities in providing a fast server response times for end users, widely tested components and in overall trusted quality.

The main components are:

• Node.js – server core
• Elastic Search – database backend
• GNU gettext – translation facilities for multilingual user interface
• HTML5 – features for cross browser functionality and geolocation
• jQuery – Javascript library for user interaction and data manipulation
• Twitter Bootstrap – user interface components

Node.js

Node.js is a modular event driven asynchronous/non-blocking web-application framework built on Chrome JavaScript runtime called v8. Node runs code in the server, as opposed to web browser JavaScript, which runs in the end-user’s browser. In Library Directory, Node provides the server core functionality with file, HTTP and database I/O operations.

Asynchronous or non-blocking operation means that the program is never stalled anywhere waiting for data to process. At the bare minimum, node process iterates through its event loop waiting for I/O events to start or finish processing and generates events for callback-functions related to I/O operations. In short, Node is doing its best to make sure that it is ready to accept new connections and process data to its full potential all the time.

v8 compiles JavaScript into fast native machine code before execution. By doing this, it is possible to reach performance levels comparable to traditional high level compiled languages, such as C and C++. However, programming with asynchronous code requires some special considerations regarding concurrent access and I/O blocking behind the scenes.

By these design factors, Node can achieve quite impressive performance and response times while remaining relatively simple and maintainable at application programming level.

Elastic Search

Elastic Search is a bona-fide search engine that builds upon Apache Lucene, a Java based search and indexing engine.

Elastic Search is schema-free document-oriented nosql database. Data is moved to and from the database as JSON objects via RESTful API over standard HTTP queries.

By using Elastic Search as data storage and search index, the whole complexities of actual search engine logic is externalized to where it is done professionally and in best possible taste.

The Elastic Search requirement as a data store was mandated by the client’s previous engagements.

Gettext

Gettext is a legacy system widely used in Unix systems for localization and internationalization purposes.

Its main benefits are true and tested tools for managing translations and availability across different operating systems.

In Library directory, GNU gettext is used both in server and as client-side javascript implementations to provide seamless multi-lingual user experience.

HTML5

The benefits of HTML5 are paramount to any modern web application. In this particular case, we rely on HTML5 to provide cross browser compatibility and geolocation support for easily finding the user’s location and provide quick answer to questions such as “where is the nearest library”.

jQuery (and JavaScript)

jQuery makes it easy and convenient to use client side JavaScript for traversing and manipulating the HTML document object model programmatically. It is possible provide a dynamic web experience to end user. For example, to update a web page content partially without loading the whole page and related files from the server.

This both speeds up the user experience and lessens server traffic, which can speed up the whole process and allow more concurrent users or make the experience faster for same amount of users. It also makes the web application feel a bit more like traditional desktop application.

jQuery and JavaScript are also being used in server and client side for database queries and in formatting the json query data into its final displayed form.

Server-side JavaScript is also used for generating static views for browsers with JavaScript turned off or older browsers with limited compatibility.

Twitter Bootstrap

Twitter Bootstrap is the basis for a clean scalable web user interface that provides all the elements needed for user interaction.

It utilizes modern HTML5 and CSS3 techniques for generating common forms, buttons, tables, navigation menus and other user interface elements.

Bootstrap also provides a responsive grid system that automatically scales down for small screen sizes, such as tablets and smart phones, without any extra effort from developer.