documente/frontend-plan.md

Piano di Sviluppo Frontend - AgenticRAG

📋 Overview

Sviluppo di un'interfaccia web moderna per AgenticRAG utilizzando React 18 + Vite + TypeScript + Tailwind CSS + shadcn/ui.

---

🎯 Obiettivi

1. Dashboard Intuitiva - Overview del sistema e statistiche
2. Gestione Documenti - Upload, preview, e organizzazione
3. Chat Avanzata - Interfaccia conversazionale con RAG
4. Configurazione Provider - Selezione e gestione LLM
5. Responsive Design - Mobile-first, tema chiaro/scuro

---

🏗️ Architettura

frontend/
├── public/
│   └── favicon.ico
├── src/
│   ├── components/           # Componenti React
│   │   ├── layout/          # Layout components
│   │   │   ├── Navbar.tsx
│   │   │   ├── Sidebar.tsx
│   │   │   └── Layout.tsx
│   │   ├── dashboard/       # Dashboard components
│   │   │   ├── StatsCard.tsx
│   │   │   ├── RecentDocuments.tsx
│   │   │   └── ActivityFeed.tsx
│   │   ├── documents/       # Document management
│   │   │   ├── UploadZone.tsx
│   │   │   ├── DocumentList.tsx
│   │   │   ├── DocumentPreview.tsx
│   │   │   └── DocumentCard.tsx
│   │   ├── chat/            # Chat interface
│   │   │   ├── ChatContainer.tsx
│   │   │   ├── MessageList.tsx
│   │   │   ├── MessageBubble.tsx
│   │   │   ├── SourceCitations.tsx
│   │   │   └── ChatInput.tsx
│   │   └── settings/        # Settings components
│   │       ├── ProviderSelector.tsx
│   │       ├── ModelSelector.tsx
│   │       └── ThemeToggle.tsx
│   ├── hooks/               # Custom React hooks
│   │   ├── useAuth.ts
│   │   ├── useDocuments.ts
│   │   ├── useChat.ts
│   │   ├── useProviders.ts
│   │   └── useTheme.ts
│   ├── api/                 # API client
│   │   ├── client.ts
│   │   ├── documents.ts
│   │   ├── chat.ts
│   │   └── providers.ts
│   ├── types/               # TypeScript types
│   │   ├── document.ts
│   │   ├── chat.ts
│   │   ├── provider.ts
│   │   └── auth.ts
│   ├── stores/              # State management (Zustand)
│   │   ├── authStore.ts
│   │   ├── chatStore.ts
│   │   └── settingsStore.ts
│   ├── lib/                 # Utilities
│   │   ├── utils.ts
│   │   └── constants.ts
│   ├── pages/               # Route pages
│   │   ├── Dashboard.tsx
│   │   ├── Documents.tsx
│   │   ├── Chat.tsx
│   │   ├── Settings.tsx
│   │   └── Login.tsx
│   ├── App.tsx
│   ├── main.tsx
│   └── index.css
├── index.html
├── package.json
├── tsconfig.json
├── vite.config.ts
├── tailwind.config.js
└── components.json          # shadcn/ui config

---

📦 Stack Tecnologico

Categoria	Tecnologia	Versione
Framework	React	^18.2.0
Build Tool	Vite	^5.0.0
Language	TypeScript	^5.0.0
Styling	Tailwind CSS	^3.4.0
UI Components	shadcn/ui	latest
Icons	Lucide React	^0.300.0
State	Zustand	^4.4.0
HTTP Client	Axios	^1.6.0
Routing	React Router DOM	^6.20.0
Forms	React Hook Form	^7.48.0
Validation	Zod	^3.22.0

---

🎨 Design System

Colori

/* Tema Chiaro */
--background: 0 0% 100%;
--foreground: 222.2 84% 4.9%;
--primary: 221.2 83.2% 53.3%;
--secondary: 210 40% 96.1%;
--accent: 210 40% 96.1%;
--muted: 210 40% 96.1%;
--border: 214.3 31.8% 91.4%;

/* Tema Scuro */
--background: 222.2 84% 4.9%;
--foreground: 210 40% 98%;
--primary: 217.2 91.2% 59.8%;
--secondary: 217.2 32.6% 17.5%;
--accent: 217.2 32.6% 17.5%;
--muted: 217.2 32.6% 17.5%;
--border: 217.2 32.6% 17.5%;

Componenti shadcn/ui da Installare

• button - Pulsanti
• card - Card contenitori
• dialog - Modali
• dropdown-menu - Menu a discesa
• input - Input testuali
• label - Etichette
• select - Select dropdown
• separator - Separatori
• sheet - Side panels
• skeleton - Loading states
• tabs - Tab navigation
• textarea - Area di testo
• toast - Notifiche
• tooltip - Tooltip

---

📱 Pagine e Funzionalità

1. Login Page (/login)

• Form di autenticazione
• Supporto API Key o JWT
• Redirect post-login

2. Dashboard (/)

• Stats Overview: Documenti totali, query oggi, token usati
• Recent Documents: Ultimi 5 documenti caricati
• Quick Actions: Upload rapido, inizia chat
• Activity Feed: Log delle ultime attività

3. Documents (/documents)

• Upload Zone: Drag & drop multi-file
• Document List: Tabella con filtri e ricerca
• Document Preview: Modal con contenuto estratto
• Actions: Elimina, scarica, visualizza

4. Chat (/chat)

• Chat Interface: Stile ChatGPT/Claude
• Message Bubbles: User (destra) / AI (sinistra)
• Source Citations: Link ai documenti fonte
• Streaming: Risposte in tempo reale (SSE)
• History: Lista conversazioni precedenti
• New Chat: Pulsante nuova conversazione

5. Settings (/settings)

• Provider Selection: Dropdown provider LLM
• Model Selection: Lista modelli disponibili
• Theme Toggle: Chiaro/Scuro/Sistema
• API Configuration: Mostra provider configurati

---

🔌 API Integration

Endpoints Utilizzati

// Documents
GET    /api/v1/documents          // Lista documenti
POST   /api/v1/documents          // Upload documento
DELETE /api/v1/documents/{id}     // Elimina documento
GET    /api/v1/documents/{id}/content  // Contenuto estratto

// Query & Chat
POST   /api/v1/query              // Query RAG
POST   /api/v1/chat               // Chat endpoint

// Providers
GET    /api/v1/providers          // Lista provider
GET    /api/v1/providers/{id}/models  // Lista modelli
GET    /api/v1/config             // Configurazione
PUT    /api/v1/config/provider    // Aggiorna provider

Autenticazione

// API Key
headers: { 'X-API-Key': 'your-api-key' }

// JWT Token
headers: { 'Authorization': 'Bearer your-token' }

---

📋 Piano di Implementazione

Fase 1: Setup (2-3 giorni)

• Inizializzare progetto Vite + React + TypeScript
• Configurare Tailwind CSS
• Installare shadcn/ui
• Configurare struttura cartelle
• Setup routing con React Router
• Setup Zustand per state management
• Creare API client base

Fase 2: Layout & Navigazione (2 giorni)

• Implementare Layout component
• Creare Navbar con logo e user menu
• Implementare Sidebar navigation
• Aggiungere theme toggle
• Responsive design (mobile)

Fase 3: Autenticazione (1-2 giorni)

• Login page
• Auth hook (useAuth)
• Auth store (Zustand)
• Protected routes
• Logout functionality

Fase 4: Dashboard (2 giorni)

• Stats cards
• Recent documents list
• Activity feed
• Quick actions
• Real-time updates (optional)

Fase 5: Document Management (3 giorni)

• Upload zone (drag & drop)
• Document list table
• Search and filters
• Document preview modal
• Delete confirmation
• Progress indicators

Fase 6: Chat Interface (4-5 giorni)

• Chat container layout
• Message components
• Message input with submit
• Source citations display
• Streaming responses (SSE)
• Chat history sidebar
• Export conversation

Fase 7: Settings (2 giorni)

• Provider selector
• Model selector
• Theme settings
• Config display

Fase 8: Polish & Testing (2-3 giorni)

• Loading states
• Error handling
• Toast notifications
• E2E testing
• Performance optimization
• Accessibility audit

---

🚀 Comandi Utili

# Setup iniziale
cd frontend
npm create vite@latest . -- --template react-ts
npm install

# Install dependencies
npm install -D tailwindcss postcss autoprefixer
npx tailwindcss init -p

# Install shadcn/ui
npx shadcn-ui@latest init

# Install components
npx shadcn-ui@latest add button card dialog input label select tabs toast

# Install additional packages
npm install zustand axios react-router-dom lucide-react

# Development
npm run dev

# Build
npm run build

# Preview
npm run preview

---

🎨 Mockup UI

Dashboard

┌─────────────────────────────────────────────────────────┐
│  🧠 AgenticRAG      Dashboard  Documents  Chat  Settings│
├─────────────────────────────────────────────────────────┤
│                                                         │
│  ┌─────────────┐ ┌─────────────┐ ┌─────────────┐       │
│  │ 📄 Documents│ │ 💬 Queries  │ │ 🔤 Tokens   │       │
│  │    1,234    │ │    567      │ │   1.2M      │       │
│  └─────────────┘ └─────────────┘ └─────────────┘       │
│                                                         │
│  ┌─────────────────────┐ ┌──────────────────────────┐  │
│  │ 📄 Recent Documents │ │ ⚡ Quick Actions         │  │
│  │                     │ │                          │  │
│  │ • Documento 1.pdf   │ │ [Upload Document]        │  │
│  │ • Documento 2.docx  │ │ [Start Chat]             │  │
│  │ • Documento 3.txt   │ │                          │  │
│  │                     │ │                          │  │
│  │ [View All →]        │ │                          │  │
│  └─────────────────────┘ └──────────────────────────┘  │
│                                                         │
└─────────────────────────────────────────────────────────┘

Chat Interface

┌─────────────────────────────────────────────────────────┐
│  🧠 AgenticRAG                              [User ▼]   │
├─────────────────────────────────────────────────────────┤
│  💬 Chat 1                    ┌─────────────────────┐   │
│  💬 Chat 2                    │                     │   │
│  💬 Chat 3                    │  👤 Ciao!          │   │
│                               │                     │   │
│  [+ New Chat]                 │  🤖 Ciao! Come     │   │
│                               │     posso aiutarti? │   │
│                               │     [📄 Fonte 1]    │   │
│                               │                     │   │
│                               │  👤 Domanda...      │   │
│                               │                     │   │
│                               │  🤖 Risposta...     │   │
│                               │                     │   │
│                               │  ┌───────────────┐  │   │
│                               │  │ Scrivi un     │  │   │
│                               │  │ messaggio...  │  │   │
│                               │  └───────────────┘  │   │
│                               │           [➤]       │   │
│                               └─────────────────────┘   │
└─────────────────────────────────────────────────────────┘

---

✅ Criteri di Accettazione

• Setup progetto completato
• Tutte le pagine implementate
• Integrazione API funzionante
• Autenticazione funzionante
• Tema chiaro/scuro implementato
• Responsive design completato
• Error handling implementato
• Loading states aggiunti
• Test E2E passati
• Build di produzione funzionante

---

Stima Totale: 3-4 settimane (1 sviluppatore full-time)