docs: README update

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)
+npm install
-# La commande suivante applique d'abord les migrations nécessaires.
+
+# 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 <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
-# 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**
+## Documentation
-```bash
-# Appliquer les migrations
-npm run local
 
-# Exécuter le seeder des articles
+Extended references are in [`docs/`](docs/):
-npx sequelize-cli db:seed --seed 20251126-add-roles.js
 
-# Créer un utilisateur Admin
+| File | Content |
-npm run create:user
+|---|---|
-
+| [DEPLOYMENT.md](docs/DEPLOYMENT.md) | Full VPS production deployment guide (Apache, PM2, SSL) |
-# Exécuter le seeder des articles
+| [ENVIRONMENT_VARIABLES.md](docs/ENVIRONMENT_VARIABLES.md) | All env variables documented |
-npx sequelize-cli db:seed --seed 20251127-add-articles.js
+| [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 |