2566f712a2
## Added
- frontend-plan.md: Complete React/Vite frontend development plan
## Contents
- Project architecture and folder structure
- Tech stack (React 18, Vite, TypeScript, Tailwind, shadcn/ui)
- Design system with colors and components
- Page-by-page feature specifications
- API integration details
- 8-phase implementation roadmap (3-4 weeks)
- UI mockups for Dashboard and Chat
- Acceptance criteria
🎨 Ready for frontend development
387 lines
13 KiB
Markdown
387 lines
13 KiB
Markdown
# 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)
|