# Architecture
Collecticity Dons — plateforme de dons. Cette doc (Collecticidoc) est maintenue par Urbanis Finance.
Cloner : [email protected]:collecticity/don.git
Branche de travail : don-stage.
# Mono-repo
| Dossier | Rôle | Port local | Node |
|---|---|---|---|
backend/ | API Express + GraphQL + crons | 3001 | 16 (^16.13.1) |
frontend/ | Site public (Nuxt SSR) | 3000 | 16 |
admin/ | Dashboard admin (Nuxt) | 3002 | 16 |
common/ | Thème, logos (PLATFORM_NAME) | — | — |
docs/ | Ce site VuePress | 8080 en npm run dev | 14.15 au build CC |
Les 3 apps se parlent via APP_URL / API_URL / ADMIN_URL.
Installation locale : Démarrage.
# Staging
Hébergement Clever Cloud. URLs :
| App | URL | Alias CC |
|---|---|---|
| Frontend | https://app-don-stage.collecticity.fr | don-frontend-staging |
| Backend / API | https://api-don-stage.collecticity.fr | don-backend-staging |
| Admin | https://admin-don-stage.collecticity.fr | don-admin-staging |
Variables d’environnement typiques (staging) :
PLATFORM_NAME=CollecticityPAYMENT_SERVICE_PROVIDER=MANGOPAYENV/NODE_ENVselon l’app CCAPP_URL,API_URL= les URLs HTTPS ci-dessus
Déployer une app (depuis la machine, scripts locaux deploy-don.sh) :
cd frontend && sh deploy-don.sh staging # clever deploy -a don-frontend-staging -f
cd backend && sh deploy-don.sh staging
cd admin && sh deploy-don.sh staging
Jenkins (Jenkinsfile) tourne sur les commits ; le déploiement docs n’est pas activé (DEPLOY_DOC=no). La doc se déploie à part (docs/deploy-doc.sh, app don-docs).
# Backend
- Pile technique : Node 16, Express, Apollo GraphQL, MongoDB, sessions (
express-session+ MongoStore). - Entrée :
backend/bin/start.js— migrations puis serveur, puis crons. - Installation : voir Démarrage. Commandes :
cd backend && npm install && npm run dev(après.env). - API : un seul point d’entrée GraphQL
POST /graphql(et playground siNODE_ENV=development:http://localhost:3001/graphql). - Schéma :
backend/graphql/typeDefs/types/Query.graphqletMutation.graphql. - Proxy front : le Nuxt frontend relaie
/graphqlversAPI_URL(frontend/nuxt.config.js).
Le navigateur tape donc https://app-don-stage.collecticity.fr/graphql ; le SSR doit utiliser API_URL (backend).
Webhooks Mangopay : fichiers dans backend/routes/hooks/ (payIn, payOut, transfer, KYC, UBO, …). JSDoc du type GET /webhooks/mangopay/payin.
Crons : backend/crons/ — liste dans la référence API.
# Frontend (site public)
- Pile technique : Nuxt 2 (SSR), Vue 2, Vuex, Apollo, Element UI, nuxt-i18n, Stylus.
- Installation :
cd frontend && npm install && npm run dev(port 3000). - Config :
frontend/.env—APP_URL,API_URL,PLATFORM_NAME,PAYMENT_SERVICE_PROVIDER,S3_URL(Cellar), recaptcha / GMaps / Intercom, etc. (modèle :frontend/.env.example). - Thème :
common/Collecticity/theme(selonPLATFORM_NAME) + CSS Element généré (npm run element:themessi le thème change).
Parcours donateur : pages contribution / paiement (CB, virement, chèque). Le workflow de création jusqu’à clôture d’une campagne est dans le guide projets.
# Admin
- Pile technique : Nuxt 2, Apollo, Element UI.
- Installation :
cd admin && npm install && npm run dev(port 3002). - Config :
admin/.env—API_URL,APP_URL,PLATFORM_NAME,ADMIN_EMAIL/ADMIN_PASSWORD, PSP. - Connexion admin : mot de passe
ADMIN_PASSWORDdu.envbackend (création du compte admin via migration / seed).
# Variables d’environnement (commun)
À coller dans chaque .env concerné :
| Variable | Rôle |
|---|---|
PLATFORM_NAME | Collecticity |
PAYMENT_SERVICE_PROVIDER | MANGOPAY |
APP_URL | Frontend (http://localhost:3000 en local) |
API_URL | Backend (http://localhost:3001) |
ADMIN_URL | Admin (backend surtout) |
MONGODB_URL / MONGODB_DATABASE | Mongo (backend) |
SESSION_SECRET | Sessions backend |
MANGOPAY_* | API sandbox / prod Mangopay |
MAILGUN_* / EMAIL_FROM | E-mails |
CELLAR_ADDON_HOST / CELLAR_ADDON_KEY_ID / CELLAR_ADDON_KEY_SECRET | Cellar (stockage fichiers, backend) |
S3_BUCKET | Nom du bucket Cellar (parfois encore un bucket Amazon) |
S3_URL | URL publique des fichiers (frontend, relais /s3) |
Ne pas committer les .env (secrets). Copier depuis les .env.example.
# Terminologie
| Terme | Sens |
|---|---|
| Donateur / Contributor | Personne ou organisation qui donne |
| Porteur de projet / Project owner | Organisation qui porte une campagne |
| Contribution / Don | Don (carte, virement ou chèque) |
| Campagne / Collecte | Projet de collecte publique |
# Technologies & services
- Runtime des apps : Node.js 16, npm 8
- Front / admin : Nuxt, Vue, Vuex, Apollo, Element UI
- Backend : Express, GraphQL, MongoDB, AJV, ESLint
- Paiement : Mangopay (opens new window)
- E-mail : Mailgun (opens new window)
- Fichiers : Cellar (opens new window) (Clever Cloud, API compatible S3) — c’est le stockage habituel. Amazon S3 reste possible ponctuellement (anciennes URLs / migration). Le client est dans
backend/utils/s3.js(CELLAR_ADDON_*+S3_BUCKET, URLs*.cellar-c2.services.clever-cloud.com). - Hébergement : Clever Cloud (opens new window)
- CI : Jenkins (
Jenkinsfile) - Autres souvent configurés : reCAPTCHA, Google Maps, Intercom, Mailchimp
# Fichiers statiques plateforme
Logos etc. : common/$PLATFORM_NAME/static → servis en $HOST/logo.svg (ex. common/collecticity/static/logo.svg). Cache long (1 an) ; changer le hash du nom de fichier pour invalider (logo.[hash].svg). Config : middleware dans frontend/nuxt.config.js.
# Thèmes
Chaque plateforme a un thème dans common/$PLATFORM_NAME/theme.
C’est là que sont définis couleurs, polices, breakpoints, etc. Importer common/getTheme.js pour obtenir dynamiquement un objet avec toutes les variables :
import getTheme from "common/getTheme";
const theme = getTheme(process.env.PLATFORM_NAME);
console.log(theme);
/*
sortie :
{
borderRadius: {},
breakpoints: {},
colors: {},
fonts: {},
transitions: {}
}
*/
TIP
Cet objet est injecté dans l’application Nuxt : this.$theme
# Thème Element UI du frontend
Pour coller à l’identité de la plateforme, un thème Element UI personnalisé est généré. Ce thème écrit en Sass étend le thème par défaut d’Element UI (theme-chalk (opens new window)).
Le point d’entrée se trouve dans frontend/assets/styles/element-ui/index.scss.
Element UI expose un jeu de variables surchargeables. La liste est dans ce fichier (opens new window).
Nos variables custom sont dans frontend/assets/styles/element-ui/custom/variables.scss. Comme le thème d’origine, elles sont préfixées par --.
On génère un fichier CSS par plateforme : dès que le thème change, il faut les régénérer :
cd frontend
npm run element:themes
Cette commande utilise Gulp pour produire un CSS par plateforme dans le dossier element-ui. La tâche du gulpfile charge du JSON comme variables Sass, afin de prendre le bon thème. Chaque fichier CSS porte le nom de la plateforme. Celui de la plateforme courante est ensuite importé dynamiquement dans nuxt.config.js.
TIP
Le thème change rarement : pour gagner du temps au build, on le génère à part avec Gulp.
# Objets
En plus du thème d’origine, des objets CSS ont été créés. Ce sont des ensembles de styles réutilisables et abstraits, définis avec des placeholders Sass (opens new window).
Tous les objets sont préfixés par -o- pour rester identifiables.
Ils se trouvent dans frontend/assets/styles/element-ui/custom/objects/.
WARNING
Les placeholders Sass ne sont pas rendus en CSS. On les utilise pour ne pas injecter les styles de l’objet à chaque import — ce serait trop lourd.
Pour utiliser un objet hors SCSS (dans le HTML par exemple), créer le sélecteur de classe qui étend le placeholder dans ~/assets/styles/element-ui/custom/objects/index.scss :
@import "./{PATH_TO_OBJECT}";
.-o-my-object {
@extends -o-my-object;
}
# Ajouter un objet
Exemple : ajouter l’objet de layout container.
Placer le placeholder dans ~/assets/styles/element-ui/custom/objects/layout.scss
%-o-container {
padding-left: 2rem;
padding-right: 2rem;
}
# Utiliser un objet
@import "./{PATH_TO_OBJECT}";
.my-selector {
@extend %-o-title-2;
}
# Mixins
# Breakpoints
Le mixin res-spec sert aux media queries :
.my-selector {
// Ce style ne s’applique qu’aux appareils xs
@include res-spec(xs-only) {
padding-right: 50px;
}
}
TIP
La liste des clés est ici (opens new window)
⚠️ Les breakpoints sont définis dans le thème de la plateforme.
# Composants
Les composants Element UI sont écrits avec la syntaxe BEM (opens new window). Ils utilisent les mixins b, e, m (Bloc, Élément, Modificateur). On suit les mêmes règles.
# Surcharger le style d’un composant
Pour surcharger el-button :
- Créer un fichier nommé
buttondans~/assets/styles/element-ui/custom/components/. - Ajouter ce commentaire en tête de fichier :
// Custom style for Button // src: https://github.com/ElementUI/theme-chalk/blob/master/src/button.scss - Importer ce qu’il faut (variables, mixins)
- Ajouter le style custom en suivant la structure du fichier d’origine :
@include b(button) { // préfixe `el-` ajouté automatiquement // style custom }
TIP
Avant de surcharger un composant, vérifier qu’on ne peut pas simplement modifier des variables.
# Variables de thème dans Stylus
On peut importer des fichiers JSON comme variables Stylus. Une variable $platform-theme (chemin du thème courant) est injectée dans le loader Stylus. Pour importer un JSON :
json($platform-theme + '/colors.json')