Aller au contenu

Architecture (C4 + Flux + Données & Sécurité)

Contexte

SalamBot adopte une architecture modulaire multi-tenant axée sur l'observabilité et la souveraineté des données. L'objectif est de fournir une plateforme conversationnelle évolutive capable de traiter simultanément plusieurs canaux de communication tout en maintenant l'isolation des données par tenant. L'architecture privilégie la séparation des responsabilités entre les couches de traitement, l'intelligence artificielle et les services métier pour garantir la maintenabilité et la scalabilité.

Vue C4 — Contexte & Conteneurs

flowchart TD
    classDef channel fill:#3b82f6,stroke:#1e40af,stroke-width:2px,color:#ffffff
    classDef gateway fill:#10b981,stroke:#047857,stroke-width:2px,color:#ffffff
    classDef ai fill:#f59e0b,stroke:#d97706,stroke-width:2px,color:#ffffff
    classDef service fill:#8b5cf6,stroke:#7c3aed,stroke-width:2px,color:#ffffff
    classDef data fill:#ef4444,stroke:#dc2626,stroke-width:2px,color:#ffffff
    classDef obs fill:#6b7280,stroke:#374151,stroke-width:1px,color:#ffffff

    subgraph Canaux
        FB[Facebook]:::channel
        WA[WhatsApp]:::channel
        WC[Webchat]:::channel
        EM[Email]:::channel
    end

    subgraph Edge
        GW[API Gateway]:::gateway
        OR[Orchestrateur]:::gateway
    end

    subgraph IA
        NLU[NLU]:::ai
        RAG[Recherche]:::ai
        LLM[LLM Router]:::ai
    end

    subgraph Services
        INC[Incident]:::service
        ESC[Escalade]:::service
        ADM[Admin]:::service
    end

    subgraph Donnees[Données]
        PG[(PostgreSQL)]:::data
        QD[(Qdrant)]:::data
        S3[(MinIO)]:::data
    end

    OBS[Observabilité]:::obs

    FB --> GW
    WA --> GW
    WC --> GW
    EM --> GW
    GW --> OR
    OR --> NLU
    NLU --> RAG
    RAG --> LLM
    OR -.-> INC
    OR -.-> ESC
    OR -.-> ADM
    RAG <--> QD
    OR <--> PG
    LLM -.-> S3
    OR -.-> OBS
    LLM -.-> OBS

Flux clé — Facebook Comment → DM

sequenceDiagram
    participant FB as Facebook
    participant GW as API Gateway
    participant OR as Orchestrateur
    participant NLU as NLU
    participant RAG as Recherche
    participant LLM as LLM Router
    participant PG as PostgreSQL

    FB->>GW: Webhook comment
    GW->>OR: Validation + routage
    OR->>NLU: Analyse linguistique
    NLU->>RAG: Intent + entités
    RAG->>RAG: Recherche contextuelle
    RAG->>LLM: Contexte + prompt
    LLM->>OR: Réponse générée
    OR->>FB: Envoi DM
    OR->>PG: Journalisation

Architecture layered

L0 Canaux

  • Facebook : Pages, commentaires, messages privés
  • WhatsApp : Business API, webhooks
  • Webchat : Widget intégré, WebSocket
  • Email : SMTP/IMAP, parsing automatique

L1 Edge

  • API Gateway : Authentification, rate limiting, routage
  • Orchestrateur : Coordination des flux, gestion d'état

L2 IA

  • NLU & Linguistique : Analyse d'intent, extraction d'entités
  • Recherche contextuelle : Embeddings, re-ranking, filtrage
  • LLM Router & Guardrails : Sélection de modèles, validation

L3 Services métier

  • Incident/Broadcast : Alertes, diffusion massive
  • Escalade/Ticketing : Transfert humain, suivi
  • Admin : Configuration, monitoring, analytics

L4 Données

  • PostgreSQL : État conversationnel, audit, métadonnées
  • Qdrant/pgvector : Embeddings, recherche sémantique
  • MinIO : Documents sources, fichiers, versions

Observabilité

  • OpenTelemetry : Traces distribuées, métriques, logs structurés

Modèle de données

PostgreSQL

  • Tenants : Configuration, limites, facturation
  • Users/Roles : RBAC, permissions granulaires
  • Messages : Historique, métadonnées, statuts
  • Conversations : Sessions, contexte, participants
  • Audits : Traçabilité, conformité, rétention

Qdrant/pgvector

  • Collections : Isolation par tenant
  • Items : {id, text, metadata, vector}
  • Indexes : HNSW, filtrage par attributs
  • Snapshots : Sauvegarde, réplication

MinIO

  • Buckets : Organisation par tenant/type
  • Objects : Documents sources, versions
  • Policies : Accès granulaire, chiffrement
  • Lifecycle : Archivage, purge automatique

Cycle de vie des données

Le diagramme suivant illustre le parcours conceptuel des données dans SalamBot :

flowchart LR
    subgraph "Ingestion"
        SOURCES[📥 Sources Externes]
        CHANNELS[📱 Canaux]
        WEBHOOKS[🔗 Webhooks]
        FILES[📄 Documents KB]

        SOURCES --> VALIDATION[✅ Validation]
        CHANNELS --> VALIDATION
        WEBHOOKS --> VALIDATION
        FILES --> VALIDATION
    end

    subgraph "Traitement"
        VALIDATION --> PARSING[🔍 Parsing]
        PARSING --> ENRICHMENT[🎯 Enrichissement]
        ENRICHMENT --> CLASSIFICATION[📊 Classification]

        CLASSIFICATION --> NLU_PROC[🧠 Traitement NLU]
        CLASSIFICATION --> RAG_PROC[📚 Traitement RAG]
        CLASSIFICATION --> ADMIN_PROC[⚙️ Traitement Admin]
    end

    subgraph "Stockage"
        NLU_PROC --> CONVERSATIONS[(💬 Conversations)]
        RAG_PROC --> EMBEDDINGS[(🔍 Embeddings)]
        ADMIN_PROC --> METADATA[(📋 Métadonnées)]

        CONVERSATIONS --> POSTGRES[(🗄️ PostgreSQL)]
        EMBEDDINGS --> VECTOR[(🎯 Vector DB)]
        METADATA --> POSTGRES

        FILES --> OBJECTS[(📦 Object Store)]
    end

    subgraph "Utilisation"
        POSTGRES --> QUERIES[🔎 Requêtes]
        VECTOR --> SEARCH[🔍 Recherche]
        OBJECTS --> RETRIEVAL[📖 Récupération]

        QUERIES --> ANALYTICS[📊 Analytics]
        SEARCH --> GENERATION[✨ Génération]
        RETRIEVAL --> GENERATION

        ANALYTICS --> DASHBOARDS[📈 Dashboards]
        GENERATION --> RESPONSES[💬 Réponses]
    end

    subgraph "Archivage & Purge"
        POSTGRES --> RETENTION{⏰ Rétention}
        VECTOR --> RETENTION
        OBJECTS --> RETENTION

        RETENTION -->|Expire| ARCHIVE[📦 Archivage]
        RETENTION -->|RGPD| PURGE[🗑️ Purge]

        ARCHIVE --> COLD_STORAGE[(❄️ Stockage Froid)]
        PURGE --> AUDIT_LOG[📝 Log Audit]
    end

    subgraph "Observabilité"
        TRACES[🔗 Traces]
        METRICS[📊 Métriques]
        LOGS[📝 Logs]

        VALIDATION -.-> TRACES
        PARSING -.-> METRICS
        ENRICHMENT -.-> LOGS
        CLASSIFICATION -.-> TRACES

        NLU_PROC -.-> METRICS
        RAG_PROC -.-> TRACES
        ADMIN_PROC -.-> LOGS

        QUERIES -.-> METRICS
        SEARCH -.-> TRACES
        GENERATION -.-> METRICS

        TRACES --> MONITORING[📊 Monitoring]
        METRICS --> MONITORING
        LOGS --> MONITORING
    end

    %% Flux de données sensibles
    VALIDATION -.->|PII Détecté| PII_HANDLER[🔒 Gestionnaire PII]
    PII_HANDLER --> REDACTION[🚫 Redaction]
    PII_HANDLER --> ENCRYPTION[🔐 Chiffrement]

    REDACTION --> POSTGRES
    ENCRYPTION --> POSTGRES

    %% Feedback loop
    RESPONSES -.->|Feedback| LEARNING[🎓 Apprentissage]
    LEARNING -.->|Amélioration| CLASSIFICATION

    %% Styles par phase
    style SOURCES fill:#e3f2fd
    style VALIDATION fill:#f3e5f5
    style PARSING fill:#e8f5e8
    style ENRICHMENT fill:#fff3e0
    style CLASSIFICATION fill:#fce4ec

    style POSTGRES fill:#ffebee
    style VECTOR fill:#e1f5fe
    style OBJECTS fill:#f1f8e9

    style ANALYTICS fill:#e8eaf6
    style GENERATION fill:#f9fbe7
    style RESPONSES fill:#e0f2f1

    style ARCHIVE fill:#efebe9
    style PURGE fill:#fafafa
    style MONITORING fill:#e3f2fd

    style PII_HANDLER fill:#ffcdd2
    style REDACTION fill:#ffcdd2
    style ENCRYPTION fill:#ffcdd2

Sécurité & Multi-tenant

Authentification & Autorisation

  • OIDC : Intégration SSO, tokens JWT
  • RBAC : Rôles hiérarchiques, permissions fines
  • ACL : Contrôle d'accès par tenant/collection

Protection des données

  • Chiffrement : TLS 1.3 en transit, AES-256 au repos
  • KMS : Gestion centralisée des clés
  • Isolation : Séparation logique par tenant

Audit & Conformité

  • Logs immuables : Traçabilité complète
  • Rétention : Politiques configurables
  • RGPD : Droit à l'oubli, portabilité

Horodatage & corrélation (standard global)

  • Horodatage : tous les événements stockés en ISO 8601 UTC suffixé Z (ex: 2025-08-14T10:30:00.000Z).
  • Affichage local : option UI seulement (ex: UTC+1 Maroc) ; la corrélation et l'alerting se font en UTC.
  • Corrélation : trace_id, span_id, correlation_id, X-Request-Id requis sur les appels externes et événements d'audit.
  • Skew : tolérance horloge ±100ms (services) ; ±5 min (webhooks).

Liens utiles

  • Composants détaillés TODO: créer la page
  • Guide de démarrage TODO: créer la page
  • Qualité & Tests TODO: créer la page