245 lines
12 KiB
Markdown
245 lines
12 KiB
Markdown
% Documentație de arhitectură — DiDi Lot 2 (Backend)
|
||
% Platformă digitală inteligentă pentru prevenirea și combaterea dezinformării
|
||
% PNRR DIGI150 · contract 11.1.i3.c9
|
||
|
||
---
|
||
|
||
# 1. Scop și context
|
||
|
||
Prezentul document descrie arhitectura tehnică a **Lotului 2 — Aplicație software backend**
|
||
din cadrul platformei DiDi, sistem de detecție a dezinformării dezvoltat în cadrul
|
||
proiectului PNRR DIGI150. Backendul primește conținut (text, URL, imagine, audio, video),
|
||
îl analizează pe patru dimensiuni independente și produce un verdict de risc cu scor
|
||
(0–100) și explicație bilingvă (RO/EN).
|
||
|
||
Lotul 2 acoperă **coloana vertebrală software** a platformei: orchestrarea analizei,
|
||
brokerul de mesaje, gateway-ul de API, baza de date, autentificarea, dashboard-ul
|
||
administrativ, observabilitatea și livrarea cloud-native. Serviciile de inteligență
|
||
artificială propriu-zise (modele LLM, deepfake, transcriere, extractori) sunt furnizate
|
||
de **Lotul 1 (Platforma AI)** și sunt consumate de backend prin interfețe HTTP configurabile
|
||
(vezi §9).
|
||
|
||
---
|
||
|
||
# 2. Vedere de ansamblu — arhitectură pe trei straturi
|
||
|
||
```
|
||
┌──────────────────────────────────────────────────────────────────────┐
|
||
│ STRAT 3 — Gateway & Autentificare │
|
||
│ Kong API Gateway (JWT RS256) · Keycloak (OIDC, realms clients/admins) │
|
||
├──────────────────────────────────────────────────────────────────────┤
|
||
│ STRAT 2 — Orchestrare │
|
||
│ Agent V3 (:24803) — motor de analiză, dispatch async │
|
||
│ didiFramework (:3005) — CRUD parametri + sync Redis │
|
||
│ Workeri (techniques ×2, ai-tampered ×2, claims ×3, domain ×2, │
|
||
│ media-preprocess ×2, verdict-aggregator ×2) │
|
||
│ Admin Dashboard (React) — configurare, monitorizare, moderare │
|
||
├──────────────────────────────────────────────────────────────────────┤
|
||
│ STRAT 1 — Date │
|
||
│ PostgreSQL 17 · Redis 7 · RabbitMQ 3.12 · MinIO (S3) │
|
||
├──────────────────────────────────────────────────────────────────────┤
|
||
│ Observabilitate transversală │
|
||
│ Prometheus · Grafana · Loki · OpenTelemetry · Jaeger · Alertmanager │
|
||
└──────────────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
Principiul de proiectare: **separarea configurării de execuție**. Toți parametrii de
|
||
analiză (tehnici, ponderi, verdicte, modele LLM, prompturi, profiluri de pipeline) sunt
|
||
gestionați declarativ prin `didiFramework` și stocați în PostgreSQL, apoi sincronizați în
|
||
Redis. Motorul de analiză (`agent-v3`) citește configurarea din Redis la fiecare rulare —
|
||
astfel comportamentul se modifică fără redeploy de cod.
|
||
|
||
---
|
||
|
||
# 3. Componentele principale
|
||
|
||
## 3.1 Agent V3 — motorul de analiză (port 24803)
|
||
|
||
Serviciul central. Node.js + TypeScript + Express 5. Expune API-ul de analiză (toate
|
||
endpoint-urile de analiză sunt **asincrone**: dispatch pe RabbitMQ, răspuns `202` + poll).
|
||
|
||
Rulează patru componente de analiză independente + un calculator de verdict:
|
||
|
||
| Componentă | Ce detectează | Scor |
|
||
|---|---|---|
|
||
| **Techniques** | tehnici de manipulare (166 tehnici, 8 dimensiuni) | manipulation_score 0–100 |
|
||
| **AI-Tampered** | conținut generat/modificat de AI | ai_probability 0–100 |
|
||
| **Claims** | afirmații verificate prin căutare web | credibility_score 0–100 |
|
||
| **Source Assessment** | credibilitatea sursei/domeniului | trust_score 0–100 |
|
||
| **Verdict** | agregare ponderată → risc final + explicație RO/EN | risk_score 0–100 |
|
||
|
||
Fiecare componentă (mai puțin Domain) rulează în două etape: **screening** (analiză rapidă)
|
||
→ **deep analysis** (analiză detaliată). Fiecare etapă are un lanț de modele LLM cu până la
|
||
3 nivele de fallback.
|
||
|
||
## 3.2 didiFramework — managementul parametrilor (port 3005)
|
||
|
||
Node.js + TypeScript + Express 4. API CRUD pentru toți parametrii platformei (peste 280 de
|
||
endpoint-uri). Stochează configurarea în PostgreSQL (schema `bos_parammgmt`) și o
|
||
sincronizează în Redis prin `POST /api/sync-redis` (~51 chei de configurare). Gestionează de
|
||
asemenea utilizatorii, creditele, abonamentele și integrarea cu Keycloak.
|
||
|
||
## 3.3 Admin Dashboard
|
||
|
||
Aplicație React 19 + Material UI. Interfață pentru: configurarea framework-ului de analiză,
|
||
managementul modelelor LLM (chain-uri free/premium), utilizatori, istoric analize, coada de
|
||
moderare umană (HIL), editorul de pipeline-uri și consola de rulare.
|
||
|
||
## 3.4 Kong API Gateway
|
||
|
||
Punctul unic de intrare pentru traficul extern. Mod DBless (configurație declarativă).
|
||
Aplică validarea JWT (RS256, contra JWKS-ului Keycloak), rate limiting, CORS, transformări
|
||
de request/response și limitare de dimensiune. Rutează `/api/v3/*` → agent-v3 și `/api/*` →
|
||
didiFramework.
|
||
|
||
## 3.5 Keycloak
|
||
|
||
Serviciul de autentificare OIDC/OAuth2. Două realm-uri: `didi-clients` (utilizatori finali)
|
||
și `didi-admins` (operatori). Emite token-uri JWT RS256, aplică politici de parolă, protecție
|
||
brute-force și MFA (TOTP).
|
||
|
||
## 3.6 Stratul de date
|
||
|
||
- **PostgreSQL 17** — sursa de adevăr. 4 scheme: `bos_parammgmt` (parametri), `bos_analysis`
|
||
(rezultate), `bos_sysadmin` (utilizatori), `bos_subscriber` (date personale).
|
||
- **Redis 7** — cache derivat din PostgreSQL (configurare) + stare de sesiune (TTL 7 zile) +
|
||
lock-uri workeri.
|
||
- **RabbitMQ 3.12** — cozi async (4 componente × 6 planuri de prioritate + media-preprocess
|
||
+ results + DLQ).
|
||
- **MinIO** — stocare fișiere media (S3-compatibil).
|
||
|
||
---
|
||
|
||
# 4. Fluxul de date
|
||
|
||
## 4.1 Analiză asincronă (fluxul principal)
|
||
|
||
```
|
||
Client → Kong (validare JWT) → agent-v3 :24803
|
||
│ validare input + verificare credite (didiFramework)
|
||
▼
|
||
Dispatcher → publică task-uri în RabbitMQ (prioritate din planul de abonament)
|
||
▼ răspuns 202: { session_id, poll_url, result_url }
|
||
|
||
--- în paralel, workeri Docker ---
|
||
Worker Techniques ┐
|
||
Worker AI-Tampered ├─ consumă din coadă → rulează executor → publică rezultat
|
||
Worker Claims │
|
||
Worker Domain ┘
|
||
▼
|
||
Verdict Aggregator → așteaptă toate componentele → VerdictCalculator (funcție pură)
|
||
→ explicație LLM (RO/EN) → persistă în PostgreSQL + Redis
|
||
▼
|
||
Client face poll: GET /:sessionId/queue-status → progres
|
||
GET /:sessionId/result → AnalysisSession completă
|
||
```
|
||
|
||
## 4.2 Analiză media (video/audio/imagine)
|
||
|
||
Un worker dedicat `media-preprocess` centralizează descărcarea, extragerea cadrelor
|
||
(ffmpeg), transcrierea (Whisper) și analiza vizuală (o singură dată), apoi dispecerizează
|
||
componentele de analiză care citesc rezultatele din cache-ul Redis — evitând reprocesarea.
|
||
|
||
## 4.3 Pipeline = workflow cu dependențe explicite
|
||
|
||
Fluxul de analiză este modelat ca **workflow cu dependențe explicite** (conform caietului,
|
||
„DAG *sau* workflow"):
|
||
|
||
```
|
||
intake → [media_preprocess] → {techniques ∥ ai_tampered ∥ claims ∥ domain} → verdict → persist
|
||
```
|
||
|
||
Variantele de pipeline per tip de conținut sunt definite prin `input_type_profile`
|
||
(6 profiluri: text_no_url, text_with_url, image, audio, video, url), fiecare cu ponderi,
|
||
reguli de override și reguli INCONCLUSIVE proprii. Endpoint-ul `POST /dry-run` rezolvă
|
||
întregul plan (noduri, dependențe, cozi, lanțuri de modele) fără a consuma resurse.
|
||
|
||
---
|
||
|
||
# 5. Securitate
|
||
|
||
- **Autentificare:** JWT RS256 emise de Keycloak. Verificate criptografic **atât la gateway
|
||
(Kong)** cât și **în backend** (agent-v3 + didiFramework) — apărare în adâncime; un token
|
||
forjat/expirat este respins cu 401 pe orice cale.
|
||
- **Autorizare (RBAC):** roluri Keycloak (`admin`, `moderator`, `senior_moderator`, `viewer`).
|
||
Endpoint-urile sensibile (istoric admin, moderare) impun rol.
|
||
- **Izolarea tier-urilor:** tier-ul (free/premium) este derivat exclusiv din planul de
|
||
abonament returnat de didiFramework, nu din body-ul cererii — previne escaladarea de
|
||
privilegii.
|
||
- **TLS** pe dashboard-ul administrativ; secretele sunt în fișiere `.env` (excluse din
|
||
versionare).
|
||
|
||
---
|
||
|
||
# 6. Scalare și reziliență
|
||
|
||
- **Scalare workeri configurabilă:** `scale-workers.sh` (status/set/auto pe metrica
|
||
`didi_queue_depth` din Prometheus).
|
||
- **Broker rezilient:** publisher confirms (așteaptă ACK-ul broker-ului), re-subscribe
|
||
automat la reconectare, DLQ cu monitor + alertă.
|
||
- **HA PostgreSQL:** livrat ca IaC reproductibil (Patroni + etcd + HAProxy) în
|
||
`didiDatabase/ha-cluster/`, cu drill de failover.
|
||
- **Fail-open pe servicii AI:** orice eroare a unui serviciu Lot 1 (timeout, indisponibil)
|
||
nu blochează analiza — se continuă cu fallback.
|
||
|
||
---
|
||
|
||
# 7. Tehnologii
|
||
|
||
| Componentă | Tehnologie |
|
||
|---|---|
|
||
| Agent V3 | Node.js, TypeScript, Express 5 |
|
||
| didiFramework | Node.js, TypeScript, Express 4 |
|
||
| Admin Dashboard | React 19, Material UI 7, TypeScript |
|
||
| Bază de date | PostgreSQL 17 (+ Patroni/HAProxy pentru HA) |
|
||
| Cache | Redis 7 |
|
||
| Coadă | RabbitMQ 3.12 |
|
||
| Stocare | MinIO (S3-compatibil) |
|
||
| Gateway | Kong 3.9 (DBless) |
|
||
| Autentificare | Keycloak 26 |
|
||
| Observabilitate | Prometheus, Grafana, Loki, OpenTelemetry, Jaeger, Alertmanager |
|
||
| CI/CD | GitLab CI (build/test/publish + rollback + health-gate) |
|
||
|
||
---
|
||
|
||
# 8. Modelul de date (rezumat)
|
||
|
||
**PostgreSQL — schema `bos_analysis`** (rezultatele analizelor): `analysis_session` (rădăcină)
|
||
+ câte un tabel per componentă (`analysis_techniques`, `analysis_ai_tampered`,
|
||
`analysis_claims`, `analysis_domain`, `analysis_verdict`) + `moderation_queue` (coada HIL).
|
||
|
||
**PostgreSQL — schema `bos_parammgmt`** (parametri, ~40 tabele): ierarhia de tehnici
|
||
(dimensiuni → subdimensiuni → tehnici → indicatori), verdicte, ponderi, surse, claims,
|
||
provideri și modele LLM, `component_stage_assignment` (chain-uri model per etapă și tier),
|
||
`component_prompt`, `input_type_profile`.
|
||
|
||
**Redis:** chei `didi:framework:*` și `didi:config:*` (configurare, permanente) + chei
|
||
`didi:pipeline:*` (sesiuni, TTL 7 zile) + chei `didi:queue:*` (stare workeri, TTL scurt).
|
||
|
||
---
|
||
|
||
# 9. Integrarea cu Lotul 1 (Platforma AI)
|
||
|
||
Agent V3 consumă serviciile Lotului 1 prin interfețe HTTP, cu **URL-uri configurabile din
|
||
mediu** (`.env`). Pe orice deployment se ajustează doar host-urile.
|
||
|
||
| Variabilă env | Serviciu Lot 1 | Rol |
|
||
|---|---|---|
|
||
| `LLM_ROUTER_URL` | llm-inference | modele LLM text (Qwen) + OCR |
|
||
| `VISION_LLM_URL` | vision | analiză imagine / cadre video |
|
||
| `DIDI_BRAIN_URL` | brain | cache de verificare + RAG (fact-checking) |
|
||
| `VIDEO_ANALYSIS_URL` | video / BusterX | detecție deepfake video |
|
||
| `EXTRACTORS_URL` | extractors | EXIF, ELA, spectrogramă, NER, YOLO, OCR |
|
||
| `FORENSIC_API_URL` | forensic | trăsături forensice media |
|
||
| `M17_WHISPER_URL` | audio | transcriere audio |
|
||
| `M17_WEB_API_URL` | web | căutare web pentru claims/surse |
|
||
| `DOMAIN_CHECK_API_URL` | domain-check | WHOIS/DNS/SSL/blacklist domeniu |
|
||
|
||
Fiecare integrare este **fail-open**: dacă serviciul Lot 1 nu răspunde, analiza continuă cu
|
||
degradare grațioasă, fără a eșua. Delimitarea responsabilităților: Lotul 2 orchestrează și
|
||
consumă; Lotul 1 furnizează modelele și izolarea execuției (inclusiv sandbox-ul de cod).
|
||
|
||
---
|
||
|
||
*Document generat pentru dosarul de recepție Lot 2. Corespondentul tehnic detaliat per
|
||
serviciu se află în fișierele `INDEX.md` din fiecare director de serviciu.*
|