adastra_api/README.md

AdAstra API

Backend of the AdAstra platform — an Express REST API serving four feature domains: CMS, e-commerce, skydive club management, and Hero Wars guild analytics.

Tech stack

Layer	Choice
Runtime	Node.js ^16.20.2 || ^18.19.1 || ^20.11.1
Framework	Express 4
MySQL ORM	Sequelize 6
MongoDB ODM	Mongoose 6
Auth	Passport (local strategy) + JWT (express-jwt / jsonwebtoken)
Validation	express-validator
Security	Helmet, express-rate-limit, CORS
Tests	Jest + Supertest, Postman/Newman
Dev server	Nodemon

Related repository

The frontend lives in adastra_app — an Angular 21 standalone app. It calls this API exclusively through relative paths prepended with environment.apiBaseUrl.

Getting started

npm install

# Copy the example env file for your environment
cp config/env/.env.example config/env/.env.local
# Edit .env.local: MYSQL_DBNAME, MYSQL_DBUSER, MYSQL_DBPASS, SECRET, …

# Initialize the database (migrate + seed roles + create admin user + seed articles)
npm run setup:api

# Start the dev server
npm run local

The server listens on SERVER_PORT (default 3200).

Commands

Command	Description
npm start	Production server (APP_ENV=production)
npm run dev	Development server, uses .env.development
npm run local	Local server with Nodemon, uses .env.local
npm test	Jest unit + integration tests
npm run test:postman	Newman / Postman collection run
npm run create:user	Interactive admin user creation script
npm run stop	Kill the process on port 3200

Environment

Environment files live in config/env/ and are loaded by dotenv at startup based on APP_ENV:

File	Used when
.env.local	npm run local
.env.development	npm run dev
.env.production	npm start

Copy .env.example to create a new environment file. Key variables:

SERVER_PORT=3200
SECRET=                  # JWT signing secret
SESSION_SECRET=
MYSQL_DBNAME=
MYSQL_DBUSER=
MYSQL_DBPASS=
MONGODB_URI=
SENDGRID_API_KEY=        # optional — email sending
SKYDIVERID_API_URL=      # optional — skydiver ID external API
# TRUST_PROXY=1          # uncomment when behind a reverse proxy

Architecture

Route domains

All routes are mounted under /api and split into four domains:

Domain	Prefix	Resources
CMS	/api/cms	users, profiles, articles, comments, tags
E-commerce	/api/ecommerce	products
Skydive	/api/skydive	aeronefs, canopies, dropzones, jumps, pages, QCM, applications
Hero Wars	/api/herowars	clans, members

Middleware pipeline

Requests flow through:

1. Helmet — security headers
2. CORS — origin whitelist from ALLOWED_ORIGINS
3. Rate limiter — express-rate-limit
4. Body parser — JSON + URL-encoded
5. Passport — initializes local + header-API-key strategies
6. Route handlers — validators → auth middleware → controller → asyncHandler
7. Error handlers — 404 catcher, log handler, final error handler

Auth

• Session-less JWT: tokens are signed with SECRET and attached by the client as Authorization: Token <jwt>.
• auth.js middleware verifies the token via express-jwt and populates req.auth.
• Password storage: PBKDF2-SHA512 with a random 16-byte salt (no bcrypt dependency on the auth path).

Databases

• MySQL (Sequelize): users, roles, skydive entities, e-commerce, CMS content.
• MongoDB (Mongoose): Hero Wars guild/clan data and analytics snapshots.

Database — migrations & seeders

One-command setup:

npm run setup:api
# Runs: db:migrate → seed roles → create:user → seed articles

Manual steps:

npx sequelize-cli db:migrate
npx sequelize-cli db:seed --seed 20251126-add-roles.js
npm run create:user
npx sequelize-cli db:seed --seed 20251127-add-articles.js

Migration helpers:

npx sequelize-cli db:migrate:status
npx sequelize-cli db:migrate:undo:all

Seeder helpers:

npx sequelize-cli db:seed:all
npx sequelize-cli db:seed --seed 20251127-add-articles.js
npx sequelize-cli db:seed:undo:all
npx sequelize-cli db:seed:undo --seed 20251127-add-articles.js

Documentation

Extended references are in docs/:

File	Content
DEPLOYMENT.md	Full VPS production deployment guide (Apache, PM2, SSL)
ENVIRONMENT_VARIABLES.md	All env variables documented
SWAGGER_GUIDE.md	API documentation via Swagger UI
GITEA_INSTALL.md	Self-hosted Gitea on Debian 11 + ISPConfig