Architecture

Le dépôt est un monorepo : une SPA React 19 + Vite + TypeScript et une API Express qui agrège les flux publics de vulnérabilités. Le SPA ne parle jamais directement à NVD ou OSV ; tout le trafic sortant passe par le serveur pour centraliser clés, cache et limites.

Ce chapitre mappe dossiers et responsabilités, décrit le flux scan/veille via les handlers et pointe vers OpenAPI servi à l'exécution.

Topologie haut niveau

flowchart LR
  classDef ui fill:#e9edf5,stroke:#00baba,color:#253343
  classDef api fill:#f3fcfc,stroke:#008c8c,color:#253343
  classDef ext fill:#fff7ed,stroke:#eda232,color:#253343

  Browser[Browser SPA]:::ui --> API[Express /api]:::api
  API --> NVD[NVD]:::ext
  API --> OSV[OSV]:::ext
  API --> GH[GitHub]:::ext
  API --> CISA[CISA KEV]:::ext
  API --> RSS[RSS]:::ext

Parcours du diagramme

Le navigateur persiste pile, locale et bascules de sources dans localStorage, puis appelle POST /api/scan ou POST /api/watch. La couche API valide les corps JSON, invoque scanStack dans server/services/scan.ts et renvoie les vulnérabilités fusionnées. La logique par fournisseur est sous server/services/ ; la déduplication partagée dans server/lib/merge.ts ; l'enrichissement traduction dans server/services/enrich.ts.

Chemin de requête (scan complet)

1. server/routes/scan.ts reçoit POST /scan.
2. server/handlers/scanHandlers.ts parse le corps via stackValidation.ts.
3. scanStack résout sources intégrées et flux RSS personnalisés activés.
4. Fetch parallèles par outil terminés ; fusion et tri.
5. enrichVulnsWithTranslations optionnel si translate: true.
6. JSON ScanResponse au client ; persistLastScan dans src/lib/scanCache.ts écrit cve-radar:last-scan avec une clé pile.

Couche base de données (PostgreSQL optionnel)

Quand DATABASE_URL est défini, les métadonnées de scan persistent dans PostgreSQL via server/db/scanHistory.ts et les piles tenant via server/db/tenants.ts. Les migrations SQL dans server/db/migrations/*.sql s'exécutent automatiquement au démarrage du pool.

Les définitions de schéma type-safe pour la migration ORM progressive vivent dans server/db/schema.ts (Drizzle ORM). server/db/drizzle.ts expose getDb() via le pool pg partagé. La persistance tenant et scan-history (server/db/tenants.ts, server/db/scanHistory.ts) utilise les query builders Drizzle ; les migrations SQL dans server/db/migrations/*.sql s'exécutent toujours au démarrage du pool.

Services de notification

Les alertes serveur en mode veille utilisent server/services/notifications/NotificationService.ts. Les adaptateurs de canal (Slack, Discord, Telegram, SMTP, webhook générique) lisent les env documentés dans Configuration. server/services/alerts.ts délègue au service pour compatibilité avec ALERT_WEBHOOK_URL.

Couche de contrat partagée

Types et ordre de sévérité dans shared/ (shared/api/vulnerability.ts, shared/constants/severityOrder.ts). src/ et server/ importent via @shared/* ; server/types.ts re-export pour compatibilité. npm run build:server compile shared/ dans dist-server/.

Couche API

Module	Rôle
server/index.ts	App Express, montage routeurs
server/routes/health.ts	GET /health
server/routes/meta.ts	capabilities, sources, openapi.json
server/routes/scan.ts	scan, watch, scan/validate
server/routes/v1.ts	Montage versionné des mêmes handlers
server/routes/translateLocale.ts	POST /translate
server/handlers/scanHandlers.ts	Logique scan/watch/validate partagée
server/openapi/spec.json	Contrat OpenAPI 3.1

Les chemins legacy restent sous /api/* ; les intégrations devraient préférer /api/v1/* (voir Référence API).

Carte frontend

Zone	Chemin
Shell	src/components/layout/AppShell.tsx, SubNav.tsx, SetupWizard.tsx
Onglets	src/components/tabs/*
Cache scan	src/lib/scanCache.ts
Client API	src/api/scan.ts, watch.ts, scanPayload.ts
i18n	src/i18n/messages/*.ts
Hooks	useVulnScan, useWatch, useVulnTranslations, useFontScale
Middleware	server/middleware/rateLimit.ts, scanTimeout.ts

Services backend (flux)

Fournisseur	Module
NVD	server/services/nvd.ts
OSV	server/services/osv.ts
GitHub	server/services/github.ts
CISA KEV	server/services/cisa.ts
RSS	server/services/rss.ts
Traduction	server/services/translate.ts

Cache et limites

Cache mémoire (server/lib/cache.ts) pour XML RSS et chaînes de traduction. Délai NVD depuis server/lib/rateLimit.ts (cadence upstream). Limites de débit des requêtes scan/veille appliquées dans server/middleware/rateLimit.ts (buckets séparés ; validate exempt). Résultats de scan côté client persistés dans localStorage via scanCache.ts. Capacités via GET /api/capabilities reflètent les limites dures des validateurs (50 outils, 20 flux personnalisés).

Suite : Alertes