## 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).