From 2566f712a25b4d249da24007750e9c89d5a93d3c Mon Sep 17 00:00:00 2001
From: Luca Sacchi Ricciardi <luca@lucasacchi.net>
Date: Mon, 6 Apr 2026 11:29:38 +0200
Subject: [PATCH] docs: add comprehensive frontend development plan
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

## 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
---
 frontend-plan.md | 386 +++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 386 insertions(+)
 create mode 100644 frontend-plan.md

diff --git a/frontend-plan.md b/frontend-plan.md
new file mode 100644
index 0000000..76e33d4
--- /dev/null
+++ b/frontend-plan.md
@@ -0,0 +1,386 @@
+# 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)