From 59401b3c85bd946339fab216ccaa4901cccc5693 Mon Sep 17 00:00:00 2001 From: Julien Gautier Date: Mon, 27 Apr 2026 23:10:49 +0200 Subject: [PATCH] docs: README update --- README.md | 166 +++++++++++++++++++++++++++++++++++++++++------------- 1 file changed, 126 insertions(+), 40 deletions(-) diff --git a/README.md b/README.md index 7657645..be6f710 100644 --- a/README.md +++ b/README.md @@ -1,67 +1,153 @@ -# AdAstra_API +# AdAstra API -API pour l'application Ad Astra +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 -**Installation rapide** ```bash -# Initialisation (applique les migrations, seed roles → création admin interactive → seed articles) -# La commande suivante applique d'abord les migrations nécessaires. +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 ``` -**Installation manuelle** +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 `. +- `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 -# Appliquer les migrations npx sequelize-cli db:migrate - -# Exécuter le seeder des articles npx sequelize-cli db:seed --seed 20251126-add-roles.js - -# Créer un utilisateur Admin npm run create:user - -# Exécuter le seeder des articles npx sequelize-cli db:seed --seed 20251127-add-articles.js ``` -**Migration** +**Migration helpers:** ```bash -# Appliquer les migrations -npx sequelize-cli db:migrate - -# Voir le statut des migrations npx sequelize-cli db:migrate:status - -# Annuler les migrations npx sequelize-cli db:migrate:undo:all ``` -**Seeder** +**Seeder helpers:** ```bash -# Exécuter tous les seeders npx sequelize-cli db:seed:all - -# Exécuter un seeder spécifique npx sequelize-cli db:seed --seed 20251127-add-articles.js - -# Annuler tous les seeders npx sequelize-cli db:seed:undo:all - -# Annuler un seeder spécifique npx sequelize-cli db:seed:undo --seed 20251127-add-articles.js ``` -**Start 'local' API server** -```bash -# Appliquer les migrations -npm run local +## Documentation -# Exécuter le seeder des articles -npx sequelize-cli db:seed --seed 20251126-add-roles.js +Extended references are in [`docs/`](docs/): -# Créer un utilisateur Admin -npm run create:user - -# Exécuter le seeder des articles -npx sequelize-cli db:seed --seed 20251127-add-articles.js -``` \ No newline at end of file +| 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 |