Capitol activStudiu de caz
Studiu de caz / 01
O platformă de analiză web production-ready, axată pe confidențialitate, cu un 'Data Analyst' AI integrat care folosește Text-to-SQL pentru a răspunde la întrebări în limbaj natural despre datele tale. Construită cu TypeScript, Express.js, React și PostgreSQL.
01 / Comportamentul sistemului
Un mecanism tehnic specific proiectului, bazat pe arhitectura și contextul de implementare înregistrate.
Construit ca o alternativă production-ready la Google Analytics, PingLens demonstrează că confidențialitatea și analiza puternică nu se exclud reciproc. Platforma a ales deliberat complexitatea în detrimentul simplității - nu doar numărarea pageview-urilor, ci un analist AI complet care înțelege limbajul natural, generează SQL sigur și transmite răspunsuri conversaționale în streaming.
Pipeline-ul AI Text-to-SQL este inima sistemului: utilizatorii pun întrebări precum 'Care au fost paginile mele top ieri?' și LLM-ul generează interogări PostgreSQL cu context complet de schemă. Fiecare interogare trece prin cinci straturi de securitate înainte de execuție. Blocklist-ul de cuvinte cheie periculoase respinge operațiunile INSERT/DROP/DELETE. Potrivirea de pattern-uri prinde încercările de injecție SQL (OR 1=1, UNION SELECT). Validarea tabelelor asigură că doar 'events' și 'websites' sunt interogate. Interogarea se execută printr-un rol de bază de date read-only cu permisiuni doar SELECT. Dacă prima încercare eșuează, sistemul reîncearcă o dată cu contextul erorii - învățând LLM-ul din greșelile sale.
03 / Înregistrarea arhitecturii
O interpretare structurată a arhitecturii înregistrate pentru acest proiect.
Trei aplicații care lucrează împreună:
• Dashboard pentru Clienți (dashboard/) - React + Vite + TailwindCSS pentru selectarea site-ului, vizualizarea metrici în timp real cu Recharts și interfața de chat AI cu răspunsuri în streaming • Script de Tracking (tracker/) - TypeScript vanilla (<5KB) cu batching inteligent de evenimente, timere de auto-flush și fallback sendBeacon pentru colectare fiabilă de date • API Backend (api/) - Express.js cu TypeScript care gestionează ingestia evenimentelor, interogări de analiză, pipeline-ul AI Text-to-SQL și abstractizarea LLM multi-provider
API-ul se conectează la PostgreSQL prin node-postgres cu două pool-uri de conexiuni: un pool principal pentru operațiuni read/write și un pool read-only (rolul ai_agent_reader) pentru interogările generate de AI. Pipeline-ul AI validează SQL-ul prin blocklist-uri regex, detectarea pattern-urilor de injecție și allowlist-uri de tabele înainte de execuție.
Furnizori LLM (OpenAI, Anthropic, Gemini) sunt abstractizați prin interfața ILLMService cu ProviderConfig discriminated union. Mecanismul de auto-corecție reîncearcă interogările eșuate o dată cu contextul erorii.
Docker Compose orchestrează întregul stack pentru dezvoltare locală. Build-ul de producție folosește Dockerfile-uri multi-stage cu utilizatori non-root și health check-uri.
Tracker-ul este proiectat pentru performanță și fiabilitate: evenimentele se pun la coadă în memorie (max 50), auto-flush la fiecare 5 secunde, trimitere batch cu fetch keepalive și fallback sendBeacon la descărcarea paginii. Zero dependențe externe. Întregul bundle este <5KB minificat.
Securitatea a fost o preocupare de prim rang de la prima zi: Helmet.js configurează headere de securitate, clasele de erori personalizate sanitizează mesajele în producție, logging-ul JSON structurat include tracing prin request ID pentru debugging, schemele Zod validează fiecare input API, și zero tipuri 'any' există în codul de producție. SQL parser-ul folosește regex stateless (fără flag /g) pentru a evita bug-ul lastIndex care cauzează rezultate alternante true/false.
Abstractizarea LLM folosește un discriminated union (ProviderConfig) cu tipurile 'vercel' și 'gemini', permițând schimbarea type-safe a providerilor. OpenAI și Anthropic folosesc interfața unificată a Vercel AI SDK. Google Gemini necesită logică de streaming personalizată dar prezintă aceeași interfață ILLMService consumatorilor.
Suita de teste validează căile critice: testele SQL parser verifică fix-ul regex stateful, blocarea pattern-urilor de injecție și permisiunea funcțiilor legitime CAST/DATE. Testele de validare acoperă schemele Zod și sanitizarea IP/user-agent. Testele de servicii mockuiesc răspunsurile LLM și verifică logica de retry. Testele tracker confirmă batching-ul cozii și comportamentul de fallback network.
05 / Aspecte selectate
Deciziile și fluxurile cu cea mai mare valoare explicativă.
06 / Metrici susținute
TypeScript, Node.js, Express.js, React, Vite, PostgreSQL, OpenAI, Anthropic, Google Gemini, TailwindCSS, Recharts, Zod, Helmet.js, Docker, Jest, Vercel AI SDK
Vezi repository-ul sursă