Add chatbot documentation and Claude agent SDK resources

chatbot/prd.md

@@ -0,0 +1,561 @@
+# Product Requirements Document (PRD)
+## Chatbot de Suport Tehnic RAG pentru ROMFAST
+
+## 1. OVERVIEW ȘI OBIECTIVE
+
+### 1.1 Problem Statement
+ROMFAST necesită un sistem de suport tehnic 24/7 care poate:
+- Răspunde la întrebări tehnice ale clienților
+- Oferi soluții bazate pe documentația existentă
+- Menține conversații context-aware
+- Funcționa independent de orice suport uman
+- Integrare perfectă cu website-ul existent
+
+### 1.2 Goals/Objectives
+**Business Goals:**
+- Reducerea costurilor de suport cu 50-70%
+- Îmbunătățirea satisfacției clienților (>4.0/5)
+- Timp de răspuns < 5 secunde
+- Disponibilitate 24/7
+
+**Technical Goals:**
+- Arhitectură scalabilă și maintainabilă
+- Upgrade de la Flowise + Groq la Claude Agent SDK
+- Implementare RAG (Retrieval-Augmented Generation)
+- Session persistence și context awareness
+
+### 1.3 Success Metrics
+- **Response accuracy**: > 90% pe întrebări tehnice
+- **First query resolution**: > 75%
+- **User satisfaction**: > 4.0/5 rating
+- **System uptime**: > 99.5%
+- **Response time**: < 5 secunde (RAG + Claude)
+- **Page load time**: < 3 secunde (frontend)
+
+## 2. USER PERSONAS ȘI USE CASES
+
+### 2.1 Primary User Personas
+
+**Persona 1: Client Final**
+- Nume: Ion Popescu
+- Rol: Utilizator final al software-ului ROMFAST
+- Technical skill: Limited
+- Goals: Rezolvare rapidă a problemelor tehnice
+- Frustrations: Așteptarea lungă pentru suport, termeni tehnici complecși
+- Preferred communication: Limbaj simplu, soluții concrete
+
+**Persona 2: Administrator IT**
+- Nume: Maria Ionescu
+- Rol: IT Administrator la client ROMFAST
+- Technical skill: Advanced
+- Goals: Soluții tehnice detaliate, troubleshooting avansat
+- Frustrations: Răspunsuri generice, lipa detaliilor tehnice
+- Preferred communication: Documentație tehnică, pași detaliați
+
+**Persona 3: Contabil**
+- Nume: Elena Vasile
+- Rol: Utilizator aplicație contabilitate ROMFAST
+- Technical skill: Basic
+- Goals: Rezolvare rapidă erori de conectare/date
+- Preferred communication: Instrucțiuni step-by-step
+
+### 2.2 Primary Use Cases
+
+**UC1: Erori de Conexiune**
+- User întâmpină eroare la conectare
+- caută soluții rapide și clare
+- necesită pași concreți de rezolvare
+
+**UC2: Întrebări Tehnice Generale**
+- User întreabă despre funcționalități
+- necesită explicații detaliate
+- vrea exemple concrete de utilizare
+
+**UC3: Problema Specifică Software**
+- User raportează bug/error mesaj specific
+- necesită identificarea cauzei
+- vrea soluție/workaround
+
+**UC4: Integrare și Setup**
+- Administrator necesită configurare sistem
+- vrea documentație tehnică detaliată
+- necessită best practices și configurații
+
+### 2.2 Telegram Use Cases
+
+**TU1: Quick Commands Access**
+- User deschide Telegram bot
+- Accesează rapid meniul principal cu `/menu`
+- Navighează prin categorii predefined
+- Selectează acțiuni rapide fără typing
+
+**TU2: Session Management**
+- User începe conversație pe website, continuă pe Telegram
+- Utilizează `/clear` pentru reset sesiune
+- Accesează istoric cu `/history`
+- Menține context între platforme
+
+**TU3: Structured Problem Reporting**
+- User folosește menu pentru a selecta categoria problemei
+- Bot adresează întrebări specifice pentru diagnostic
+- Oferă solutions step-by-step
+- Permite escalare către suport uman dacă needed
+
+**TU4: On-the-Go Assistance**
+- Mobile user în teren întâmpină problemă
+- Folosește Telegram pentru quick help
+- Primește concise, mobile-friendly responses
+- Generează documentație offline format pentru download
+
+## 3. FUNCTIONAL REQUIREMENTS
+
+### 3.1 Core Chatbot Functionality
+**FR1: Question Processing**
+- Accept întrebări în limbaj natural (română/engleză)
+- Parse și understand intent-ul utilizatorului
+- Extract key terms pentru better RAG retrieval
+- Handle typos și spelling errors
+
+**FR2: RAG Integration**
+- Search în knowledge base pentru relevant content
+- Ranking results după relevance score
+- Include source citations în răspunsuri
+- Handle cases where no relevant info found
+
+**FR3: Response Generation**
+- Generate contextual responses folosind Claude Agent SDK
+- Include step-by-step solutions pentru probleme tehnice
+- Maintain consistent brand voice (ROMFAST style)
+- Provide alternative solutions dacă primary nu funcționează
+
+**FR4: Session Management**
+- Maintain conversation context across multiple turns
+- Remember previous questions și answers
+- Reference earlier conversation în current responses
+- Session persistence across browser refresh
+
+### 3.2 User Interface Requirements
+**FR5: Chat Interface**
+- Clean, professional UI design matching ROMFAST branding
+- Responsive design (mobile & desktop)
+- Real-time typing indicators
+- Message history scrollable
+- Input field with character limit
+
+**FR6: Accessibility Features**
+- Keyboard navigation support
+- Screen reader compatibility
+- High contrast mode option
+- Font size adjustment
+
+**FR7: Message Display**
+- Clear distinction între user și bot messages
+- Timestamps pentru fiecare message
+- Source citations displayed clearly
+- Error messages displayed user-friendly
+
+### 3.3 Integration Requirements
+**FR8: URL Parameter Support**
+- Support `?message=intrebare` parameter
+- Auto-fill input field cu parameter
+- Auto-send message după page load
+- Handle URL encoding/decoding properly
+
+**FR9: Cross-Origin Communication**
+- API calls către backend LXC container
+- CORS configuration pentru cross-origin requests
+- HTTPS encryption pentru API calls
+- Error handling pentru network issues
+
+**FR10: Local Storage Management**
+- Store session ID în localStorage
+- Persistent conversation history
+- Auto-cleanup după X days
+- Privacy-compliant data storage
+
+### 3.3 Telegram Bot Functionality
+**FR11: Command Processing**
+- Handle slash commands (/menu, /clear, /help, /start, /history)
+- Parse và process bot commands cu python-telegram-bot
+- Command descriptions displayed în help menu
+- Context-aware command availability
+
+**FR12: Interactive Menu System**
+- Hierarchical menu structure cu inline keyboards
+- Category navigation (Conectare, Erori, Configurare, etc.)
+- Quick action buttons pentru common issues
+- Back navigation în menu hierarchy
+- Dynamic menu updates based on context
+
+**FR13: Session Management (Telegram)**
+- User session tracking prin Telegram user_id
+- Cross-platform session synchronization
+- Session persistence across bot restarts
+- Private session storage pentru confidentiality
+
+**FR14: Response Formatting pentru Telegram**
+- Markdown formatting pentru rich text responses
+- Code blocks pentru technical instructions
+- Inline URL generation pentru documentation links
+- Message length optimization (Telegram 4096 char limit)
+- Support pentru media attachments (PDF, images)
+
+**FR15: Error Handling și Recovery (Telegram)**
+- Graceful error handling pentru API failures
+- User-friendly error messages în Telegram
+- Retry mechanisms pentru failed requests
+- Escalation options pentru complex issues
+- Fallback messages când RAG returns no results
+
+## 4. NON-FUNCTIONAL REQUIREMENTS
+
+### 4.1 Performance Requirements
+**NFR1: Response Time**
+- API response < 5 secunde (including RAG retrieval)
+- Frontend load time < 3 secunde
+- UI interaction response < 200ms
+- Real-time typing indicators < 100ms delay
+
+**NFR2: Scalability**
+- Support concurrent 100+ users
+- Handle 1000+ questions per day
+- Backend auto-scaling cu Docker
+- Database optimization pentru fast retrieval
+
+**NFR3: Reliability**
+- System uptime > 99.5%
+- Graceful degradation pentru partial failures
+- Automatic error recovery
+- Backup și recovery procedures
+
+### 4.2 Security Requirements
+**NFR4: Data Privacy**
+- No personal data storage beyond session
+- Encrypted API communications
+- Rate limiting pentru abuse prevention
+- Input validation pentru XSS prevention
+
+**NFR5: Authentication**
+- No user authentication required (anonymous sessions)
+- Session ID generation secure enough
+- Protection against session hijacking
+- CSRF protection pentru API calls
+
+### 4.3 Maintainability
+**NFR6: Code Quality**
+- Clean, documented code
+- Separation of concerns
+- Unit tests pentru critical components
+- CI/CD pipeline pentru deployments
+
+**NFR7: Monitoring și Debugging**
+- Comprehensive logging
+- Performance metrics collection
+- Error tracking și alerting
+- User interaction analytics
+
+## 5. TECHNICAL ARCHITECTURE
+
+### 5.1 Frontend Requirements
+**TR1: Technology Stack**
+- HTML5 semantic markup
+- ES6+ JavaScript (vanilla, no frameworks)
+- CSS3 cu modern layout (Grid/Flexbox)
+- Fetch API pentru backend communication
+
+**TR2: Component Architecture**
+- Modular JavaScript structure
+- Event-driven architecture
+- Component-based UI elements
+- Plugin-ready architecture pentru future extensions
+
+### 5.2 Backend Requirements
+**TR3: API Layer**
+- FastAPI RESTful endpoints
+- JSON request/response format
+- HTTP status codes standard
+- OpenAPI documentation
+
+**TR4: AI/ML Integration**
+- Claude Agent SDK integration
+- RAG pipeline cu Chroma vector DB
+- Embedding models pentru text processing
+- Context management pentru conversations
+
+**TR5: Data Layer**
+- ChromaDB pentru vector storage
+- In-memory session store
+- File-based knowledge base storage
+- Backup procedures pentru data persistence
+
+### 5.3 Infrastructure Requirements
+**TR6: Deployment Architecture**
+- Docker containerization
+- Proxmox LXC deployment
+- Static IP configuration
+- SSL certificate management
+
+**TR7: Network Requirements**
+- Public IP exposure pentru API
+- Firewall configuration
+- DDoS protection setup
+- CDN integration caching (opțional)
+
+### 5.4 Telegram Integration Architecture**
+**TR8: Telegram Bot Requirements**
+- **Bot Framework**: python-telegram-bot library
+- **Bot Commands**: Structured commands cu slash (/menu, /clear, /help)
+- **Menu System**: Interactive inline keyboards pentru navigation
+- **Session Management**: Per-user session persistence
+- **Message Types**: Support text, commands, și callback queries
+
+**TR9: Claude Agent SDK Integration cu Telegram**
+- **Message Processing**: Claude responses adapted pentru Telegram format
+- **Tool Integration**: MCP servers accessible din Telegram context
+- **Session Continuity**: Same session across website și Telegram
+- **Context Preservation**: Conversation history maintained platform-agostic
+
+**TR10: Backend Communication**
+- **Shared Service**: Common backend service pentru website și Telegram
+- **Session Synchronization**: Sync sessions între platforms
+- **Response Formatting**: Platform-specific response formatting
+- **Error Handling**: Graceful degradation pentru Telegram limitations
+
+**TR11: Telegram-Specific Features**
+- **Command Handlers**: /start, /help, /menu, /clear, /history
+- **Interactive Menus**: Category navigation, quick actions
+- **Callback Queries**: Menu selections, confirmations
+- **Status Messages**: Typing indicators, processing states
+
+## 6. USER EXPERIENCE REQUIREMENTS
+
+### 6.1 Interaction Design
+**UX1: Conversation Flow**
+- Natural conversatională flow
+- Proactive suggestions pentru follow-up
+- Clear confirmation messages
+- graceful handling pentru misunderstood questions
+
+**UX2: Error Management**
+- Friendly error messages
+- Alternative suggestions când nu înțeleg
+- Option to rephrase questions
+- Human hand-off option (future)
+
+**UX3: Visual Design**
+- ROMFAST brand alignment (colors, fonts)
+- Professional appearance
+- Intuitive UI elements
+- Consistent spacing și typography
+
+### 6.2 Telegram User Experience
+**UX6: Telegram Bot Interface**
+- Intuitive command menu structure
+- Clear menu labels și descriptions
+- Consistent button design și placement
+- Responsive layout pentru mobile screens
+
+**UX7: Telegram Commands Design**
+- **/start**: Welcome message și quick tutorial
+- **/menu**: Interactive menu cu main categories
+- **/clear**: Clear current session și start fresh
+- **/help**: List all available commands și usage
+- **/history**: Show conversation history summary
+
+**UX8: Telegram Navigation Patterns**
+- Hierarchical menu flow cu back buttons
+- Quick return to main menu option
+- Context-sensitive menu items
+- Visual feedback pentru button clicks
+
+**UX9: Telegram Response Structure**
+- Short, mobile-friendly responses
+- Bulleted lists pentru step-by-step instructions
+- Code blocks formatted properly
+- Emojis în moderation în brand consistency
+
+### 6.4 Accessibility și Usability
+**UX5: Mobile Experience**
+- Touch-friendly interface
+- Optimized pentru smartphones
+- Vertical layout preference
+- Voice input support (future)
+
+**UX6: Localization**
+- Limbavă română primary
+- English as secondary
+- Date/times local format
+- Currency formatting (dacă relevant)
+
+## 7. CONSTRAINTS ȘI ASSUMPTIONS
+
+### 7.1 Technical Constraints
+**C1: Hosting Environment**
+- Frontend: Shared hosting (no server-side access)
+- Backend: LXC Docker container limits
+- No direct database access from frontend
+- Static file serving constraints
+
+**C2: Budget Constraints**
+- Claire Max subscription cost limits
+- LXC resource limits (CPU/RAM)
+- Third-party service dependencies
+- Maintenance cost considerations
+
+### 7.2 Business Constraints
+**C3: Timeline**
+- Maximum 5 days pentru implementation
+- Parallel development possible
+- Phased roll-out approach
+- Minimal disruption la existing services
+
+**C4: Compliance**
+- GDPR compliance pentru user data
+- No sensitive data storage
+- Data retention policies
+- User consent requirements
+
+### 7.3 Assumptions
+**A1: User Behavior**
+- Users comfortable cu chat interfaces
+- Basic computer literacy
+- Access la modern browsers
+- Stable internet connection
+
+**A2: Technical Environment**
+- Modern browser support (last 2 versions)
+- JavaScript enabled
+- HTTPS support
+- Mobile browser compatibility
+- Telegram app access (mobile și desktop)
+- Stable internet connection pentru API calls
+
+## 8. SUCCESS CRITERIA ȘI LAUNCH REQUIREMENTS
+
+### 8.1 MVP Definition
+**Minimum Viable Product includes:**
+- Basic chat interface with RAG responses
+- Session persistence
+- URL parameter support
+- Mobile responsive design
+- Basic error handling
+
+### 8.2 Launch Criteria
+**Technical readiness:**
+- All functional requirements implemented
+- Security testing completed
+- Performance benchmarks met
+- Backup procedures documented
+
+**Business readiness:**
+- Knowledge base populated cu relevant content
+- Support team trained pe system
+- User documentation prepared
+- Communication plan ready
+- Telegram bot published și functional
+- Cross-platform session testing completed
+
+### 8.3 Post-Launch Requirements
+**PL1: Monitoring și Analytics**
+- User interaction tracking
+- Response quality metrics
+- System performance monitoring
+- Error rate tracking
+
+**PL2: Iteration Plan**
+- Weekly performance reviews
+- Monthly content updates
+- Quarterly feature enhancements
+- Annual architecture review
+
+## 9. RISK ASSESSMENT ȘI MITIGATION
+
+### 9.1 Technical Risks
+**Risk 1: Claude API Limits**
+- Impact: Service degradation
+- Probability: Medium
+- Mitigation: Local fallbacks, graceful degradation
+
+**Risk 2: Cross-Origin Issues**
+- Impact: Frontend-backend communication failure
+- Probability: High
+- Mitigation: CORS testing, fallback mechanisms
+
+**Risk 3: Knowledge Base Incomplet**
+- Impact: Poor response quality
+- Probability: Medium
+- Mitigation: Content gaps analysis, gradual population
+
+### 9.2 Business Risks
+**Risk 4: User Adoption Low**
+- Impact: Investment not justified
+- Probability: Medium
+- Mitigation: User training, promotional activities
+
+**Risk 5: Performance Issues**
+- Impact: Poor user experience
+- Probability: Medium
+- Mitigation: Performance testing, optimization
+
+## 10. FUTURE ROADMAP (Post-Launch)
+
+### 10.1 Phase 1 (1-3 months)
+- **Telegram Bot Launch**: Complete Telegram integration
+- **Advanced Commands**: /ticket, /escalate, /feedback
+- **Media Support**: File upload/download capabilities
+- **Analytics Dashboard**: Admin interface pentru insights
+- **Knowledge Base Admin**: easier content management
+
+### 10.2 Phase 2 (3-6 months)
+- **Multi-platform Sync**: Seamless session sync website ↔ Telegram
+- **Voice Input Support**: Dictation features pentru mobile
+- **Integration APIs**: Connect cu CRM/ticket systems
+- **Advanced Personalization**: User profiles și preferences
+- **Telegram Channels**: Broadcast announcements și updates
+
+### 10.3 Phase 3 (6-12 months)
+- **Video Tutorials**: Embedded video content în responses
+- **Community Q&A**: Social features pentru peer support
+- **Analytics Dashboard**: Advanced tracking și insights
+- **Integration APIs**: Connect cu CRM/ticket systems
+
+### 10.4 Long-term Vision
+- **Mobile App**: Native iOS/Android applications
+- **Voice Assistant**: Phone bot integration
+- **AI Agent Tools**: Diagnostic și troubleshooting automation
+- **Predictive Support**: Proactive issue identification
+
+---
+
+## ACCEPTANCE CRITERIA
+
+### Functional Acceptance
+- [ ] Chatbot answers 90% of technical questions accurately based on knowledge base
+- [ ] System maintains context across conversation turns
+- [ ] URL parameter auto-fills and auto-sends messages
+- [ ] Sessions persist across browser refreshes
+- [ ] Mobile responsive design works on all major devices
+- [ ] Error handling provides user-friendly messages
+
+### Technical Acceptance
+- [ ] API response time < 5 seconds including RAG
+- [ ] Frontend loads in < 3 seconds
+- [ ] System handles 100+ concurrent users
+- [ ] CORS communication works properly
+- [ ] SSL encryption implemented for API calls
+- [ ] Session persistence works reliably
+
+### Business Acceptance
+- [ ] User satisfaction score > 4.0/5
+- [ ] Support cost reduction measurable
+- [ ] System uptime > 99.5%
+- [ ] Knowledge base populated with essential documentation
+- [ ] Support team trained on system operation
+
+---
+
+*Document Version: 1.1*
+*Created: 24 Octombrie 2025*
+*Last Updated: 24 Octombrie 2025*
+*Status: Ready for Implementation*
+*Changes: Added Telegram Bot Integration Section*

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*

chatbot/v2-arhitectura.md

@@ -0,0 +1,125 @@
+## 1. Introducere și Context
+Chatbot-ul de suport tehnic ROMFAST va oferi răspunsuri asistate de RAG și Claude Agent SDK atât pe website, cât și în Telegram. Arhitectura propusă trebuie să asigure timpul de răspuns sub 5 secunde, disponibilitate ridicată, persistența sesiunilor și integrarea cu infrastructura existentă (Docker în LXC Proxmox).
+
+## 2. Mapare Cerințe → Soluții Arhitecturale
+| Cerință cheie | Soluție arhitecturală |
+| --- | --- |
+| FR1, FR2, FR3 | Pipeline RAG (ChromaDB + Claude Agent SDK) cu preprocesare întrebări și scorare rezultate |
+| FR4, FR10 | Session store (Redis sau SQLite in-memory backup) accesat de frontend, backend și Telegram |
+| FR5–FR7 | Frontend web modular (HTML/JS/CSS) + API JSON standard |
+| FR8, FR9 | FastAPI gateway cu CORS, HTTPS și suport query param `message` |
+| FR11–FR15 | Microserviciu Telegram bazat pe python-telegram-bot conectat la același backend |
+| NFR1–NFR3 | Containere Docker separate, auto-restart Proxmox, load shedding și cache răspunsuri |
+| NFR4–NFR7 | TLS end-to-end, rate limiting, observability (logging centralizat, metrics, alerting) |
+
+## 3. Vedere Arhitecturală de Nivel Înalt
+- **Client Web**: UI chat responsiv, gestionează sesiuni locale și comunică cu backend via Fetch API.
+- **Gateway API (FastAPI)**: Orchestrare request-uri, autentificare sesiunilor anonime, fan-out către servicii interne.
+- **Serviciu RAG**: Normalizare întrebări, căutare vectorială în ChromaDB, construirea contextului și apel Claude.
+- **ChromaDB + Knowledge Store**: Vectori și metadate pentru documentația ROMFAST, pipeline ingestie periodică.
+- **Session Store**: Stocare conversații și context (Redis/SQLite replicat) pentru persistență cross-platform.
+- **Telegram Bot Service**: Handler comenzi, UI prin inline keyboards, sincronizare sesiuni cu gateway-ul.
+- **Observability Stack**: Logging structurat, export metrics (Prometheus compatible) și alerting.
+- **Infrastructură Docker pe Proxmox LXC**: Containere orchestrate manual sau cu docker-compose, SSL terminat via Traefik/nginx reverse proxy.
+
+## 4. Descriere Componentă cu Componentă
+### 4.1 Client Web
+- **Responsabilități**: UI chat, tip indicators, gestionare localStorage (ID sesiune, istoric recent), trimis întrebări, afișare surse.
+- **Tehnologii**: HTML5, CSS3 (Flex/Grid), ES6 modules, Fetch API, Web Workers opțional pentru preprocesare.
+- **Interfețe**: API REST `/api/chat`, `/api/session`, evenimente SSE/WebSocket pentru actualizări opționale.
+- **Scalare**: Servire statică prin CDN/lightweight web server; caching agresiv pentru assets.
+
+### 4.2 Gateway API (FastAPI)
+- **Responsabilități**: Validare input, rate limiting, orchestrare RAG, management erori, transformare răspunsuri.
+- **Tehnologii**: FastAPI, Uvicorn, Pydantic, middleware CORS/HTTPS, JWT stateless pentru sesiuni anonime (semnare internă).
+- **Interfețe**: REST endpoints `/chat`, `/session`, `/history`, `/health`; webhook Telegram `/telegram/webhook`.
+- **Scalare**: Replicare container, load balancing prin reverse proxy, timeouts stricte, circuit breaker către Claude API.
+
+### 4.3 Serviciu RAG
+- **Responsabilități**: Curățare întrebări, vectorizare (embedding), căutare top-k în ChromaDB, compunere context și prompt engineering pentru Claude.
+- **Tehnologii**: Python, Claude Agent SDK, sentence-transformers (embedding), langchain-like orchestrator.
+- **Interfețe**: gRPC/REST intern expus gateway-ului, contract clar pentru request/response (query, session_id, metadata).
+- **Scalare**: Worker pool asincron, caching răspunsuri populare, fallback la knowledge base static în caz de indisponibilitate Claude.
+
+### 4.4 ChromaDB și Knowledge Store
+- **Responsabilități**: Stocare vectori, metadate, versiuni documentație.
+- **Tehnologii**: ChromaDB container, storage montat persistent (volume Proxmox), pipeline ingestie (Python ETL) cu scheduler.
+- **Interfețe**: API nativ Chroma, scripturi ingestie (loaders), export pentru backup.
+- **Scalare**: Partajare colecții pe namespace, sharding logic pentru domenii (Contabilitate, Admin, etc.), snapshot backup zilnic.
+
+### 4.5 Session Store
+- **Responsabilități**: Persistență context conversație, state comenzi Telegram, token TTL.
+- **Tehnologii**: Redis (preferat) cu fallback SQLite on-disk, replică la cald.
+- **Interfețe**: API key/value, TTL, liste pentru istoricul recent; acces prin SDK Python și JS.
+- **Scalare**: Master/replica, persistare RDB/AOF, monitorizare memorie.
+
+### 4.6 Telegram Bot Service
+- **Responsabilități**: Gestionare comenzi `/start`, `/menu`, etc., generare inline keyboard, relay întrebări către gateway, formatting Markdown.
+- **Tehnologii**: python-telegram-bot, async handlers, job queue pentru retry.
+- **Interfețe**: Webhook către gateway, REST fallback polling, servicii interne pentru sesiuni.
+- **Scalare**: Replici multiple cu queue deduplicare (Redis Streams), respectarea rate limit Telegram.
+
+### 4.7 Observability și DevOps
+- **Responsabilități**: Logging centralizat, metrics (latency, usage), alerting, CI/CD pipelines.
+- **Tehnologii**: Elastic Stack sau Loki+Grafana, Prometheus exporters, Sentry/Opentelemetry pentru tracing.
+- **Interfețe**: Dashboards Grafana, webhook alerting (Slack/Email), pipeline GitHub Actions.
+- **Scalare**: Retenție loguri 30 zile, sampling tracing, rotație indices.
+
+### 4.8 Infrastructură și Securitate
+- **Responsabilități**: Orchestrare containere, management certificate, firewall, backup.
+- **Tehnologii**: Docker, docker-compose, Traefik/nginx, Proxmox backup server, CrowdSec/Fail2ban.
+- **Interfețe**: Reverse proxy, Let’s Encrypt ACME, scripturi deployment.
+- **Scalare**: Vertical scaling LXC, pregătire migrare spre Kubernetes/Nomad dacă load crește.
+
+## 5. Fluxuri de Date și Sequencing
+### 5.1 Întrebare din Client Web
+1. UI trimite request `POST /api/chat` cu mesaj și session_id.
+2. Gateway validează, atașează metadata (persona, limbă) și trimite către serviciul RAG.
+3. Serviciul RAG vectorizează, interoghează ChromaDB, compune prompt cu surse.
+4. Claude Agent SDK generează răspuns, gateway-l adnotează cu surse și pași.
+5. Răspunsul este salvat în session store și returnat UI-ului pentru afișare.
+
+### 5.2 Întrebare din Telegram
+1. Bot primește mesaj/comandă și trimite payload la webhook-ul gateway-ului.
+2. Gateway mapează Telegram user_id la session_id comun și procesează similar cu fluxul web.
+3. Răspunsul este formatat Markdown, validat sub 4096 caractere și trimis înapoi prin bot.
+4. Istoricul este sincronizat în session store pentru acces cross-platform.
+
+### 5.3 Manevrarea Erorilor/Fallback
+1. Dacă Claude sau Chroma sunt indisponibile, gateway revine la răspunsuri cached sau FAQ static.
+2. În caz de eroare critică, gateway trimite mesaj prietenos utilizatorului și loghează incidentul.
+3. Scheduler declanșează alerting și reinstanțează containerul afectat.
+
+## 6. Persistență și Management Date
+- **Sesiuni**: session store cu TTL configurabil (7 zile), replicat, curățare periodică.
+- **Vectori**: ChromaDB cu versiuni documente, index rebuild săptămânal, backup incremental.
+- **Knowledge base raw**: Fișiere markdown/PDF într-un storage versionat (Git + backup Proxmox).
+- **Loguri și Metrics**: Centralizare în Loki/Elastic, metrics în Prometheus, retenție 30 zile.
+
+## 7. Integrare Telegram Specifică
+- Webhook securizat (secret token) expus prin reverse proxy HTTPS.
+- Mapare user_id ↔ session_id în session store pentru continuitate conversații.
+- Gestionare rate limiting Telegram cu queue și exponential backoff.
+- Menu builder modular pentru categorii (Conectare, Erori, Configurare) configurabile din metadata.
+- Fallback la notificare suport uman prin integrare viitoare (webhook spre ticketing).
+
+## 8. Securitate, Conformitate și Observabilitate
+- **Transport**: TLS end-to-end, HSTS, certificate auto-întreținute.
+- **Rate limiting**: NGINX/Traefik + Redis counters pentru prevenire abuz.
+- **Validare input**: Sanitizare text, limită caractere, filtrare cod malițios.
+- **Privacy**: Stocare minimă, criptare at rest pentru vectori și backup, politici GDPR (drept de ștergere).
+- **Monitoring**: Health checks `/healthz`, dashboards latență, error rate, uptime.
+- **Alerting**: Prag >3% erori, răspuns >4 secunde, spațiu disk <15% liber.
+
+## 9. Scalabilitate și Reziliență
+- Containere separate pentru gateway, RAG, Chroma, Telegram cu resurse dedicate.
+- Auto-restart și watchdog scripts în Proxmox, backup zilnic volume critice.
+- Circuit breakers și retry policy către Claude API, degrade gracefully la fallback static.
+- Posibilă introducere CDN pentru livrare statice și caching răspunsuri frecvente.
+
+## 10. Roadmap Tehnic (0–6 luni)
+- **Luna 0–1**: Implementare client web + gateway API + RAG minim (Chroma + Claude), ingestie documentație de bază.
+- **Luna 1–2**: Adăugare session store distribuit, logging centralizat, pipeline ingestie automat.
+- **Luna 2–3**: Lansare Telegram bot cu comenzi de bază, sincronizare sesiuni, fallback complet erori.
+- **Luna 3–4**: Introducere metrics/alerting, optimizare performanță, cache răspunsuri.
+- **Luna 4–6**: Extindere knowledge base, analytics dashboard, pregătire pentru scaling (replici, load balancing).