Skip to content

README.md

Latest commit

 

History

History
83 lines (56 loc) · 4.94 KB

README.md

File metadata and controls

83 lines (56 loc) · 4.94 KB
Raw

gamification-api

API supporting the Gamification project at Topcoder.

Quick Start

Assuming you have PostgreSQL server running locally and the database tc_gamification exists. If this is not the case, either install PostgreSQL server or use the docker-compose provided. See "Docker support" section how to do that.

When PostgreSQL server is ready, proceed with the commands below to get started. Following steps require working db connection, take care to setup the URL properly and with correct credentials.

  1. npm i
  2. Setup local env vars - execute is terminal:
export POSTGRE_SQL_USER=<PG_USER>
export POSTGRE_SQL_PASS=<PG_PASS>
export POSTGRE_SQL_DATABASE=<HOST&DB_NAME>
  1. npm run init-db
  2. npm run seed-db - optional step, assuming you want mock data for development.
  3. Set the local environment file - we keep a sample file with all vars one needs to have set to be able to run the API locally. Check the .env.sample, fill it with proper values, and finally rename it to .env.development.local. Done, vars will be picked-up on server start.
  4. npm run dev

Docker support

WIP

Migrations & Seeds

This project is using Umzug for running and rolling back tasks relted to db model migrations. The database could be programmatically modified throughout the life of the project so that the current state of the design can be arrived at by executing a series of migration scripts or calls.

We are writing migrations/seed in TypeScript. See ./src/db folder for more details. There are migrate.js & seed.js files which can be executed via node.js in terminal. Those file implement the Umzug API. As you may find, npm init-db and seed-db are proxy calls to Umzug.

For detailed info how to write migrations in TypeScript with Umzug see its documentation: https://github.com/sequelize/umzug#migrations

There is an example of our initial migration in the src/db/migrations/2022.08.02T14.28.51.init-db.ts file.

Here, what the migration does is:

  • Reads our SQL file with schema create statements and executes those via the .query(...SQL) API from Sequelize.
  • the down migration would drop all tables in the daatabase and restore to initial state if executed.

After completion it should look similar to:

For seeds, check the initial seeder as example: src/db/seeders/2022.08.02T15.25.48.init-mock-data.ts

  • for up it creates data in the tables
  • for down truncates the tables

After completion it should look similar to:

Note: here you get the ORG_ID which is needed later for requests to the API.

How to sync db models used by the Sequelize ORM with latest db structure?

When changes/migrations affect the database schema structure the ORM models need to reflect and update accordingly. We use an automated approach to solve this need. There is a tool in npm, named sequelize-auto which is installed as a dev dependency.

In project root type:

npm run sync-orm

This command will execute and update the typescript files in the src/db/models folder. Those are the ORM definitions used by Sequelize. Note that sequelize-auto has some issues and leaves unused variables defined. This could cause lint errors. Therefore we run sequelize-auto and after it we run npm run lint:fix for convenience but still you may need to do small work to clean up the generated code.

Assets Hosting

Badge images and asstest are hosted on AWS S3.

On PROD & DEV the bucket name is the same - tc_gamification.

We follow strict naming convention: org_id/badge_image_id.file_ext. This will ensure badge images are stored in folders per organization and are uniqie named.

This is public access bucket, which provides access to the digital assets used by the gamification project. All files are served with proper HTTP headers. We set CacheControl: 'max-age=31536000' (365 days) header to all badge images which ensures speed loading and reduces traffic.

Dependency security checks

Use the Node 24 version in .nvmrc and npm ci --install-links=true for a reproducible install. The explicit install option packages local compatibility dependencies with install-links=true; both Docker dependency stages pass the same option. The minimatch adapter preserves older tooling APIs while delegating matching to the maintained engine.

Run npm audit, npm run lint, npm run build, npm run build:tsc, npm test -- --runInBand, and npm run test:dependency-compat after updates. Compatibility tests cover callable glob matching, bounded adversarial patterns, and the bulk-badge CSV parser's normal input and prototype-safe headers.

The development and production deployment targets share the same minimal non-root runtime and patched, digest-pinned Node 24 / Alpine image.