Add chatbot documentation and Claude agent SDK resources

chatbot/v1-arhitectura.md

@@ -0,0 +1,131 @@
+# Plan: Chatbot RAG pentru romfast.ro
+
+## ARHITECTURĂ GENERALĂ
+
+```
+Website romfast.ro (shared hosting) → HTTPS API calls → Backend Docker LXC → Claude Agent SDK + RAG
+                                     ↑
+                              chatbot.html (static + JS)
+```
+
+## STRUCTURA SOLUȚIEI
+
+### Frontend (pe shared hosting romfast.ro)
+- **chatbot.html**: Pagină statică minimală (skeleton HTML)
+- **chatbot.js**: Tot codul JavaScript (generează HTML dinamic, face API calls)
+- **CSS injectat**: Generate dinamic prin JavaScript
+- **localStorage**: Pentru session persistence
+
+### Backend (Docker în LXC Proxmox)
+- **FastAPI**: Doar 2 endpoints (`/ask` și health check)
+- **Claude Agent SDK**: Integrare pentru răspunsuri inteligente
+- **RAG System**: Chroma + embeddings pentru knowledge base
+- **No web serving**: Doar backend API
+
+### Comunicare
+- **HTTPS API calls**: Direct de la browser către IP-ul LXC
+- **CORS**: Configurat în FastAPI pentru cross-origin
+- **JSON communication**: Standard REST API
+
+## IMPLEMENTARE
+
+### Faza 1: Backend LXC (2-3 zile)
+1. **Setup LXC**: Ubuntu 22.04 cu Docker
+2. **Build backend**: FastAPI + Claude SDK + RAG
+3. **Knowledge base**: Upload documente tehnice
+4. **Test endpoints**: `/ask` și health check
+
+### Faza 2: Frontend Integration (1-2 zile)
+1. **chatbot.html**: Adaugă pe website-ul romfast.ro
+2. **chatbot.js**: JavaScript complete pentru UI și API calls
+3. **Test communication**: Cross-origin API calls
+4. **Mobile responsive**: Adaptare pentru mobile
+
+### Faza 3: Production Setup (1 zi)
+1. **IP public**: Asigură acces la LXC container
+2. **Security**: Rate limiting, CORS settings
+3. **Testing**: Functionality și performance
+4. **Documentation**: Setup instructions
+
+## UTILIZARE
+
+### Access Patterns
+- **Direct URL**: `romfast.ro/chatbot.html?message=eroare+conexiune`
+- **Empty start**: `romfast.ro/chatbot.html`
+- **Link integration**: Din alte pagini cu parameters predefinite
+
+### User Flow
+1. **User opens** chatbot.html (cu sau fără message)
+2. **JavaScript generează** UI-ul dinamic
+3. **API call către backend** întrebarea
+4. **Backend procesează** cu Claude + RAG
+5. **JavaScript afișează** răspunsul și sursele
+6. **Session persist** în localStorage
+
+## TECH STACK
+
+### Frontend (Shared Hosting)
+- **HTML5** static
+- **Vanilla JavaScript** (ES6+)
+- **CSS** generated via JS
+- **localStorage** pentru sessions
+- **Fetch API** pentru backend calls
+
+### Backend (LXC Docker)
+- **FastAPI** (Python 3.11)
+- **Claude Agent SDK**
+- **ChromaDB** (vector storage)
+- **Uvicorn** (ASGI server)
+- **Docker** pentru containerization
+
+### Infrastructure
+- **Proxmox LXC**: 2 CPU, 2GB RAM, 20GB SSD
+- **Public IP**: Pentru API access
+- **HTTPS**: Certificat SSL pentru API
+- **No reverse proxy**: Direct exposure (simplificat)
+
+## BENEFICII
+
+### ✅ Technical
+- **Fără dependențe de hosting infrastructure**
+- **Separation of concerns**: UI vs backend
+- **Scalable backend** independent de frontend
+- **Easy updates**: Frontend direct pe website
+
+### ✅ Business
+- **Zero additional hosting costs**
+- **Full control** asupra backend
+- **Professional appearance** pentru clienți
+- **Multiple entry points**: GET parameters, direct access
+
+### ✅ Maintenance
+- **Simple stack**: JS + FastAPI
+- **Independent deployments**
+- **Easy debugging** și testing
+- **Standard web technologies**
+
+## CONSTRAINTS & SOLUTIONS
+
+### Constraint: No Nginx access
+**Solution**: Direct HTTPS API calls către LXC IP
+
+### Constraint: Shared hosting
+**Solution**: Frontend static, backend separate
+
+### Security: Cross-origin requests
+**Solution**: CORS configuration în FastAPI
+
+## SUCCESS METRICS
+
+- **Setup time**: < 5 zile total
+- **Page load**: < 3 secunde (HTML static)
+- **API response**: < 5 secunde (RAG + Claude)
+- **Mobile support**: 100% responsive
+- **Session persistence**: > 95% reliability
+
+Acest plan oferă o soluție **practică și implementabilă** în condițiile de shared hosting, cu **arhitectură clar separată** și **deploy minim complex**.
+
+---
+
+*Creat: 24 Octombrie 2025*
+*Status: Plan de arhitectură - așteptare aprobare*