Negli ambienti multi-tenant ad alta scala, gestire decine di attività in background eterogenee — dagli audit QA automatizzati alla scoperta di lead commerciali, fino all'instradamento di email OAuth e alla sincronizzazione dei contenuti — diventa rapidamente insostenibile quando viene affidato a cron job non coordinati o script bash isolati. Senza un framework di orchestrazione centralizzato, i processi a lunga esecuzione rischiano di generare processi orfani, saturare i core della CPU e operare senza alcuna osservabilità in tempo reale.

Per risolvere questa sfida architetturale abbiamo progettato Job Runner v2.0: una piattaforma ad alto throughput in Node.js e TypeScript basata su un'architettura modulare a plugin. Definendo interfacce di sottosistema fortemente tipizzate, Job Runner ha consolidato tre motori di automazione precedentemente separati — QA Watchdog, Lead Hunter e Article Sync — in un'unica piattaforma osservabile e isolata a livello di processo sul nodo worker dedicato (192.168.11.18:8084).

1. Il Problema degli Script in Background Frammentati

Prima del consolidamento sotto un orchestratore unificato, ciascuno strumento operativo funzionava nel proprio silo:

• QA Watchdog: Avviava spider Playwright headless autonomi per rilevare link 404, verificare i moduli di contatto dinamici e ispezionare gli schemi JSON-LD su oltre 130 domini.
• Lead Hunter: Eseguiva cicli di scoperta multi-step sui registri aziendali regionali, inviava comunicazioni tramite Google Gmail API e sincronizzava i contatti con Frappe CRM.
• Article Sync e Indicizzazione SEO: Eseguiva routine pianificate per sincronizzare i file JSON con MongoDB Atlas e inviare gli URL agli endpoint IndexNow.

Quando venivano eseguiti tramite sessioni SSH scollegate o cron di sistema standard, promise rejection non gestite o bug nei parser potevano bloccare la CPU al 100% a tempo indeterminato.

2. L'Architettura Modulare a Plugin in TypeScript

Job Runner v2.0 risolve il problema astraendo ogni dominio operativo in un modulo tipizzato sotto src/modules/ tramite un contratto dichiarativo unificato:

export interface JobDef {
  key: string;
  name: string;
  description: string;
  queue: 'qa' | 'lead-hunter' | 'seo' | 'maintenance' | 'social';
  bin: 'node' | 'bash';
  script: string;
  cwd: string;
  baseArgs: string[];
  schedule?: string;
  retries: number;
  logFile: string;
}

A. Integrazione di QA-Watchdog (src/modules/qa/)

Tutte le suite di test automatizzati sono state migrate come spider TypeScript nativi: 404 Fast Spider (qa:spider), Contact Form Liveness (qa:contact-forms), Static Asset Auditor (qa:asset-audit) e SEO Schema Validator (qa:seo-audit) su oltre 3.400 articoli pubblicati.

B. Integrazione di Lead-Hunter (src/modules/marketing/)

Il motore di outreach commerciale opera attraverso una cascata deterministica in cinque fasi: scoperta PMI regionali, audit delle regressioni tecniche (SSL assente, LCP elevato, viewport mancante), deduplicazione in Frappe CRM v15 via REST API, invio tramite microservizio OAuth Google Gmail sulla porta 8085 e tracciamento automatico dei bounce.

C. Integrazione di Article Sync e Motore di Contenuti Versionato (src/modules/content/)

La sincronizzazione dei contenuti adotta il dual-writing atomico tra shard JSON, database SQLite delle revisioni (data/revisions.db) e MongoDB, con snapshot immutabili (v1 → v2) e notifiche istantanee a IndexNow.

3. Isolamento dei Processi POSIX e Telemetria Grafana/Loki

Per prevenire la saturazione della CPU e i processi orfani, Job Runner applica due invarianti di stabilità fondamentali:

• Sandboxing dei Gruppi di Processi (-pid): Quando un job viene arrestato o supera il timeout, Job Runner invia SIGTERM / SIGKILL all'ID negativo del gruppo di processi (process.kill(-child.pid, 'SIGTERM')), garantendo la terminazione pulita di tutti i processi figli (incluse le istanze Chromium headless).
• Telemetria Dual-Push: Tutti i log e le metriche del ciclo di vita vengono inviati a Prometheus e Promtail/Loki, alimentando dashboard Grafana in tempo reale sui nodi .32 e .18.

4. Conclusione

Unendo validazione QA, automazione marketing e sincronizzazione dei contenuti in un'architettura modulare a plugin, abbiamo trasformato script in background fragili in un motore di automazione enterprise resiliente e completamente osservabile.