Skip to content
/ opendojo Public

An open-source student and class management system for traditional karate clubs

License

Notifications You must be signed in to change notification settings

sedge/opendojo

Repository files navigation

Build Status

Welcome to OpenDojo!

This is an open-source student check-in and class management system for small to medium sized traditional martial arts clubs. Features include:

  • A class management console, where classes can be created, assigned a day and time and restricted to certain ranks
  • A rank management console, where ranks can be defined
  • A student management console, where students can have their contact, membership expiry and rank information stored
  • A live, browser-based check-in system, where students can see the current class, see a custom message from the instructor, modify their contact information and check-in
  • A simple email client, where the instructor can send individual or mass emails to their students based on rank or other criteria

Table of Contents

  1. Prerequisites
  2. Installation
  3. Environment
  4. API Reference
  5. Tests
  6. Data

1) Prerequisites

The following global dependencies are required for this application:

  1. Nodejs v0.10.~ (native)
  2. MongoDB (native)
  3. React (native)
  4. Grunt (npm module)
  5. Mocha (npm module)

NOTE: This app has only been thoroughly tested on the most recent versions of Google Chrome (38+), and as of this writing, browser compatibility is not guaranteed for any other platform or version.


2) Installation

From the root directory: npm install


3) Environment

Variables

The server won't run without an environment file in the root directory of the application. Copy the provided env.dist file to .env and customize as necessary.

Database Configuration (Windows 7/8)

After installing MongoDB, in a new command shell, traverse to the \bin subdirectory of your MongoDB installation folder. An executable file called mongod.exe should be found in there. In this subfolder, you should type in this command to set the database to point to the OpenDojo repository's parent folder with an addition of adding a \data subfolder in your path. It does not exist yet, but it will as soon as MongoDB turns on. The command is highlighted below:

mongod --dbpath C:\["PATH\TO\YOUR\OPENDOJO\PARENT\FOLDER"]\data --port 27017

At this time, adding user data programmatically is required in order for the database to contain valid user credentials for you to sign into the app with. The user generation script is currently localted inside of the server\scripts subdirectory of the OpenDojo repository. If you would like sample data for the rest of the modules to be generated for you at this time as well, you may invoke the user and sample data generation scripts simultaneously, e.g. -

node _dbSamplesGen.js && node _uGen.js

Naturally, there is also a script to delete this data located in the same subfolder.

Server Initialization

When ready, npm start will spin up the server. The default localhost port the node process has been set to serve at is 8745.

Front-end

Before you can view your work, you have to compile the CSS files and ReactJS app files with grunt build.


4) API Reference

Routes

Route Name Available Verbs Description
/api/[students OR ranks OR classes OR records] GET, POST Used to retrieve all existing records of the requested module from the DB, or adds a new record to the database.
/api/[student OR rank OR class OR record]/:id GET, PUT, DELETE Used to retrieve, edit, or delete a single module record. Requires a valid id value.

Authentication

Our security infrastructure uses the JSON web token protocol alongside node.js. It is sessionless, URL-safe, and claims/roles expandable with relative ease.

Data Flow

alt text

Routes
Route Name Available Verbs Description
/token GET Used to generate and retrieve a valid JSON Web Token. Requires valid user credentials in the request headers in order to respond successfully. This route is the de-facto "gateway" to being able to retrieve any subsequent resources from the available module routes.
Events
Event Name Arguments Child Events Child Arguments Description
logIn none logInCompleted, logInFailed logInCompleted: (token, validUser), logInFailed: (error, code) Event listeners/handlers for the GET /token request and response process. The logIn.failed() also listens for any failed GET request from the 4 modules in order to properly obstruct any unwanted access to these protected resources.

Style Guide

We utilize both native and React-based Bootstrap CSS components. Since our front-end relies almost exclusively on React, it would be in your best interest to render any new data or feature using React-Bootstrap components and classes. Any custom styles or colours for our app's elements and general motif have been declared in our style.less file and are to be followed as closely as you possibly can.

If you are planning on adding an element or component which does not have any custom CSS rules already created for it, feel free to add them yourself, but keep in mind that the design and layout choices you will make will be subject to much scrutiny by some very picky people upon review. Try to maintain a consistent feel in comparison to the rest of the app's UI in general. To see an example of our style guide being used on standard elements and components, you should take a look at our rendered styleguide.html page located in the server subfolder. This can be accessed most easily while the server is running at /styleguide.html.


5) Tests

Tests are a grunt task that invoke the mocha test framework and provide JavaScript linting by running:

$> grunt test

For more information on how to implement unit tests for this app, refer to our CONTRIBUTING.md file.

6) Data

Scripts/_dbCustomMessage.js needs to be run to allow the user the ability to create a custom message for checking into class

About

An open-source student and class management system for traditional karate clubs

Resources

License

Stars

Watchers

Forks

Packages

No packages published

Contributors 4

  •  
  •  
  •  
  •