Biblioteca Pontes

Context

Biblioteca Pontes este clientul Android oficial al bibliotecii virtuale a Asociației Pontes — cea mai mare bibliotecă digitală în limba română destinată persoanelor cu deficiențe de vedere. Aplicația permite navigarea catalogului, căutarea, descărcarea și încărcarea de cărți accesibile direct de pe dispozitiv.

Biblioteca este alimentată de comunitate: materialele disponibile provin în mare parte de la utilizatori. Aplicația deservește peste 1.000 de descărcări și este folosită zilnic de persoane nevăzătoare din România.

Caracteristici principale

• Navigare ierarhică — răsfoiește secțiunile, genurile și autorii bibliotecii cu un sistem breadcrumb intuitiv
• Căutare full-text — caută în întreg catalogul (minimum 4 caractere); activabilă și prin agitarea dispozitivului
• Cărți aleatorii — generează selecții aleatorii filtrate pe secțiune, gen și număr
• Topuri & clasamente — cele mai recente, modificate, descărcate; autori populari
• Istoric personal — activitatea de descărcări și căutări
• Descărcare & citire — cărțile se descarcă în Downloads/Pontes/Biblioteca/ ca arhive ZIP
• Încărcare cărți — contribuie cu documente (DOC, DOCX, PDF, RTF, EPUB, ZIP, TXT, HTML)
• Manager de fișiere integrat — copiază, taie, redenumește, extrage ZIP, partajează fișiere
• Accesibilitate nativă — alerte sonore, suport VoiceOver/TalkBack, agitare pentru căutare, temă light/dark/system
• Cont utilizator — autentificare, recuperare parolă, editare profil

Arhitectură

Aplicația Android este front-end-ul unui ecosistem mai larg:

┌───────────────────────────────────────────────┐
│         Biblioteca Pontes (Android)           │
│       Kotlin · OkHttp · Fragments             │
├───────────────────────────────────────────────┤
│         www.pontes.ro/biblioteca/              │
│  PHP 7.4 (producție) → Angular 21 (WIP)       │
├───────────────────────────────────────────────┤
│          biblioserver.pontes.ro/api             │
│       Node.js / Express + MariaDB              │
└───────────────────────────────────────────────┘

Frontend web PHP

Interfața web live la www.pontes.ro/biblioteca/ este o aplicație PHP 7.4 clasică, fără framework, ce deservește atât vizitatorii din browser cât și API-ul consumat de aplicația Android. Arhitectura este bazată pe un pattern single-page controller: un fișier index.php rutat după parametrul ?act=..., cu o ierarhie de clase biblioRender → biblioEngine → coreUtils.

Caracteristici

• Catalog public — răsfoire pe secțiuni, categorii, autori, genuri cu căutare full-text
• Conturi utilizatori — înregistrare, autentificare pe sesiuni, trei niveluri de acces (standard 3 descărcări/zi, premium 15, admin)
• Panou administrare — CRUD complet pentru cărți, autori, genuri, utilizatori; manager fișiere, gestionare descrieri AI, joburi de conversie
• Statistici — dashboard cu grafice (Chart.js): descărcări, încărcări, căutări, autentificări în timp, distribuție pe genuri, top utilizatori
• Integrare Wikipedia — proxy pentru biografiile autorilor din Wikipedia românească
• Descrieri generate AI — se conectează la BiblioServer (Node.js) pentru generare de descrieri și etichete cu Gemini

Tehnologii

PHP 7.4, MySQL (mysqli), jQuery 3.5.1, Bootstrap 4, Chart.js, session-based auth, arhivare cu ZIP, conversie documente prin joburi asincrone.

Repere tehnice

• Android nativ în Kotlin — single-activity pattern, fragmente, PreferenceFragmentCompat, arhitectură bazată pe broadcast-uri locale pentru comunicare între fragmente
• MinSdk 21 — compatibilitate cu Android 5.0+, target SDK 37
• API REST sincron cu backend PHP — consumă endpoint-urile json.php, login.php, download2.php, upload.php cu autentificare prin parametri MD5
• Manager de fișiere complet — navigare arborescentă, operațiuni de fișiere, extragere arhive ZIP
• Detecție agitare — accelerometru configurat ca senzor hardware, prag de sensibilitate reglabil
• Sunete și haptică — 4 efecte sonore (info, eroare, descărcare completă, încărcare completă) redate cu SoundPool
• Temă adaptivă — light / dark / system, cu suport pentru culori Material You pe Android 12+
• Caching în memorie — răspunsurile API se cache-uiesc într-un HashMap<String, CacheItem> pentru navigare rapidă
• Backend Node.js (BiblioServer) — API REST modern cu Express, descrieri generate AI (Gemini, Groq, Mistral), conversie asincronă de documente
• Angular 21 (în lucru) — înlocuirea interfeței web PHP cu o aplicație standalone Material Design 3, signals, zoneless change detection, View Transitions API

Galerie

• Ecran principal — meniu grilă cu opțiunile: Biblioteca, Topuri, Random, Căutare, Fișiere
• Bibliotecă — listă cărți cu breadcrumb, paginare, căutare și filtre
• Detaliu carte — descriere, etichete, butoane de descărcare
• Topuri — cele mai noi, modificate, descărcate
• Manager fișiere — navigare directoare, operațiuni fișiere
• Autentificare — ecran login cu utilizator și parolă
• Setări — temă, sunet, agitate căutare, număr elemente listă