Architecture d'ensemble

Cette fiche donne les repères nécessaires pour comprendre ce que vous hébergez : un seul conteneur applicatif, une base PostgreSQL, et un serveur SMTP. Elle ne couvre pas la marche à suivre pour installer ou déployer — voir la partie Installation pour cela.

Vue d'ensemble

flowchart LR
    Nav[Navigateur] -->|HTTP| C

    subgraph C["Conteneur TimePick — process Express (port 3000)"]
        SPA[Interface web<br/>fichiers statiques]
        API[API REST]
        UP[Fichiers uploadés<br/>logo, images d'email]
    end

    C -->|lecture/écriture| DB[(PostgreSQL)]
    C -->|email rendu en HTML| SMTP[[Serveur SMTP<br/>Gmail, Brevo, OVH, ou MailHog en dev]]

Le navigateur ne parle qu'à un seul point d'entrée. Ce même process sert l'interface, répond aux requêtes de l'API et distribue les fichiers uploadés. Il communique avec deux services externes : la base de données et un serveur SMTP.

Ce que vous hébergez, en résumé

• Un conteneur applicatif — interface, API et fichiers uploadés dans le même process.
• Une base PostgreSQL — toutes les données, y compris la configuration applicative.
• Un serveur SMTP — pour l'envoi des magic links et des notifications (aucun service tiers propriétaire requis).

Trois blocs de code, un seul déploiement

Le code source est organisé en monorepo (un seul dépôt Git, plusieurs paquets npm reliés entre eux). Cette organisation ne change rien à ce que vous hébergez — elle explique seulement pourquoi le dépôt contient plusieurs dossiers.

• client/ — l'interface web : React 19 et Vite 7. C'est ce que voient les utilisateurs dans leur navigateur (tableau de bord, calendrier de réservation, éditeur d'emails…). En production, ce dossier est compilé en fichiers statiques (HTML/CSS/JS) qui n'ont plus besoin de Node.js pour s'exécuter.
• server/ — l'API : Express 5, qui gère l'authentification, les réservations, l'envoi d'emails et l'accès à la base de données. C'est le seul bloc qui tourne réellement en continu en production.
• shared/ — un paquet interne de types et de constantes partagés entre client/ et server/ (par exemple les couleurs de la charte email). Il n'a pas d'existence autonome : il est compilé et intégré aux deux autres au moment du build.

Détail des dossiers et des sous-dossiers : voir README.md § Structure du projet dans le dépôt.

En développement : trois processus séparés

Sur un poste de développement, npm run dev lance trois processus en parallèle, chacun sur son propre port :

Processus	Rôle	Adresse
SHARED	recompile shared/ à chaque changement	— (pas de port)
CLIENT	serveur de développement Vite, rechargement à chaud	http://localhost:5173
SERVER	API Express	http://localhost:3000

Le navigateur parle alors à deux adresses distinctes (5173 pour l'interface, 3000 pour l'API). C'est un confort de développement uniquement : ce découpage disparaît en production.

En production : un seul conteneur

L'image Docker de production assemble tout en un seul process Express qui écoute sur le port 3000 :

• l'interface (client/) est compilée à l'avance (vite build) et ses fichiers statiques sont copiés dans le conteneur ; Express les sert directement comme n'importe quel fichier statique ;
• l'API et l'interface partagent donc la même origine (même domaine, même port) — plus de distinction 5173/3000 ;
• les fichiers uploadés (logo de l'organisation, images insérées dans les emails) sont écrits sur le disque du conteneur et distribués par ce même process.

URL de l'API figée au build

L'adresse de l'API (VITE_API_URL) est intégrée dans les fichiers de l'interface au moment de la compilation, pas au démarrage du conteneur. Un conteneur construit avec la mauvaise valeur ne peut pas être corrigé en changeant une variable d'environnement au lancement — il faut reconstruire l'image. Voir la fiche Installation en production (Docker).

Au démarrage, le conteneur applique lui-même les migrations de base de données avant de lancer le serveur (opération sans effet si elles sont déjà appliquées) — aucune commande manuelle séparée n'est nécessaire à chaque redémarrage.

La configuration vit en base de données

Contrairement à beaucoup d'applications, la plupart des réglages de TimePick (nom de l'organisation, paramètres SMTP, identité visuelle des emails, durées de session…) ne sont pas stockés dans un fichier de configuration sur le serveur : ils sont enregistrés dans une table de la base PostgreSQL et modifiables depuis l'interface d'administration.

Seule une poignée de valeurs — la connexion à la base elle-même, les clés de sécurité — reste dans des variables d'environnement fournies au conteneur au démarrage. Voir Variables d'environnement et Configuration initiale.

Les emails : rendu côté serveur, envoi par SMTP

TimePick ne dépend d'aucun service d'emailing tiers. Le contenu des emails (invitations, notifications) est composé au format MJML — un langage de mise en page pensé pour produire du HTML compatible avec la majorité des clients de messagerie — puis converti en HTML directement par le serveur au moment de l'envoi. Ce HTML est ensuite transmis à un serveur SMTP classique pour la distribution.

En développement, si aucun serveur SMTP n'est configuré, les emails partent automatiquement vers MailHog (un intercepteur local qui les affiche dans une interface web au lieu de les envoyer réellement) plutôt que d'échouer silencieusement. En production, un fournisseur SMTP réel doit être configuré — voir Fournisseurs SMTP.

Pour aller plus loin

• Qu'est-ce que TimePick ? — pour une vision fonctionnelle.
• Concepts et vocabulaire — pour le sens des termes métier.
• Prérequis — pour la liste des logiciels à installer avant de commencer.
• Détail technique du build (stages Docker, dépendances) : Dockerfile dans le dépôt.