Architecture & folders

Summary

Alakajam is a website powered by a NodeJS server. If you have decent knowledge of JavaScript, you should be able to get started quickly. The main techs we use are:

• TypeScript (extension of the JavaScript language) (*)
• Express (web framework)
• Nunjucks (server-side templates)
• Bookshelf (ORM) + Knex (SQL builder)
• PostgreSQL (database), although SQLite is supported for development
• Bootstrap/Bootflat (UI)
• CSSNext ("extended" CSS)

The code takes advantage of the async/await syntax to make asynchronous code look cool. The trickiest part of the sources is the Bookshelf ORM: while it simplifies a lot how database queries are run, it can take some time to get used to.

(*) You may find that we're not taking advantage of TypeScript that much in practice. That's because the project has been initially coded in JavaScript, then migrated to TS. We aim to improve that little by little.

File structure

NB. Unlike in the schema, the models are now in a single core/models.js file.

Name	Description	See also
client/	Custom CSS and JavaScript. All the CSS will be built automatically into a single file thanks to PostCSS, same with the JS thanks to Webpack. We can use most of the latest CSS/JS features we want thanks to CSSNext and Babel respectively.	Working with client side JavaScript
cypress/	Set of integration tests based on Cypress. We use CircleCI to run these (and unit tests) to detect regressions in the code automatically. Far from extensive, but still useful.
deployment/	Scripts & files used on the live server.
githooks/	Run the install script inside to make sure the code style is always validated before you commit code.
server/articles/	List of articles to be displayed in the Docs section of the site.
server/controllers/	Implements the routes (see index.js) and the handling of requests, using Express. Data is passed to/retrieved from services, then we eventually choose a template to render.	Working with controllers
server/core/	Technical setup and various utilities central to the services, controllers & templates. All the database entities are here in a models.js file.
server/migrations/	Database migrations.
server/services/	The bulk of the logic. Interacts with the database through Bookshelf (ORM) + Knex (SQL builder), exposing features to the controllers.
server/templates/	HTML templates. They are rendered from the controllers, and processed by Nunjucks.
server/test/	A vague attempt at introducing unit tests.
server/index.ts	The entry point of the application, initializing Express, PostCSS, Webpack etc.
static/	Static assets (pictures, external libraries, etc.)
config.sample.js	An example configuration file. The one actually used by server upon launch is config.js (created automatically if it doesn't exist).