lucasacchi/documente
0
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

docs: add comprehensive frontend development plan

Browse Source 
## 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
This commit is contained in:
Luca Sacchi Ricciardi
2026-04-06 11:29:38 +02:00
parent 437a484b1c
commit 2566f712a2
1 changed files with 386 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

386
frontend-plan.md Normal file
View File

@@ -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)