search

Marduk-Project / bia-server

GNU General Public License v3.0
3 stars 2 forks source link

readme

Open Source platform to help volunteers against COVID19

Welcome to the Open Source platform to help volunteers, companies and public institutions to organize work against COVID19, and others future disasters.

Understanding in Brazilian Portuguese (pt-BR)

Esta plataforma nasceu para ajudar o grupo Brothers in Arms (Brasil-RS - Grande Porto Alegre) a organizar o volutariado, empresas e governo, visando combater o COVID19, e futuros desafios semelhantes.

Escolhemos o idioma inglês para a codificação, banco de dados e explicações, visando potencializar a contribuição e o uso internacional da plataforma.

Getting started

This project was written in Node.js technology, using Express as Back end, and Bootstrap with Vue.js as Front end. The server folder contains the back end code, and the front folder contains the front end code.

The Database choosed was a SQL type, with Sequelize as the ORM and migrations library.

Also, this app has a Command Line Interface, that uses the Commander.js library, with the scripts inside the bin folder.

First install and run

  1. You need to have Node.js installed 12.16.2+ on your computer with npm.
  2. Clone the repository.
  3. Run npm install.
  4. Copy the config.example.json file to cfg_development.json (or cfg_[env_name].json).
  5. Edit the cfg_development.json to have the correct database and other configs.
  6. Run npx sequelize db:migrate to run the migration scripts, to create the database tables.
  7. Run ./cli.sh admin-create <your-email> <your password> to create the first admin user.
  8. Run npm run front-build to Build the front end SPA (Single Page Application) files.
  9. Run npm start to run the server.

... and thats it!

Help needed

We are a small group, working as volunteers, coding to help it to work. If you want to help more, you can contact us on #issue12.

Code organization and standardization

We do not have any strong pattern organization at this moment. Basicaly we have the following rules:

Current application modules

Back end

The backend organization runs a classic Express application. The main librarys that are the structure of the server are:

Useful CLI commands

Folders organization

The full back end are inside server folder, with the following organization inside:

To understand how the code is pretended to be organized with more details, please read Code organization.

Database changes/migrations

Any change to the database (table or field creation, indexes, renames etc), need to be done with a migration file, inside database/migrations folder.

Migrations concept are just a way to keep track of any database changes by source-code/script files, time-based sequential and incremental order. If you need to put your development or production database on the same "moment" that other developers are, you just need to run their migrations scripts. You can also run on up (apply changes) and down(rollback changes) sequence.

If you need more info about migrations, please read the Sequelize Migration Manual.

Sequelize quick help info

Sequelize quick help command line tool pasted here:

$ npx sequelize --help
npx sequelize [command]

Commands:
  sequelize db:migrate                        Run pending migrations
  sequelize db:migrate:schema:timestamps:add  Update migration table to have timestamps
  sequelize db:migrate:status                 List the status of all migrations
  sequelize db:migrate:undo                   Reverts a migration
  sequelize db:migrate:undo:all               Revert all migrations ran
  sequelize db:seed                           Run specified seeder
  sequelize db:seed:undo                      Deletes data from the database
  sequelize db:seed:all                       Run every seeder
  sequelize db:seed:undo:all                  Deletes data from the database
  sequelize db:create                         Create database specified by configuration
  sequelize db:drop                           Drop database specified by configuration
  sequelize init                              Initializes project
  sequelize init:config                       Initializes configuration
  sequelize init:migrations                   Initializes migrations
  sequelize init:models                       Initializes models
  sequelize init:seeders                      Initializes seeders
  sequelize migration:generate                Generates a new migration file       [aliases: migration:create]
  sequelize model:generate                    Generates a model and its migration  [aliases: model:create]
  sequelize seed:generate                     Generates a new seed file            [aliases: seed:create]

Options:
  --version  Show version number                                         [boolean]
  --help     Show help                                                   [boolean]

Database seeders

In same way as migrations, you can create the seeders to generate database data to better test your code. To do understand more about seeders concept, you can read the Sequelize Migration Manual.

Front end

The application front end is based on Bootstrap framework with Vue.js as javascript SPA library, and with the Vuex as state management and routing.

Useful CLI commands

Understand the front end concepts...

The front end looks like complicated, but it's not. Lets just understand some concepts before we start understanding the folders.

...with that in mind, lets follow for the folders organization.

Folders and code organization

Important notes about Select2

Selects with remote data (Select2) are a common development facing problem. Please note that the Select2.vue in front/js/libs/components/form/Select2.vue was made to make it easy to work with. To understand how it works, you can see the UserSelect.vue file, in front/js/components/resources/gl_user/UserSelect.vue.

Simple example about using the Select2

Lets just follow the example as using the existing component on a vue file:

import UserSelect from "../.../UserSelect.vue";
export default {
    ...
    components: {
        'app-user-select': UserSelect,
    },
    data() {
        return {
            user: null,
        };
    }
    ...
}
<div>
  <app-user-select v-model="user"></app-user-select>
</div>

It will result in a...
HTTP GET /api/admin/gl_user?q=[your_query_text]

And the result will be parse by the UserSelect.vue => mapResult function:

export default {
    ...
    methods: {
        mapResult(value, index) {
            value.text = `${value.name} - (${value.email})`;
            return value;
        }
  }
  ...
}

Using Select2 with "extraparams" in the GET request

Another example, now with extraparams. Lets filter the users by level.

import UserSelect from "../.../UserSelect.vue";
export default {
    ...
    components: {
        'app-user-select': UserSelect,
    },
    data() {
        return {
            user: null,
            level: 1, // admin - check this with attention
        };
    }
    ...
}
<div>
  <!-- watch for the extraparams object with the level -->
  <app-user-select
    v-model="user"
    :extraparams="{ level: level }"
  ></app-user-select>
</div>

It will send the &level=level param on the request...
HTTP GET /api/admin/gl_user?q=[query_text]&level=1

Application CLI (Command line tools)

The command line tools for the application are inside the bin folder. All the commands will be documented better later... For now you can use ./cli.sh --help:

Usage: app [options] [command]

Options:
  -V, --version  output the version number
  -h, --help     output usage information

Commands:
  admin-create   Creates database and setup first admin user.
  connect-test   Tests database connection.
  help           Show this help
  help [cmd]     display help for [cmd]

Thank you

We want to thank you for your attention to read the entire README.md file. If you want to help, let us know.