Business modules

The backend is organized around vertical business slices. Each slice has a Nest module, controller, service, repository, DTO file, and usually a live-DB e2e.ts slice.

Core / Client / Abonnement

Core (src/core)

Global key/value parameters in core.parametre.

Route	Permission
GET /api/v1/core/parametres	CORE.VOIR
POST /api/v1/core/parametres	CORE.CREER
PUT /api/v1/core/parametres/:cle	CORE.MODIFIER

Client (src/client)

Single client referential. DTOs support identity documents (piece_identite) and emergency contacts (contact_urgence).

Route	Permission
GET /api/v1/client/clients	CLIENT.VOIR
POST /api/v1/client/clients	CLIENT.CREER
PATCH /api/v1/client/clients/:id	CLIENT.MODIFIER
POST /api/v1/client/clients/:id/pieces-identite	CLIENT.MODIFIER

ClientRepository.nextClientCode produces GSG-CL-NNN by casting the numeric suffix, avoiding lexicographic rollover past 999.

Abonnement (src/abonnement)

Subscription categories only (abonnement.categorie_abonnement).

Route	Permission
GET /api/v1/abonnement/categories	ABONNEMENT.VOIR
POST /api/v1/abonnement/categories	ABONNEMENT.CREER
PATCH /api/v1/abonnement/categories/:id	ABONNEMENT.MODIFIER
DELETE /api/v1/abonnement/categories/:id	ABONNEMENT.SUPPRIMER

Residence

The ResidenceModule (src/residence/) is the reference implementation of the project’s architecture: buildings, rooms, lease contracts, rent instalments, rebilled utilities, short stays, subscriptions, inventory photos, and a resident portal.

Sub-modules

Sub-module	Files	Scope
Buildings	batiments.*	Multi-building referential
Rooms	logements.*	Rental inventory, numbering
Contracts / rent	residence.*	Lease contracts, instalments, deposits, PDFs
Charges	charges.*	Rebilled utilities
Short stays	sejours.*	Night/rest stays
Subscriptions	abonnements.*	Recurring services
Portal	portail.*	Read-only resident space
Inventory	etat-lieux.*	Move-in/move-out photos

Key routes

Route	Permission	Purpose
POST /api/v1/residence/contrats	RESIDENCE.CREER	Create contract
POST /api/v1/residence/contrats/:id/activer	RESIDENCE.MODIFIER	EN_ATTENTE → ACTIF
POST /api/v1/residence/contrats/:id/resilier	RESIDENCE.MODIFIER	ACTIF → RESILIE
POST /api/v1/residence/echeances/:id/encaisser	FINANCES.CREER	Single instalment collection
POST /api/v1/residence/contrats/:id/encaisser-loyer-lot	FINANCES.CREER	Bulk collection
GET /api/v1/residence/suivi	RESIDENCE.VOIR	Rent tracking view
GET /api/v1/residence/impayes	RESIDENCE.VOIR	Overdue/partial view
GET /api/v1/residence/occupation	RESIDENCE.VOIR	Occupancy per building

State machines

Entity	States
contrat_location	EN_ATTENTE, ACTIF, RESILIE, TERMINE
logement	DISPONIBLE, RESERVE, OCCUPE, EN_NETTOYAGE, EN_MAINTENANCE, INDISPONIBLE
charge_facturee	IMPAYEE, PARTIELLE, PAYEE
sejour_court	EN_COURS, TERMINE, ANNULE
abonnement	ACTIF, SUSPENDU, RESILIE, EXPIRE

Resident portal

GET /api/v1/residence/portail/* is protected by RESIDENT.VOIR. All queries are scoped to AuthUser.idClient. Routes include:

• resume
• echeances and echeances/:id/recu/pdf
• etat-des-lieux and etat-des-lieux/:id/photo
• paiements and paiements/:id/recu/pdf
• caution

Commercial modules

All commercial modules use SettlementService from FacturationModule to create or settle facturation.facture rows.

Market (src/market)

Domain	Tables
Catalogue	categorie_produit, fournisseur, produit
Stock	mouvement_stock (trigger owns quantite_stock)
Sales	vente, ligne_vente

quantite_stock is never written directly; it is computed by trg_mouvement_stock_solde. Manual movements are ENTREE, SORTIE, AJUSTEMENT.

Pressing (src/pressing)

Order lifecycle: DEPOSE → EN_TRAITEMENT → PRET → RETIRE / ANNULEE.

• Deposit may include an advance (acompte) that creates a PARTIELLE COMMANDE_PRESSING invoice.
• Pickup (retirer) settles the balance on the same invoice.
• Cancellation is only possible before any invoice exists.

Restaurant (src/restaurant)

Order lifecycle:

EN_COURS → EN_PREPARATION → SERVIE → PAYEE / ANNULEE

Orders are fully paid at creation. Status transitions are enforced by TRANSITIONS_COMMANDE_STATUT.

Salle de fête (src/salle_fete)

Reservation lifecycle: RESERVEE → CONFIRMEE → REALISEE / ANNULEE.

• confirmer collects an advance and creates a PARTIELLE RESERVATION_FETE invoice.
• realiser collects the balance on the same invoice.
• disponibilites returns occupied slots for a given date.

Facturation and Finances

Facturation (src/facturation)

• Prestations (prestations)
• Invoices (factures, factures/:id/pdf, factures/:id/ticket)
• SettlementService exported for all commercial modules
• FacturationRepository.prochainNumeroFacture produces GSG-FAC-YYYY-NNN

SettlementService.settle resolves an activity, creates/reads an invoice, applies a payment, and returns the trigger-recomputed montant_total, montant_paye, reste, statut.

Finances (src/finances)

Domain	Main tables
Payments	paiement, application_paiement
Expenses	depense, categorie_depense
Cash drawers	caisse, periode_caisse, tirage
Payment methods	moyen_paiement
Consolidation	views ca_par_activite, tableau_de_bord

Cash-drawer rules:

• creerPaiement / creerDepense require an open periode_caisse for the chosen caisse.
• creerTirage computes montant_attendu from encaissements − décaissements − dépenses and emits a HIGH notification if ecart !== 0.

RH and Dashboard

RH (src/rh)

Entity	Routes
Services	services
Employees	employes
Attendance	pointages, pointages/:id/depart
Payroll	paies, paies/:id/elements, paies/:id/recalculer, paies/:id/valider, paies/:id/payer

• heure_arrivee and duree_travaillee are trigger-owned.
• Payroll totals are recomputed by trg_element_salaire_paie.
• BulletinPdfService generates payslip PDFs.

Dashboard (src/dashboard)

Aggregated tiles for the executive dashboard and per-activity dashboards. Reuses RapportsModule and DashboardRepository. Output formats: json, pdf, xlsx.

Audit, Rapports, Uploads, Jobs

Audit (src/audit)

Read-only access to audit.journal_audit. Supports JSON, PDF, and XLSX reports. POST /api/v1/audit/masquer masks sensitive fields such as mot_de_passe before display.

Rapports (src/rapports)

Read-only aggregation endpoints:

• /api/v1/rapports/synthese-globale
• /api/v1/rapports/financier
• /api/v1/rapports/activites/:code
• /api/v1/rapports/rh
• /api/v1/rapports/series

CSV / Excel serialization uses ; delimiter and recursively flattens nested JSON.

Uploads (src/uploads)

• POST /api/v1/uploads — multipart upload of file + categorie
• GET /api/v1/uploads?key=... — download object bytes

Categories: client-photo, piece-identite, plat-photo, etat-lieux, produit-photo.

Jobs (src/jobs)

Cron / BullMQ seam. Cron schedule examples:

Job	Cron	Purpose
generer-echeances	12 2 * * *	Generate rent instalments
recalculer-paie	41 4 1 * *	Recalculate payroll
reesolde-stock	23 3 * * *	Recompute market stock
transition-contrats-expires	30 2 * * *	Expire finished contracts
sauvegarde-auto	* * * * *	Trigger scheduled backups

Manual trigger routes are under POST /api/v1/jobs/*.