Contribuer & Architecture

Ce guide est destiné aux développeurs souhaitant contribuer à Gäld ou comprendre son architecture interne.

Environnement de développement

Docker (recommandé)

git clone https://github.com/Scanix/Gaeld.git
cd Gaeld/api
cp .env.example .env
docker compose up -d
docker compose exec laravel.test php artisan gaeld:install --demo

L'application est disponible sur http://localhost:8080. Le flag --demo injecte des données d'exemple (factures, dépenses, contacts) pour le développement.

Services démarrés par Docker Compose :

Service	Conteneur	Port
Laravel (PHP + Nginx)	laravel.test	8080
PostgreSQL 16	pgsql	5432
Redis 7	redis	6379
MeiliSearch	meilisearch	7700
Mailpit (email dev)	mailpit	8025 (dashboard), 1025 (SMTP)

Exécution des commandes

Toutes les commandes PHP doivent être exécutées dans le conteneur Docker :

# Commandes Artisan
docker compose exec laravel.test php artisan <commande>

# Composer
docker compose exec laravel.test composer <commande>

# PHPStan
docker compose exec laravel.test ./vendor/bin/phpstan analyse

# Tests
docker compose exec laravel.test php artisan test

Frontend

Le projet API utilise Inertia.js + Vue 3 pour son interface d'administration :

pnpm install
pnpm dev    # Serveur dev Vite avec HMR
pnpm build  # Build de production

Vue d'ensemble de l'architecture

Stack technique

Couche	Technologie
Backend	Laravel 12, PHP 8.4
Frontend	Vue 3 + Inertia.js
Base de données	PostgreSQL 16
Cache/Queue/Session	Redis 7
Recherche	MeiliSearch (fallback : base de données)
Calcul monétaire	BCMath (chaînes, jamais de flottants)

Structure orientée domaine

Le code est organisé en domaines sous app/Domains/, chacun encapsulant une capacité métier :

app/Domains/
├── Accounting/      # Plan comptable, grand livre, écritures, TVA, budget
├── Api/             # Contrôleurs REST API, ressources, webhooks
├── Assets/          # Immobilisations et amortissements
├── Banking/         # Comptes bancaires, import CAMT, rapprochement
├── Contacts/        # Clients, fournisseurs, personnes de contact
├── Expenses/        # Enregistrement des dépenses, catégories, workflow
├── Invoicing/       # Factures, notes de crédit, factures récurrentes, paiements
├── Migration/       # Import de données depuis un logiciel externe
├── Organizations/   # Multi-tenancy, paramètres organisation, onboarding
├── Payroll/         # Employés, fiches de salaire, déductions suisses
├── Reporting/       # Rapports financiers, exports
└── Users/           # Authentification, profils, 2FA, passkeys

Multi-tenancy

Gäld utilise un modèle de base de données partagée avec isolation au niveau des lignes :

• Chaque table de données possède une clé étrangère organization_id
• Le trait BelongsToOrganization ajoute un scope global qui filtre automatiquement les requêtes
• Le service CurrentOrganization contient l'organisation active pour la requête en cours
• Le middleware EnsureHasOrganization résout l'organisation depuis la session (web) ou le token (API)

Feature Flags

Les fonctionnalités sont contrôlées via des variables d'environnement FEATURE_* :

Flag	Par défaut	Description
FEATURE_BANK_SYNC	false	Connexion bancaire et synchronisation
FEATURE_AUTO_RECONCILIATION	false	Rapprochement automatique des paiements
FEATURE_API_ACCESS	false	Accès à l'API REST
FEATURE_MULTI_CURRENCY	false	Support multi-devises

Tests

Gäld dispose de trois suites de tests :

# Exécuter tous les tests
docker compose exec laravel.test php artisan test

# Exécuter une suite spécifique
docker compose exec laravel.test php artisan test --testsuite=Feature
docker compose exec laravel.test php artisan test --testsuite=Unit
docker compose exec laravel.test php artisan test --testsuite=Security

Suite	Emplacement	But
Feature	tests/Feature/	Tests d'intégration — requêtes HTTP, base de données
Unit	tests/Unit/	Tests unitaires isolés — services, modèles
Security	tests/Security/	Tests de sécurité — auth, permissions, CSRF

Analyse statique

docker compose exec laravel.test ./vendor/bin/phpstan analyse

Style de code

docker compose exec laravel.test ./vendor/bin/pint

Workflow de contribution

1. Forkez le dépôt et créez une branche depuis main
2. Configurez l'environnement de développement
3. Effectuez vos modifications — gardez chaque PR focalisée sur un seul sujet
4. Ajoutez des tests pour tout nouveau comportement
5. Exécutez les vérifications avant de pousser :

   docker compose exec laravel.test php artisan test
   docker compose exec laravel.test ./vendor/bin/phpstan analyse
   docker compose exec laravel.test ./vendor/bin/pint --test

6. Ouvrez une pull request avec une description claire

Pour les changements importants, ouvrez d'abord une issue pour discuter de l'approche.

Signaler des problèmes

Ouvrez une issue sur GitHub avec :

• Un titre et une description clairs
• Les étapes de reproduction (en cas de bug)
• Le comportement attendu vs observé
• Votre environnement (version PHP, OS, navigateur)