livrare lot 2
This commit is contained in:
commit
8ecc78e729
763 changed files with 164593 additions and 0 deletions
245
backend/docs/01_Arhitectura_Lot2.md
Normal file
245
backend/docs/01_Arhitectura_Lot2.md
Normal file
|
|
@ -0,0 +1,245 @@
|
|||
% 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.*
|
||||
Loading…
Add table
Add a link
Reference in a new issue