docs: README update
This commit is contained in:
@@ -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 <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**
|
||||
```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
|
||||
```
|
||||
| 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 |
|
||||
|
||||
Reference in New Issue
Block a user