# 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`](../adastra_app) — an Angular 21 standalone app. It calls this API exclusively through relative paths prepended with `environment.apiBaseUrl`.

## Getting started

```bash
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:**
```bash
npm run setup:api
# Runs: db:migrate → seed roles → create:user → seed articles
```

**Manual steps:**
```bash
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:**
```bash
npx sequelize-cli db:migrate:status
npx sequelize-cli db:migrate:undo:all
```

**Seeder helpers:**
```bash
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/`](docs/):

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