Architecture

Pulse ERP est une mono-app Nuxt 4 full-stack : un seul processus Node.js sert à la fois le rendu SSR et l'API Nitro REST. Pas de microservices, pas de message broker au départ — on n'y vient que si un besoin opérationnel le justifie.

Stack technique

Frontend — choix clés

Backend — choix clés

Architecture en couches

Route API   server/api/**/*.ts
  │  parse Zod · vérif permission · appel service
  ▼
Service     server/services/*.service.ts
  │  logique métier · transactions Prisma · audit log · events / jobs
  ▼
Repository  server/repositories/*.repository.ts
  │  Prisma pur — aucun métier, aucun side-effect
  ▼
PostgreSQL

DTO pattern

Les schémas Zod dans shared/dto/ sont la source de vérité du contrat API. Le type TypeScript est inféré du schéma, jamais défini à part.

// shared/dto/asset.dto.ts
export const AssetCreateDto = z.object({
  label: z.string().min(1).max(120),
  modelId: z.string().uuid(),
  conditionState: z.enum(['NEW', 'EXCELLENT', 'GOOD', 'NEEDS_REPAIR']),
})
export type AssetCreateDto = z.infer<typeof AssetCreateDto>

Côté composable, on importe le type :

import type { AssetDto } from '~/../shared/dto/asset.dto'
export function useWorkspaceAssets() {
  return useFetch<AssetDto[]>('/api/workspace/assets')
}

Structure du repo (monorepo pnpm)

PROJET-ERP-CRM-v2/
├── app/
│   ├── pulse/              ← application Nuxt ERP/CRM
│   │   ├── app/            # pages · layouts · composables · components · middleware
│   │   ├── server/         # api · services · repositories · lib · middleware · jobs
│   │   ├── shared/         # DTO Zod, enums, helpers purs (app ↔ server)
│   │   ├── prisma/         # schema.prisma · migrations/ · seed.ts
│   │   ├── i18n/locales/   # fr.json · en.json
│   │   └── tests/          # unit/ · integration/ · e2e/
│   └── docs/               ← site de documentation (projet séparé)
└── pnpm-workspace.yaml

Portails applicatifs

Patterns transverses

Multi-tenant — isolation systématique

Toute entité business porte organizationId NOT NULL. Trois lignes de défense :

1. DB : index composite (organizationId, …) sur toutes les requêtes ; FK vers Organization.
2. Repository : prend organizationId en paramètre, l'injecte dans la clause where. Pas de surcharge possible.
3. Service : lit organizationId depuis session.activeOrganizationId, jamais depuis le body.

Audit log

Chaque mutation sensible journalise dans AuditLog (append-only, rétention 10 ans) :

await auditLog({
  actorId: session.user.id,
  organizationId: tenant.id,
  action: 'lease_contract.unlock',
  targetType: 'LeaseContract',
  targetId: contractId,
  payload: { reason, previousStatus },
  ip: getRequestIP(event),
})

Gestion des erreurs

defineApiHandler attrape les classes d'erreur et sérialise une réponse uniforme :

{
  "error": {
    "code": "CONFLICT",
    "message": "Le numéro de série existe déjà",
    "details": { "field": "serialNumber" },
    "requestId": "01HXY..."
  }
}

Un intercepteur $fetch côté frontend mappe ces erreurs vers un toast.

State machines (workflows multi-étapes)

Les workflows complexes (cycle de vie affaire LLD, processus SAV) utilisent des state machines explicites dans server/services/*.workflow.ts avec une table de transitions validées. Chaque changement d'état émet un événement métier qui peut déclencher notifications, jobs asynchrones et audit log.

Jobs & cron

croner schedule les jobs définis dans server/jobs/. Chaque exécution est tracée dans la table Job (statut PENDING → RUNNING → SUCCEEDED / FAILED, max 5 tentatives, idempotence par clé de payload).

Conventions de code

Naming

Conventional Commits

Enforced par Husky + commitlint. Format : <type>(<scope>): <description>.

Types : feat fix chore docs refactor test perf build ci.

Scopes : auth identity annuaire assets crm sales lease catalog files notif admin ai ui db infra docs.

Tests

Règle fondamentale : chaque nouveau .service.ts → un .integration.test.ts dans tests/integration/. Utiliser createTenantFixture() de tests/helpers/tenant-isolation.ts, seed dans try {}, nettoyage dans finally { await fx.cleanup() }.

Avant toute PR :

pnpm test && pnpm test:integration && pnpm lint && pnpm typecheck

Sécurité & déploiement

Sécurité

• Auth : Better Auth — sessions cookie HttpOnly Secure SameSite=Lax, MFA TOTP, magic link.
• Headers : security-headers.ts injecte HSTS, CSP, X-Frame-Options DENY, Permissions-Policy.
• Rate limiting : token bucket — 5 req/min/IP sur POST /api/auth/*, 300 req/min/session sur GET /api/*.
• Secrets : aucun dans le repo ; .env ignoré par git ; rotation API keys tous les 90 j.
• RGPD : hébergement Scaleway fr-par, anonymisation (User.anonymizedAt), export données /api/account/data-export.

Environnements

Migrations DB

Stratégie zero-downtime : colonne d'abord nullable → déploiement code → backfill → NOT NULL en migration suivante. Ne jamais supprimer de fichier sous prisma/migrations/.

CI/CD

• ci.yml (sur PR) : lint + typecheck + unit + build.
• e2e.yml (nightly) : Playwright sur staging.
• deploy-prod.yml (manuel) : promotion image staging → prod + migrations + smoke tests + rollback automatique si healthcheck KO.