Documentație Tehnică Oficială

1. Arhitectura Sistemului și Stack-ul Tehnologic

Aplicația Ctrl+Alt+Truth este fundamentată pe o arhitectură modernă și scalabilă, utilizând React 18 și Next.js (App Router). Am adoptat o decuplare strictă între Client Components (marcate cu directiva 'use client', responsabile pentru interactivitatea UI și state management) și Server Components / API Routes, care gestionează comunicarea securizată cu backend-ul și ascunderea secretelor.

Pentru a asigura o experiență nativă pe dispozitivele mobile și reziliență în condiții de conectivitate redusă, sistemul este configurat ca un Progressive Web App (PWA). Am implementat Service Workers pentru capabilități de offline caching, un manifest.json riguros configurat și principii stricte de design mobile-first.

La nivel de UI/UX, stack-ul se bazează pe Tailwind CSS pentru un styling utility-first, integrat cu Shadcn UI (construit peste primitivele Radix UI). Această decizie arhitecturală garantează componente complet accesibile (WAI-ARIA compliant), ne-stilizate implicit, oferind flexibilitate maximă în aplicarea design system-ului nostru personalizat (fundal #e7edeb, accent #7c1f31).

2. Integrarea LLM și Arhitectura Backend (API)

Comunicarea cu motorul Google Gemini 2.5 Flash API este orchestrată exclusiv prin intermediul Next.js Serverless Functions (app/api/generate/route.ts), prevenind astfel expunerea cheilor API în mediul client.

Pentru a garanta integritatea datelor consumate de frontend, am implementat un mecanism de Structured Outputs (JSON Schema). Sistemul dictează strict tipul de răspuns MIME ca fiind application/json prin prompt engineering avansat, forțând modelul să returneze un payload cu o formă exactă (conținând text, toxicWords, explanation și emotions). Aceasta previne erorile de parsare la nivelul clientului și asigură un contract de date stabil.

Pentru a asigura un uptime de 99.9% în scenarii de trafic intens (high-traffic demos), am dezvoltat o Strategie de Rotație a Cheilor API. Backend-ul dispune de un array de chei și interceptează erorile HTTP 429 (Too Many Requests). În cazul epuizării cotei unei chei, sistemul implementează o buclă recursivă de fallback, iterând prin cheile disponibile până la obținerea unui răspuns valid.

În situația extremă a unui eșec total al rețelei sau epuizării tuturor cheilor, arhitectura folosește un pattern de Graceful Degradation: aplicația face fallback transparent către dataset-uri deterministe, hardcodate local, asigurând continuitatea experienței utilizatorului fără a genera excepții fatale în UI.

3. Algoritmică Client-Side și Analiză NLP Locală

Analiza Stilometrică (Local Stylometry)

Pentru a distinge între tiparele de generare mecanică (AI) și cele organice (umane), am implementat un model matematic care rulează integral în browser. Textul este parsat prin Expresii Regulate (Regex) complexe, capabile să gestioneze edge case-urile punctuației din limba română (ex: elipse, interogații retorice, abrevieri).

Algoritmul calculează Deviația Standard a Lungimii Frazelor (Burstiness) utilizând formula exactă a varianței (suma diferențelor la pătrat față de medie, împărțită la N). O deviație scăzută indică uniformitate (specifică LLM-urilor), în timp ce o deviație ridicată indică variabilitatea naturală a scriiturii umane. Suplimentar, se calculează Diversitatea Lexicală ca raport procentual între cuvintele unice și totalul cuvintelor.

Motorul de Highlight (Parsing Interactiv)

Am dezvoltat un algoritm cu complexitate temporală $O(n)$ pentru a mapa array-ul toxicWords peste elementele DOM interactive ale textului. Această abordare permite comutarea instantanee a stării (onClick) la nivel de cuvânt, fără a declanșa re-randări costisitoare ale întregului arbore de componente (component tree), menținând un framerate de 60fps în timpul interacțiunii.

4. Securitate, Performanță și State Management

Performanța aplicației este optimizată prin utilizarea avansată a React Hooks (useState, useEffect, useMemo).

O atenție deosebită a fost acordată Animației de Răspândire a Propagandei(Propaganda Spread Animation) de pe Landing Page. Pentru a preveni memory leaks (scurgeri de memorie) și "stale closures", am asigurat demontarea corectă a componentelor și curățarea ID-urilor de setInterval în cadrul funcției de cleanup a hook-ului useEffect, utilizând totodată functional state updates.

Persistența Datelor și Confidențialitatea (Privacy): Am optat pentru o arhitectură zero-database. Toate datele utilizatorului, inclusiv scorurile și progresul, sunt stocate exclusiv în localStorage-ul browserului. Această decizie face aplicația inerent conformă cu normele GDPR, deoarece nicio informație cu caracter personal (PII - Personally Identifiable Information) nu părăsește dispozitivul utilizatorului.

Pentru a preveni atacurile de tip XSS (Cross-Site Scripting) la injectarea textelor dinamice generate de AI, am implementat rutine de bază pentru sanitizarea DOM-ului, asigurându-ne că payload-urile sunt tratate strict ca text și nu ca HTML executabil.

5. Ghidul Profesorului: Integrare la Clasă

Platforma Ctrl+Alt+Truth este concepută ca un instrument pedagogic interactiv pentru lecțiile de educație civică, TIC sau gândire critică. Iată cum poate fi integrată eficient în procesul de predare:

Obiective Pedagogice

• Dezvoltarea gândirii critice: Elevii învață să nu accepte informația ca fiind adevărată doar pe baza aspectului vizual al sursei.
• Înțelegerea mecanismelor AI: Demistificarea modului în care textele sintetice sunt generate și cum pot fi detectate prin analiză stilometrică.
• Recunoașterea tehnicilor de manipulare: Identificarea limbajului polarizant, a clickbait-ului și a manipulării consensului.

Strategii de Predare

1. Sesiuni de Analiză în Grup: Profesorul poate proiecta Laboratorul de Adevăr și poate analiza împreună cu elevii un articol generat, dezbătând de ce anumite cuvinte sunt marcate ca fiind toxice.
2. Competiție de Verificare (Swipe Game): Elevii pot concura pentru cel mai mare scor în jocul de swipe, dezvoltând reflexe rapide de detectare a titlurilor suspecte.
3. Lecții Structurate cu Quiz: Academia oferă 6 module progresive. Fiecare modul se încheie cu un quiz de evaluare care oferă feedback instantaneu și explicații detaliate pentru fiecare răspuns.