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*