didi-lot1-ai/ai_platform/docs/ARCHITECTURE.md

DiDi — LOT 1 · Arhitectură și fluxuri (diagrame)

Diagramele arhitecturale și de flux ale Sistemului de Inteligență Artificială (LOT 1), recreate în Mermaid (editabile, randate automat pe GitHub/GitLab și în VS Code). Corespund Anexei A din Propunerea Tehnică. Versiunile originale (imagini) se găsesc în docs/diagrams/offer_diagram_1..7.png. Pentru vizualizare în browser: docs/architecture.html.

Convenții (diagrame de secvență): săgeată continuă ->> = cerere; punctată -->> = răspuns; auto-buclă = procesare internă; Note over = observație. LOT 2 (Backend) este consumatorul API REST al platformei LOT 1.

---

1. Arhitectură de ansamblu — componente (control plane vs execution plane)

flowchart LR
  subgraph LOT1["LOT 1 — Platforma AI"]
    subgraph M4["Modul 4 — Cache"]
      redis["Redis / cache distribuit<br/>rezultate · locks · pub/sub · rate-limit"]
    end
    subgraph M1["Modul 1 — Inferență LLM"]
      gw["LLM Gateway (FastAPI)"]
      vllm["vLLM — Qwen3.5 (GPU)"]
      llama["llama.cpp (CPU, fallback)"]
    end
    subgraph M6["Modul 6 — Dashboard Admin AI"]
      dash["Dashboard Admin<br/>monitorizare · metrici GPU · stare servicii"]
    end
    subgraph M5["Modul 5 — RAG / Brain"]
      rag["RAG Service"]
      emb["Embeddings API"]
      vs["Vector Store (pgvector)"]
      rr["Rerank API"]
    end
    subgraph M3["Modul 3 — Web Crawl"]
      web["Web Crawl API<br/>căutare · content extraction"]
    end
    subgraph M2["Modul 2 — Extractoare ML"]
      whisper["Whisper API<br/>transcriere audio"]
      video["Video Analysis API<br/>ffmpeg + frame sampling"]
      buster["BusterX (vLLM)<br/>deepfake detection"]
      sandbox["Sandbox Cod<br/>EXIF · ELA · spectrograme"]
    end
    subgraph MT4["Modul T4 — Credibilitate sursă"]
      domcheck["Domain Check API<br/>WHOIS · SSL · blacklist · DNS · IP"]
    end
  end
  subgraph LOT2["LOT 2 — Backend (consumator API REST)"]
    orch["Orchestrator"]
    workers["Workers Analiză"]
  end

  gw --> vllm
  gw -. fallback .-> llama
  rag --> emb
  rag --> vs
  rag --> rr
  video --> buster

  workers -->|POST /v1/chat/completions| gw
  workers -->|POST /v1/audio/transcriptions| whisper
  workers -->|POST /analyze/video| video
  workers -->|POST /v1/gather| web
  workers -->|POST /v1/query| rag
  workers -->|POST /analyze| sandbox
  workers -->|POST /api/v1/check/check| domcheck
  orch --- workers

  redis -. cache .-> gw
  redis -. cache .-> rag

---

2. Flux inferență LLM — cache + fallback multi-backend

sequenceDiagram
    participant B as Backend (LOT 2)
    participant G as LLM Gateway (FastAPI)
    participant V as vLLM Qwen3.5
    participant L as llama.cpp (fallback)

    B->>G: POST /v1/chat/completions {model, messages[], temperature}
    G->>G: Verificare cache
    alt Cache hit
        G-->>B: 200 {cached response}
    else Cache miss
        G->>V: Forward request
        alt vLLM disponibil
            V->>V: Generare răspuns (GPU)
            V-->>G: 200 {response, usage}
        else vLLM indisponibil
            G->>L: Fallback request
            L->>L: Generare răspuns (CPU)
            L-->>G: 200 {response, usage}
        end
        G->>G: Stocare în cache
        G-->>B: 200 {response, usage, model_used}
    end

---

3. Flux multimodal (text + imagine) — viziune / OCR / artefacte AI

sequenceDiagram
    participant B as Backend (LOT 2)
    participant G as LLM Gateway (FastAPI)
    participant V as vLLM Qwen3.5

    B->>G: POST /v1/chat/completions {messages:[{user, [text, image_url]}]}
    G->>V: Forward multimodal request
    V->>V: Procesare imagine + text (GPU)
    V->>V: OCR, descriere, detecție artefacte AI
    V-->>G: 200 {response: structured JSON}
    Note over G: Răspuns structurat: description, ocr_text, ai_artifacts, anomalies
    G-->>B: 200 {response, model_used}

---

4. Flux analiză video — detecție deepfake (BusterX)

sequenceDiagram
    participant B as Backend (LOT 2)
    participant VA as Video Analysis API
    participant F as ffmpeg
    participant BX as BusterX (vLLM)

    B->>VA: POST /analyze/video {video_url}
    VA->>VA: Download video
    VA->>F: Extragere cadre (frame sampling configurabil)
    F-->>VA: Cadre extrase (N imagini)
    loop Pentru fiecare cadru
        VA->>BX: POST analiză cadru
        BX->>BX: Detecție artefacte deepfake
        BX-->>VA: {score, artifacts, confidence}
    end
    VA->>VA: Agregare scoruri per cadru
    VA->>VA: Calculare verdict final
    VA-->>B: 200 {verdict, score, evidence_frames, analysis_details}

---

5. Flux RAG — interogare bază de cunoștințe

sequenceDiagram
    participant B as Backend (LOT 2)
    participant R as RAG Service
    participant E as Embeddings API
    participant VS as Vector Store
    participant RR as Rerank API

    B->>R: POST /v1/query {query, top_k, filters}
    R->>E: Embedding query text
    E-->>R: Vector embedding
    R->>VS: Nearest neighbor search {vector, top_k: 20}
    VS-->>R: Documente candidat (cu scoruri similaritate)
    R->>RR: Reranking documente {query, documents}
    RR-->>R: Documente reordonate (scoruri relevanță)
    R->>R: Filtrare top_k final
    R-->>B: 200 {documents:[{text, score, source, metadata}]}

---

6. Flux Web Crawl — colectare evidence

sequenceDiagram
    participant B as Backend (LOT 2)
    participant W as Web Crawl API
    participant S as Motor căutare (SearXNG / provideri)
    participant P as Pagini Web

    B->>W: POST /v1/gather {claim, max_sources}
    W->>S: Căutare web {query: claim}
    S-->>W: Rezultate căutare (URLs + snippets)
    loop Pentru fiecare URL relevant
        W->>P: Fetch pagină
        P-->>W: Conținut HTML
        W->>W: Extragere conținut structurat (text, metadate, autor, dată)
    end
    W->>W: Structurare evidence package
    W-->>B: 200 {sources:[{url, title, content, snippet, date, credibility_indicators}]}

---

7. Flux Sandbox — analiză media (EXIF / ELA / spectrogramă / cadre)

sequenceDiagram
    participant B as Backend (LOT 2)
    participant SB as Sandbox API
    participant PY as Python Runtime (izolat)

    B->>SB: POST /analyze {media_url, analysis_type}
    SB->>SB: Download fișier media (stocare temporară)
    alt Imagine
        SB->>PY: Execuție EXIF extraction
        PY-->>SB: Metadata EXIF
        SB->>PY: Execuție Error Level Analysis
        PY-->>SB: Rezultat ELA
    else Audio
        SB->>PY: Execuție spectrogramă
        PY-->>SB: Analiză spectrogramă
    else Video
        SB->>PY: Execuție frame analysis
        PY-->>SB: Semnături digitale + anomalii
    end
    SB->>SB: Cleanup fișiere temporare
    SB-->>B: 200 {metadata, anomalies, signatures, analysis_type}
    Note over SB: Sandbox: izolare completă, timeout, restricții resurse, audit

---

Notă de mapare ofertă → implementare livrată

Diagramele reflectă arhitectura din propunerea tehnică. În deployment-ul livrat, denumirile concrete ale componentelor sunt:

În diagrame (ofertă)	În implementarea livrată
Redis / cache	didi_brain (Postgres/pgvector) — verification_cache + analysis_atom (TTL, dedup, invalidare)
RAG Service /v1/query	didi_brain /v1/search + /v1/gather
Vector Store	pgvector (în didibrain-postgres)
Embeddings / Rerank API	embeddings (bge-m3) / rerank (bge-reranker-v2-m3)
Web Crawl /v1/gather + „Brave Search"	web + SearXNG (gratuit) + provideri (SerpAPI/Tavily/Brave/LinkUp/Exa) + cloak (tier-3)
Sandbox Cod /analyze	extractors (/v1/metadata, /v1/detect, /v1/ner, /v1/ocr, /v1/sentiment) + forensic_features
vLLM Qwen3.5	vllm/vllm-openai:qwen3_5 — model Qwen/Qwen3.5-35B-A3B
BusterX (vLLM)	l8cv/BusterX_plusplus (Qwen2.5-VL-7B)