Guide de developpement

Ce document vous guidera pour installer, configurer et developper Arrhes sur votre machine locale.

Table des matieres

Choix de l'environnement
Prerequis
Installation
Configuration
Initialisation de la base de donnees
Lancement en developpement
Structure du projet
Scripts disponibles
Workflow de developpement
Debugging
Conseils

Choix de l'environnement

Vous avez deux options pour developper Arrhes :

Option 1 : Developpement avec Docker Compose (Recommande)

Avantages :

Configuration simplifiee (pas d'installation de PostgreSQL, RustFS, etc.)
Environnement standardise et reproductible
Isolation complete des services
Node.js et pnpm installes localement (meilleure performance IDE)

Prerequis :

Node.js 25+
pnpm
Docker et Docker Compose

Ideal pour : Developpement quotidien, bonne balance performance/simplicite

Option 2 : Developpement natif

Avantages :

Controle total sur chaque service
Peut etre plus rapide sur certaines machines
Pas besoin de Docker

Prerequis :

Node.js 25+
pnpm
PostgreSQL installe localement
Optionnellement Docker pour RustFS et Mailpit

Ideal pour : Developpeurs experimentes, personnalisation avancee

Prerequis

Prerequis communs

Node.js : Version 25 ou superieure
```
node --version  # Devrait afficher v25.x.x ou superieur
```
Installation : https://nodejs.org/

pnpm : Version 10 ou superieure

pnpm --version

Installation :

npm install -g pnpm
# ou
curl -fsSL https://get.pnpm.io/install.sh | sh -

Option 1 : Avec Docker Compose

Docker et Docker Compose : https://www.docker.com/get-started
```
docker --version
docker compose version
```

C'est tout ! PostgreSQL, RustFS et Mailpit seront lances automatiquement dans des containers.

Option 2 : Developpement natif

PostgreSQL : Version 14 ou superieure recommandee

psql --version

Installation :

Ubuntu/Debian :

sudo apt update
sudo apt install postgresql postgresql-contrib
sudo systemctl start postgresql

macOS :

brew install postgresql@16
brew services start postgresql@16

Windows : Telecharger depuis https://www.postgresql.org/download/windows/

Docker (optionnel, pour RustFS et Mailpit) : https://www.docker.com/get-started
Ou configurez des services S3 et SMTP alternatifs

Installation

Etape 1 : Cloner le repository

git clone https://github.com/arrhes/application.git
cd application

Etape 2 : Installer les dependances

pnpm install

Cette commande installera toutes les dependances de tous les packages du monorepo.

Etape 3 : Verifier l'installation

pnpm ls --depth=0

Vous devriez voir tous les packages workspace listes.

Configuration

Option 1 : Configuration avec Docker Compose (Recommande)

1. Lancer les services avec just (recommande)

just dev up

Ou directement avec Docker Compose :

docker compose -f .workflows/dev/compose.yml up -d --build

Les services seront disponibles sur :

PostgreSQL : localhost:5432 (user: postgres, password: admin, database: default)
RustFS API : localhost:9000
RustFS Console : http://localhost:9001 (credentials: rustfsadmin / rustfsadmin)
Mailpit SMTP : localhost:1025
Mailpit Web : http://localhost:8025

2. Creer le bucket RustFS

Accedez a la console RustFS : http://localhost:9001

Credentials : rustfsadmin / rustfsadmin
Creez un bucket nomme arrhes-files

3. Creer les fichiers de configuration

packages/api/.env :

# Environnement
ENV=development
VERBOSE=true
PORT=3000

# CORS et Cookies
CORS_ORIGIN=http://localhost:5173
COOKIES_DOMAIN=localhost
COOKIES_KEY=development-secret-key-change-in-production-min-32-chars

# URLs
API_BASE_URL=http://localhost:3000
WEBSITE_BASE_URL=http://localhost:5173

# Base de donnees (Docker Compose)
SQL_DATABASE_URL=postgres://postgres:admin@localhost:5432/default

# Stockage RustFS (Docker Compose)
STORAGE_ENDPOINT=http://localhost:9000
STORAGE_BUCKET_NAME=arrhes-files
STORAGE_ACCESS_KEY=rustfsadmin
STORAGE_SECRET_KEY=rustfsadmin

# Email Mailpit (Docker Compose)
EMAIL_ENDPOINT=localhost:1025
EMAIL_USER=test
EMAIL_PASSWORD=test

packages/tools/.env :

DATABASE_URL=postgres://postgres:admin@localhost:5432/default

Option 2 : Configuration native

1. Creer la base de donnees PostgreSQL

# Se connecter a PostgreSQL
sudo -u postgres psql

# Dans le shell PostgreSQL :
CREATE USER arrhes_user WITH PASSWORD 'arrhes_password';
CREATE DATABASE arrhes OWNER arrhes_user;
GRANT ALL PRIVILEGES ON DATABASE arrhes TO arrhes_user;
\q

2. Configurer les services externes (optionnel)

RustFS (Stockage de fichiers) :

# Lancer RustFS avec Docker
docker run -d \
  -p 9000:9000 \
  -p 9001:9001 \
  --name rustfs \
  -e "RUSTFS_ACCESS_KEY=rustfsadmin" \
  -e "RUSTFS_SECRET_KEY=rustfsadmin" \
  -e "RUSTFS_CONSOLE_ENABLE=true" \
  -e "RUSTFS_VOLUMES=/data" \
  -v ~/rustfs/data:/data \
  rustfs/rustfs:latest

# Acceder a la web UI : http://localhost:9001
# Creer un bucket nomme "arrhes-files"

Mailpit (Test d'emails) :

# Lancer Mailpit avec Docker
docker run -d -p 1025:1025 -p 8025:8025 axllent/mailpit

# Interface web : http://localhost:8025

3. Creer les fichiers de configuration

Utilisez les memes fichiers .env que dans l'Option 1, en ajustant les credentials PostgreSQL selon votre configuration.

Pour plus de details sur la configuration, consultez CONFIGURATION.md.

Initialisation de la base de donnees

Pour le developpement local (hors Docker)

Etape 1 : Pousser le schema vers la base de donnees

pnpm --filter tools run push

Cette commande cree toutes les tables necessaires dans PostgreSQL a partir des schemas definis dans @arrhes/application-metadata.

Etape 2 : Seed avec des donnees de demonstration

pnpm --filter tools run seed

Cette commande insere :

Un utilisateur de demonstration : demo@arrhes.com / demo
Une organisation exemple : "Arrhes"
Des comptes comptables de base
Des journaux
Des ecritures comptables d'exemple pour 2022 et 2023
Des documents et etats financiers

Etape 3 : Reinitialiser la base (si necessaire)

Pour tout supprimer et recommencer :

pnpm --filter tools run reset

Cette commande execute : clear + push + seed

Avec Docker Compose

Pour reinitialiser la base de donnees dans l'environnement Docker :

just dev reset

Ou manuellement :

docker compose -f .workflows/dev/compose.yml exec api sh -c "cd /workspace/packages/tools && pnpm run reset"

Lancement en developpement

Commande principale

pnpm run dev

Cette commande lance simultanement :

API sur http://localhost:3000
Website (Dashboard) sur http://localhost:5173

Les deux processus tournent en parallele avec hot-reload active.

Lancer individuellement (optionnel)

Dans des terminaux separes :

Terminal 1 - API :

pnpm --filter api run dev

Terminal 2 - Website :

pnpm --filter website run dev

Terminal 3 - Metadata (optionnel, watch mode) :

pnpm --filter metadata run dev

Acces a l'application

Frontend (Dashboard) : http://localhost:5173
API : http://localhost:3000
RustFS Console : http://localhost:9001 (rustfsadmin / rustfsadmin)
Mailpit Web UI : http://localhost:8025

Identifiants de demonstration

Email    : demo@arrhes.com
Password : demo

Notes par option

Docker Compose :

Assurez-vous que les services sont lances : docker compose -f .workflows/dev/compose.yml ps
Si les services ne sont pas demarres : just dev up

Natif :

Assurez-vous que PostgreSQL est demarre
Si vous utilisez RustFS/Mailpit avec Docker, verifiez qu'ils tournent : docker ps

Structure du projet

arrhes/
├── packages/
│   ├── api/                    # Backend API (@arrhes/application-api)
│   │   ├── src/
│   │   │   ├── api.ts         # Configuration Hono
│   │   │   ├── server.ts      # Point d'entree
│   │   │   ├── clients/       # Clients services externes
│   │   │   ├── factories/     # Factories Hono typees
│   │   │   ├── middlewares/   # Auth, validation, etc.
│   │   │   ├── routes/        # Routes API
│   │   │   │   ├── auth/      # Routes authentifiees
│   │   │   │   └── public/    # Routes publiques
│   │   │   ├── validators/    # Validation des donnees
│   │   │   └── utilities/     # Utilitaires
│   │   ├── .env               # Variables d'environnement
│   │   ├── package.json
│   │   └── tsconfig.json
│   │
│   ├── website/               # Frontend React (@arrhes/application-website)
│   │   ├── src/
│   │   │   ├── root.tsx       # Point d'entree React
│   │   │   ├── index.html     # HTML principal
│   │   │   ├── assets/        # CSS, images, manifest
│   │   │   ├── components/    # Composants UI reutilisables
│   │   │   ├── contexts/      # React contexts
│   │   │   ├── features/      # Features par domaine
│   │   │   │   ├── dashboard/ # Dashboard (organisations, settings, support)
│   │   │   │   ├── docs/      # Documentation integree
│   │   │   │   ├── website/   # Site vitrine
│   │   │   │   ├── signIn/    # Connexion
│   │   │   │   └── signUp/    # Inscription
│   │   │   ├── routes/        # Definition routes
│   │   │   └── utilities/     # Utilitaires
│   │   ├── package.json
│   │   ├── tsconfig.json
│   │   └── vite.config.ts
│   │
│   ├── metadata/               # Schemas et types partages (@arrhes/application-metadata)
│   │   ├── src/
│   │   │   ├── models/        # Modeles Drizzle ORM
│   │   │   ├── schemas/       # Schemas Valibot
│   │   │   ├── routes/        # Definitions routes API
│   │   │   ├── components/    # Composants metier
│   │   │   └── utilities/     # Utilitaires
│   │   ├── package.json
│   │   └── tsconfig.json
│   │
│   ├── ui/                     # Composants UI partages (@arrhes/ui)
│   │   ├── src/
│   │   │   ├── components/    # Boutons, layouts, etc.
│   │   │   ├── fonts/         # Polices
│   │   │   ├── styles/        # CSS
│   │   │   └── utilities/     # cn, sleep
│   │   ├── package.json
│   │   └── panda.config.ts
│   │
│   └── tools/                  # Outils base de donnees (@arrhes/application-tools)
│       ├── src/
│       │   ├── clearDB.ts     # Vider la DB
│       │   ├── migrate.ts     # Migrations
│       │   ├── schemas.ts     # Import schemas
│       │   ├── dbClient.ts    # Client DB
│       │   ├── drizzle.config.ts  # Config Drizzle Kit
│       │   └── seed/          # Scripts de seed
│       ├── .env               # Variables d'environnement
│       └── package.json
│
├── .workflows/                  # Docker configurations
│   ├── .dev/                   # Environnement Docker de developpement
│   │   ├── compose.yml
│   │   └── packages/
│   │       ├── api/            # Dockerfile + .env de dev
│   │       ├── dashboard/      # Dockerfile + .env du frontend
│   │       └── tools/          # .env des outils
│   └── .build/                 # Configuration Docker de production et CI
│       ├── compose.yml
│       └── packages/
│           ├── api/
│           ├── ci/             # Dockerfile pour le pipeline CI local (just build)
│           └── dashboard/
│
├── docs/                       # Documentation
│   ├── ARCHITECTURE.md
│   ├── BUSINESS_MODEL.md
│   ├── CONFIGURATION.md
│   ├── CONTRIBUTING.md
│   └── DEVELOPMENT.md
│
├── justfile                    # Commandes just (dev up/down/reset/logs, build)
├── biome.json                  # Configuration Biome (linter + formatter)
├── pnpm-workspace.yaml         # Configuration workspace
├── package.json                # Scripts racine
├── LICENSE
└── README.md

Scripts disponibles

Scripts racine (depuis `/`)

# Lancer API + Website en developpement
pnpm run dev

# Builder tous les packages
pnpm run build

# Verifier le linting et le formatage (Biome)
pnpm check

# Corriger automatiquement le linting et le formatage
pnpm check:fix

Commandes just

# Demarrer l'environnement Docker de developpement
just dev up

# Arreter l'environnement
just dev down

# Reinitialiser la base de donnees
just dev reset

# Voir les logs
just dev logs

# Lancer le pipeline CI en local (Biome check + build, dans Docker)
just build

Scripts API (`packages/api/`)

# Developpement avec hot-reload
pnpm --filter api run dev

# Build pour production
pnpm --filter api run build

# Lancer en production (apres build)
pnpm --filter api run start

Scripts Website (`packages/website/`)

# Developpement avec hot-reload
pnpm --filter website run dev

# Build pour production
pnpm --filter website run build

Scripts Metadata (`packages/metadata/`)

# Build avec watch mode
pnpm --filter metadata run dev

# Build une fois
pnpm --filter metadata run build

Scripts Tools (`packages/tools/`)

# Generer les migrations depuis le schema
pnpm --filter tools run generate

# Pousser le schema vers la DB (dev)
pnpm --filter tools run push

# Introspecter le schema de la DB
pnpm --filter tools run pull

# Appliquer les migrations (production)
pnpm --filter tools run migrate

# Seed avec donnees de demo
pnpm --filter tools run seed

# Vider completement la DB
pnpm --filter tools run clear

# Reset complet : clear + push + seed
pnpm --filter tools run reset

# Supprimer les migrations
pnpm --filter tools run drop

Workflow de developpement

Developpement typique

Avec Docker Compose

Lancer les services
```
just dev up
```
Lancer l'application (dans un terminal separe si necessaire)
```
pnpm run dev
```
Developper avec hot-reload
- Modifications dans packages/api/src/ : Rechargement automatique de l'API
- Modifications dans packages/website/src/ : HMR (Hot Module Replacement)
- Modifications dans packages/metadata/src/ : Necessite rebuild (ou mode watch)
Arreter les services (a la fin de la session)
```
just dev down
```

Avec installation native

Lancer les services externes

# PostgreSQL (si pas demarre)
sudo systemctl start postgresql

# RustFS (si utilise avec Docker)
docker start rustfs

# Mailpit (si utilise avec Docker)
docker start mailpit

Lancer l'application
```
pnpm run dev
```
Developper avec hot-reload
- Modifications dans packages/api/src/ : Rechargement automatique de l'API
- Modifications dans packages/website/src/ : HMR (Hot Module Replacement)
- Modifications dans packages/metadata/src/ : Necessite rebuild (ou mode watch)

Modifier le schema de base de donnees

Modifier les modeles dans packages/metadata/src/models/
Rebuild metadata
```
pnpm --filter metadata run build
```
Generer la migration (optionnel, pour production)
```
pnpm --filter tools run generate
```

Appliquer les changements

# Developpement : push direct
pnpm --filter tools run push

# Production : migrations
pnpm --filter tools run migrate

Mettre a jour le seed si necessaire dans packages/tools/src/seed/

Ajouter une nouvelle route API

Creer la definition de route dans packages/metadata/src/routes/

// packages/metadata/src/routes/auth/myFeature.ts
import { routeDefinition } from '#src/utilities/routeDefinition.js'
import * as v from 'valibot'

export const myFeatureRoute = routeDefinition({
    path: '/api/auth/my-feature',
    paramsSchema: v.object({ /* ... */ }),
    bodySchema: v.object({ /* ... */ }),
    responseSchema: v.object({ /* ... */ }),
})

Creer l'implementation dans packages/api/src/routes/auth/

// packages/api/src/routes/auth/myFeature.ts
import { myFeatureRoute } from '@arrhes/application-metadata/routes'
import { authFactory } from '#/factories/authFactory.js'

export const myFeature = authFactory.createApp().post(
    myFeatureRoute.path,
    async (c) => {
        // Implementation
        return c.json({ /* ... */ })
    }
)

Enregistrer la route dans packages/api/src/routes/routes.ts
Utiliser cote frontend dans packages/website/src/utilities/postAPI.ts

Ajouter une nouvelle page

Creer le composant dans packages/website/src/features/
Definir la route dans packages/website/src/routes/root/
Mettre a jour le tree dans le fichier tree correspondant (ex: dashboardTree.ts, docsTree.ts)
Ajouter la navigation si necessaire dans les layouts

Debugging

API (Backend)

Logs verbeux :

VERBOSE=true

Debugger Node.js :

Modifier packages/api/package.json :

{
  "scripts": {
    "dev:debug": "tsx watch --inspect --env-file=.env ./src/server.ts"
  }
}

Lancer :

pnpm --filter api run dev:debug

Attacher le debugger dans VS Code avec cette configuration (.vscode/launch.json) :

{
  "type": "node",
  "request": "attach",
  "name": "Attach to API",
  "port": 9229,
  "skipFiles": ["<node_internals>/**"]
}

Website (Frontend)

Console du navigateur :

Ouvrir DevTools (F12)
Voir les erreurs, warnings, et logs

React DevTools :

Installer l'extension React DevTools
Inspecter les composants et leur state

TanStack Query DevTools : Deja integre dans l'application, visible en bas de l'ecran en mode dev.

Base de donnees

Inspecter la DB :

# Avec Docker Compose
psql postgres://postgres:admin@localhost:5432/default

# Avec installation native
psql postgres://arrhes_user:arrhes_password@localhost:5432/arrhes

Commandes SQL utiles :

-- Lister les tables
\dt

-- Voir le schema d'une table
\d table_name

-- Compter les enregistrements
SELECT COUNT(*) FROM users;

-- Voir les derniers enregistrements
SELECT * FROM users ORDER BY "createdAt" DESC LIMIT 10;

Drizzle Studio (GUI pour visualiser la DB) :

pnpm dlx drizzle-kit studio --config=packages/tools/src/drizzle.config.ts

Conseils

Performance

Hot-reload lent ? Redemarrez le serveur de developpement
Build lent ? Verifiez que Node.js est a jour
pnpm lent ? Nettoyez le cache : pnpm store prune

Problemes courants

"Cannot connect to database" :

Avec Docker : Verifiez que les containers sont lances : docker compose -f .workflows/dev/compose.yml ps
Natif : Verifiez que PostgreSQL est demarre : sudo systemctl status postgresql
Testez la connexion : psql postgres://postgres:admin@localhost:5432/default
Verifiez les credentials dans .env

"Module not found @arrhes/application-metadata" :

Rebuild metadata : pnpm --filter metadata run build
Ou lancez en mode watch : pnpm --filter metadata run dev

"CORS error" :

Verifiez CORS_ORIGIN dans packages/api/.env
Assurez-vous que l'URL correspond exactement

"Cookie not set" :

Verifiez COOKIES_DOMAIN (doit etre localhost en dev)
Verifiez que l'API et le frontend sont sur le meme domaine

"S3/Storage error" :

Verifiez que RustFS est demarre : docker ps | grep rustfs
Verifiez que le bucket existe (console : http://localhost:9001)
Testez l'endpoint : curl http://localhost:9000

Problemes Docker :

Port deja utilise : Un autre service utilise le meme port

# Voir ce qui utilise le port 5432 (PostgreSQL)
sudo lsof -i :5432

Container ne demarre pas : Voir les logs

docker compose -f .workflows/dev/compose.yml logs postgres
docker compose -f .workflows/dev/compose.yml logs rustfs
docker compose -f .workflows/dev/compose.yml logs mailpit

Reinitialiser completement :

docker compose -f .workflows/dev/compose.yml down -v
docker compose -f .workflows/dev/compose.yml up -d --build

Bonnes pratiques

Commits atomiques : Un commit = une fonctionnalite/fix
Messages de commit clairs : Suivez les conventions (voir CONTRIBUTING.md)
Tester avant de commit : Lancez just build pour verifier le linting et la compilation
Suivre les patterns existants : Regardez le code existant pour rester coherent
Documenter les changements : Commentaires pour la logique complexe

Ressources utiles

Hono : https://hono.dev/
Drizzle ORM : https://orm.drizzle.team/
Valibot : https://valibot.dev/
TanStack Router : https://tanstack.com/router/
TanStack Query : https://tanstack.com/query/
Radix UI : https://www.radix-ui.com/
Panda CSS : https://panda-css.com/

Pour contribuer au projet, consultez CONTRIBUTING.md.

FilesExpand file tree

DEVELOPMENT.md

Latest commit

History

DEVELOPMENT.md

File metadata and controls

Guide de developpement

Table des matieres

Choix de l'environnement

Option 1 : Developpement avec Docker Compose (Recommande)

Option 2 : Developpement natif

Prerequis

Prerequis communs

Option 1 : Avec Docker Compose

Option 2 : Developpement natif

Installation

Etape 1 : Cloner le repository

Etape 2 : Installer les dependances

Etape 3 : Verifier l'installation

Configuration

Option 1 : Configuration avec Docker Compose (Recommande)

1. Lancer les services avec just (recommande)

2. Creer le bucket RustFS

3. Creer les fichiers de configuration

Option 2 : Configuration native

1. Creer la base de donnees PostgreSQL

2. Configurer les services externes (optionnel)

3. Creer les fichiers de configuration

Initialisation de la base de donnees

Pour le developpement local (hors Docker)

Avec Docker Compose

Lancement en developpement

Commande principale

Lancer individuellement (optionnel)

Acces a l'application

Identifiants de demonstration

Notes par option

Structure du projet

Scripts disponibles

Scripts racine (depuis /)

Commandes just

Scripts API (packages/api/)

Scripts Website (packages/website/)

Scripts Metadata (packages/metadata/)

Scripts Tools (packages/tools/)

Workflow de developpement

Developpement typique

Avec Docker Compose

Avec installation native

Modifier le schema de base de donnees

Ajouter une nouvelle route API

Ajouter une nouvelle page

Debugging

API (Backend)

Website (Frontend)

Base de donnees

Conseils

Performance

Problemes courants

Bonnes pratiques

Ressources utiles

Scripts racine (depuis `/`)

Scripts API (`packages/api/`)

Scripts Website (`packages/website/`)

Scripts Metadata (`packages/metadata/`)

Scripts Tools (`packages/tools/`)