# 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
```css
/* 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

```typescript
// 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
```typescript
// 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

```bash
# 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)