Flux & Séquences

But & portée¶

Ce document décrit les chemins majeurs end-to-end de SalamBot à travers des séquences Mermaid. Il couvre les flux critiques pour les canaux Facebook, WhatsApp et Webchat, avec leurs contrôles, erreurs et SLO. Les détails d'API sont documentés dans API/reference.md.

Acteurs & conventions¶

Acteurs principaux¶

• Channel : Ingestion des messages (Facebook, WhatsApp, Webchat, Email)
• API Gateway : Point d'entrée, authentification, rate limiting
• Orchestrateur : Coordination des flux, routage intelligent
• NLU : Analyse d'intention et entités
• Recherche (RAG) : Récupération de contexte pertinent
• LLM Router : Génération de réponses via modèles
• Ticketing : Gestion des escalades
• Incident : Détection et alertes
• Admin : Politiques et configurations
• Observabilité : Métriques et traces
• Stores : PostgreSQL, Qdrant, MinIO

Envelope I/O standard¶

{
  "schema_version": "1.0",
  "tenant": "acme",
  "channel": "facebook",
  "message_id": "msg_123",
  "correlation_id": "corr_abc",
  "timestamp": "2025-08-14T10:00:00Z",
  "locale": "fr-MA",
  "data": { "NOTE": "payload spécifique" }
}

Traces¶

Propagation du correlation_id bout-à-bout pour traçabilité complète.

Flux #1 — Facebook Comment → DM (Auto-réponse ou Escalade)¶

sequenceDiagram
    autonumber
    participant FB as Facebook
    participant GW as API Gateway
    participant SI as Social
    participant ORC as Orchestrateur
    participant NLU as NLU
    participant RAG as RAG
    participant LLM as LLM Router
    participant TK as Ticketing

    FB->>GW: Webhook comment
    GW->>SI: normalize
    SI-->>ORC: message
    ORC->>NLU: Analyze intent
    NLU->>ORC: Intent + confidence

    alt confidence >= seuil
        ORC->>RAG: Retrieve context
        RAG-->>ORC: Context data
        ORC->>LLM: Generate response
        LLM->>ORC: Response text
        ORC->>FB: Send DM
    else confidence < seuil
        ORC->>TK: Create ticket
        TK->>ORC: Ticket created
        ORC->>FB: Escalation DM
    end

Points de contrôle¶

• Validation signature Facebook webhook
• Vérification HMAC/sha256 + tolérance horloge ±5 min (webhook)
• Limite taille texte (4000 chars)
• Isolation tenant stricte
• Vérification rate limits

Événements émis¶

SLO par flux¶

Erreurs/Timeouts clés¶

• 400 invalid_input : Payload malformé
• 401 unauthorized : absence ou invalidité d'auth côté gateway
• 403 permission_denied : signature invalide / interdit
• 429 rate_limited : Dépassement quotas
• 504 timeout : RAG/LLM indisponible

Flux #2 — WhatsApp → Incident/Broadcast (détection et alerte)¶

sequenceDiagram
    autonumber
    participant WA as WhatsApp
    participant GW as API Gateway
    participant ORC as Orchestrateur
    participant NLU as NLU
    participant INC as Incident
    participant NOT as Notification

    WA->>GW: Message client
    GW->>ORC: Route message
    ORC->>NLU: Analyze urgency
    NLU->>ORC: Intent + urgency

    alt urgency = high
        ORC->>INC: Trigger incident
        INC->>NOT: Send alerts
        NOT->>INC: Delivery ack
        INC->>ORC: Incident opened
    end

Points de contrôle¶

• Seuils d'alerte configurables
• Prévention spam incidents : max 1 / 5 min / tenant
• Prévention spam broadcasts : max 1 / 5 min / tenant
• Validation urgence NLU

Événements émis¶

SLO par flux¶

Erreurs/Timeouts clés¶

• 400 invalid_input (payload invalide)
• 403 permission_denied (règles/politiques)
• 429 rate_limited
• 504 timeout

Flux #3 — Webchat → Réponse contrainte par politiques (Admin)¶

sequenceDiagram
    autonumber
    participant WC as Webchat
    participant GW as API Gateway
    participant ORC as Orchestrateur
    participant ADM as Admin
    participant RAG as RAG
    participant LLM as LLM Router

    WC->>GW: User message
    GW->>ORC: Route message
    ORC->>ADM: Get policies
    ADM->>ORC: Active rules

    opt context needed
        ORC->>RAG: Retrieve docs
        RAG->>ORC: Context data
    end

    ORC->>LLM: Generate (+ policies)
    LLM->>ORC: Filtered response
    ORC->>WC: Stream response

Points de contrôle¶

• Respect langue sortie (fr-MA)
• Tokens max selon policy max_tokens (Admin)
• Filtrage contenu sensible
• Validation politiques tenant

Événements émis¶

SLO par flux¶

Erreurs/Timeouts clés¶

• 400 invalid_input
• 429 rate_limited
• 500 internal_error

Idempotency & replays¶

• Idempotency-Key au niveau API Gateway
• Réexécution safe sur NLU/RAG/Router si même (tenant, channel, message_id)
• Cache réponses 24h pour rejeu exact

Sécurité & PII par flux¶

• PII masking au bord (ingestion)
• Validation Orchestrateur avant traitement
• Rétention 30–90 jours configurable par tenant
• Chiffrement en transit et au repos

Observabilité — traces & logs¶

Corrélation¶

Unique via correlation_id propagé dans tous les services.

Champs de log clés¶

• tenant, channel, message_id, correlation_id
• latency_ms, status_code, error_type
• nlu_confidence, rag_docs_count, llm_tokens

Attributs de trace OTel¶

• service.name, trace_id, span_id

Références¶

• Concepts/architecture
• Concepts/composants
• API/reference