Structura codului sursă

Codul platformei Recash este organizat modular, nu ca un singur bloc monolitic — fiecare parte a aplicației funcționează izolat, ușor de urmărit și de schimbat fără să afecteze restul. Acesta este împărțit în cinci zone principale:

• app/ — rutele și interfața vizuală
• lib/ — funcțiile care fac logica efectivă: calcule, validări, reguli
• hooks/ — cod reutilizabil pe partea de client, precum reconectarea automată la WebSocket
• ws-server/ — comunicarea în timp real, ca serviciu independent
• mcp-server/ — serverul MCP, care expune datele read-only ale platformei către asistenți AI, ca serviciu independent

Rutele API

Toate rutele sunt versionate explicit, sub app/api/v1/ — o decizie care lasă loc pentru o eventuală versiune viitoare fără a afecta clienții existenți. Dedesubt, fiecare grup de rute acoperă un domeniu individual: posts pentru postări, auth pentru autentificare, ai pentru analiza AI, radar pentru alertele geografice, profile pentru datele utilizatorului, leaderboard pentru clasament.

O rută bine construită face trei lucruri: validează cererea, apelează logica potrivită, răspunde.

Logica aplicației

Fiecare acțiune importantă din aplicație are codul ei dedicat în lib/, separat de rute:

• lib/rate-limit.ts — limitare de trafic
• lib/cache.ts — cache-aside generic
• lib/pubsub.ts — publicare evenimente WebSocket
• lib/radar.ts — notificări radar
• lib/badges.ts — acordare badge-uri

Componente server și client

Majoritatea componentelor din Recash sunt Server Components — randate pe server, fără JavaScript trimis în plus către browserul cuiva care doar vrea să vadă o postare. Doar fișierele care încep explicit cu "use client" rulează și în browser, pentru că au nevoie de interactivitate sau de stare pe care doar browserul o poate asigura.

Hook-uri personalizate

Hook-urile adună într-un singur loc logica ce s-ar repeta în mai multe componente. Componentele care le folosesc nu știu nimic despre ce se întâmplă în spate — doar se abonează la date și primesc actualizări:

• useRecashSocket — reconectare automată la WebSocket, coadă de mesaje, distribuirea evenimentelor
• useNotificationBell — contorul de notificări necitite, actualizat live
• usePostLive — starea live a unei postări (status, mesaje noi)

Serverul MCP

mcp-server/ rulează ca proces separat și expune datele read-only ale platformei (anunțuri, reputație, clasament, statistici) prin Model Context Protocol, astfel încât orice client MCP — de exemplu Claude — să le poată interoga în siguranță. Nu duplică logica aplicației: folosește exact același catalog de tool-uri din lib/ai/tools.ts ca și asistentul din aplicație, iar ambele apelează aceleași rute publice /api/v1/.... O singură sursă de adevăr, trei clienți: interfața web, serverul MCP și asistentul integrat. Detalii în Integrare AI.

Convenții de proiect

Rutele publice folosesc URL-uri în română, coerent cu publicul aplicației. Fiecare pagină "grea" este separată de fișierul de rută propriu-zis: page.tsx rămâne un punct de intrare simplu, care face fetch-ul inițial de date, iar logica de interfață stă în componenta ei dedicată.