126 lines
9.2 KiB
Markdown
126 lines
9.2 KiB
Markdown
## 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).
|