# 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=Collecticity
  • PAYMENT_SERVICE_PROVIDER=MANGOPAY
  • ENV / NODE_ENV selon l’app CC
  • APP_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 si NODE_ENV=development : http://localhost:3001/graphql).
  • Schéma : backend/graphql/typeDefs/types/Query.graphql et Mutation.graphql.
  • Proxy front : le Nuxt frontend relaie /graphql vers API_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 (selon PLATFORM_NAME) + CSS Element généré (npm run element:themes si 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_PASSWORD du .env backend (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é button dans ~/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')