ROMFASTSQL/chatbot/v1-arhitectura.md

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