# 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)

```mermaid
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

```mermaid
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

```mermaid
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)

```mermaid
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

```mermaid
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

```mermaid
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)

```mermaid
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) |