Development, in-depth documentation

The application

• MEAN stack, seeded originally with MEAN.js boilerplate: MongoDB, ExpressJS, AngularJS v1 (we’re migrating to React), NodeJS. Additionally stuff like Bootstrap v3 for component styles, Leaflet for the map, etc.
• Database scheme (look for *.server.model.js project files to check most up to date info)
• We’re migrating the client to React. Read a migration guide.

The mobile app

• We have a basic Webview app written in React Native and Expo.io which mostly just gets you push notifications and an icon on phone’s screen. :-)
• We have in-the-works React Native app.

Coding conventions

• Project has .editorconfig file, we recommend to download extension for your IDE.
• Build script checks all the files against our ESLint rules. Fix errors before submitting PR and add integration for your IDE.
• Prettier codeformatter is configured so you might want to install integration for your IDE.

Other conventions

• File names use dash to separate words. For example: foo-bar.js (except for React Components CamelCase.js)
• Use camelCase for identifiers. Functions and variable names should be named like doAThing, not do_a_thing.

JS

• See Angular 1 Style Guide
• We’re migrating to ES2018. Write your code in modern JavaScript. Read a migration manual.

CSS/LESS

• We use LESS CSS for CSS.
• Build as generic and re-usable components as possible. Rather .panel than .about-box.

CSS class names

• Name reusable bits of layouts by module names and keep them out of page styles, (eg. .group-badge can be used in multiple places around the site.)
• Related elements within a module use the base name as a prefix. For example module .panel has also .panel-header, .panel-body and .panel-footer.
• Prefix state rules with .is- (for example .is-collapsed).

Route conventions

TODO: Outdated

Convention is as follows:

• Url has the plural like /messages/, /users/, /users/:userId/photos, /users/:userId/references
• The id is the singular name followed by Id like userId, photoId, etc
• The route with the id is called nameSingle like usersSingle, offersSingle, etc
• Template name matches route name
• Nested routes are simply concatenated like usersSingleReferences or usersSinglePhotosSingle

Examples

• /users route name users
• /users/:username route name usersSingle
• /users/:username/edit route name usersSingleEdit
• /users/:username/photos route name usersSinglePhotos
• /users/:username/photos/edit route name usersSinglePhotosEdit
• /users/:username/photos/:photoId route name usersSinglePhotosSingle
• /users/:username/photos/:photoId/edit route name usersSinglePhotosSingleEdit
• /messages route name messages
• /messages/:userId route name messagesThread - deviates because it is userId not messageId

Testing

Strategy:

CI setup

Slowly getting there. Any help/experiences appreciated! #228

Unit tests

…mainly to test Mongo models (example).

…as well some critical bits of Angular frontend (example).

Integration tests

… mainly for the API routes (example).

Clientside Component tests

• Look for modules/*/tests/client/components
• Written with React Testing Library

Run tests

• npm test for everything,
• npm run test:server for Mocha tests,
• npm run test:server:watch same with watching,
• npm run test:client for testing Karma-unit tests and
• npm run test:selenium to run old outdated Selenium tests. Requires Python. Make sure Trustroots is running already as this task won’t spin it up first. This task isn’t included in the main test task. If you want to pass custom domain to test for Selenium you can do so by running: python ./scripts/selenium/test.py https://dev2.trustroots.org/

Folder layout

You might want to read the folder structure to get a handle on how things are laid out, although we’ve started deviating from it with Angular.js to React migration. A quick summary:

• modules/ contains one folder for each “component” of the site, this is where most of the interesting stuff lives
• modules/**/server/ contains all the backend, server side stuff
  • /models defines the Mongoose models. There are only a few, so it might be worth scanning them to understand the data model. For in depth description, see [[database]].
  • /controllers as you’d expect, Express controllers live here.
  • /routes links url paths to controllers
  • /tests defines tests run server side
  • /jobs Agenda job scheduler (~cron) jobs (see config/lib/agenda.js for more)
  • modules/core/server/views contains email templates and initial rendered index.html
• modules/**/client/ contains all the client side stuff
  • modules/core/client/app
  • modules/core/client/app/less contains the site wide style variables and application.less file which includes rest of the modules.
  • /less is where you’ll find CSS styles in LESS format. Each module should have .less file with the module name, which then includes rest of the less files from the same folder. E.g.: modules/core/client/app/less/application.less includes modules/messages/client/app/less/messages.less which then includes inbox.less and thread.less from the same directory.
  • /views is where you’ll find Angular.js templates
  • /api functions for communicating with REST API points, used in React components and not with Angular.js stuff; Angular uses /services insteead.
  • /services is where you’ll find Angular service, mostly for connecting to REST API points. Not used in React components; those use /api instead.
  • /config contains the client side routes and other configs
  • /directives contains the Angular directives
  • /controllers contains the angular client side controllers
  • /components contains React components. Read more about our React migration
  • /utils containts utility functions used mostly with React components.
  • /images Images for the module.
• config/ ta-da, configs! Server side.
  • /assets Defines paths for assets (serverside JS, frontend CSS/JS/LESS, lib files etc)
  • /lib/env primary config files. Don’t modify anything else here except local.js.
  • /lib/env/local.js file overriding other env/* files. Put here your adjustments you don’t want have publicly at the repo (it’s git-ignored).
  • /lib/agenda.js Agenda job scheduler (kinda like cron)
  • /lib/worker.js Configures all cron jobs with above Agenda
  • /lib/express.js Sets up the server side application and routes
  • /lib/app.js Boot up function for the serverside app.
  • /lib/facebook-api.js Sets up Facebook Graph API client
  • /lib/firebase-messaging.js Sets up Firebase for push notifications
  • /lib/mongoose.js Sets up database connection and related utilities.
  • /lib/render.js Configuration for Nunjucs, a serverside template renderer
  • /lib/logger.js Configures error logging service
  • /lib/exponent-notifications.js Expo.io based mobile app push notifications
• server.js server entrypoint; for APIs and serving the fontend client
• worker.js background job runner entrypoint, for running Agenda
• package.js dependencies, managed with NPM