bakery-admin/bakery-ia
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
0fd273cfce976bb085aa398f5563b2b1295f3501
bakery-ia/frontend/README.md

1372 lines
48 KiB
Markdown
Raw Normal View History

ADD new frontend
2025-08-28 10:41:04 +02:00
frontend/
├── public/
│ ├── icons/ # PWA icons (multiple sizes)
│ ├── manifest.json # PWA manifest
│ └── sw.js # Service worker
├── src/
│ ├── components/
│ │ ├── ui/ # Design system components
│ │ │ ├── Button/
│ │ │ │ ├── Button.tsx
│ │ │ │ ├── Button.stories.tsx
│ │ │ │ ├── Button.test.tsx
│ │ │ │ └── index.ts
│ │ │ ├── Input/
│ │ │ ├── Card/
│ │ │ ├── Modal/
│ │ │ ├── Table/
│ │ │ ├── Badge/
│ │ │ ├── Avatar/
│ │ │ ├── Tooltip/
│ │ │ ├── Select/
│ │ │ ├── DatePicker/
│ │ │ └── index.ts
│ │ ├── layout/
│ │ │ ├── AppShell/
│ │ │ ├── Header/
│ │ │ ├── Sidebar/
│ │ │ ├── Breadcrumbs/
│ │ │ ├── PageHeader/
│ │ │ └── Footer/
│ │ ├── domain/
│ │ │ ├── auth/
│ │ │ ├── dashboard/
│ │ │ ├── inventory/
│ │ │ ├── production/
│ │ │ ├── sales/
│ │ │ ├── forecasting/
│ │ │ ├── analytics/
│ │ │ └── onboarding/
│ │ └── shared/
│ │ ├── LoadingSpinner/
│ │ ├── EmptyState/
│ │ ├── ErrorBoundary/
│ │ ├── ConfirmDialog/
│ │ └── DataTable/
│ ├── pages/
│ │ ├── public/
│ │ │ ├── LandingPage/
│ │ │ ├── LoginPage/
│ │ │ └── RegisterPage/
│ │ ├── app/
│ │ │ ├── DashboardPage/
│ │ │ ├── operations/
│ │ │ │ ├── InventoryPage/
│ │ │ │ ├── ProductionPage/
│ │ │ │ ├── OrdersPage/
│ │ │ │ ├── ProcurementPage/
│ │ │ │ └── POSPage/
│ │ │ ├── analytics/
│ │ │ │ ├── ForecastingPage/
│ │ │ │ ├── SalesAnalyticsPage/
│ │ │ │ ├── PerformancePage/
│ │ │ │ └── AIInsightsPage/
│ │ │ ├── data/
│ │ │ │ ├── WeatherPage/
│ │ │ │ ├── TrafficPage/
│ │ │ │ └── EventsPage/
│ │ │ ├── communications/
│ │ │ │ ├── NotificationsPage/
│ │ │ │ ├── AlertsPage/
│ │ │ │ └── PreferencesPage/
│ │ │ ├── settings/
│ │ │ │ ├── TeamPage/
│ │ │ │ ├── BakeryConfigPage/
│ │ │ │ ├── TrainingPage/
│ │ │ │ └── SystemPage/
│ │ │ └── onboarding/
│ │ │ ├── UploadPage/
│ │ │ ├── AnalysisPage/
│ │ │ ├── ReviewPage/
│ │ │ └── SetupPage/
│ │ └── index.ts
│ ├── hooks/
│ │ ├── api/
│ │ │ ├── useAuth.ts
│ │ │ ├── useInventory.ts
│ │ │ ├── useProduction.ts
│ │ │ ├── useForecasting.ts
│ │ │ ├── useSales.ts
│ │ │ ├── useSSE.ts
│ │ │ └── useWebSocket.ts
│ │ ├── ui/
│ │ │ ├── useModal.ts
│ │ │ ├── useTheme.ts
│ │ │ ├── useToast.ts
│ │ │ └── useDebounce.ts
│ │ └── business/
│ │ ├── useBakeryWorkflow.ts
│ │ ├── useProductionSchedule.ts
│ │ └── useAlerts.ts
│ ├── stores/
│ │ ├── auth.store.ts
│ │ ├── ui.store.ts
│ │ ├── bakery.store.ts
│ │ ├── alerts.store.ts
│ │ └── index.ts
│ ├── services/
│ │ ├── api/
│ │ │ ├── client.ts
│ │ │ ├── auth.service.ts
│ │ │ ├── tenant.service.ts
│ │ │ ├── sales.service.ts
│ │ │ ├── inventory.service.ts
│ │ │ ├── forecasting.service.ts
│ │ │ ├── training.service.ts
│ │ │ ├── data.service.ts
│ │ │ ├── notification.service.ts
│ │ │ ├── orders.service.ts
│ │ │ ├── production.service.ts
│ │ │ ├── procurement.service.ts
│ │ │ └── pos.service.ts
│ │ ├── realtime/
│ │ │ ├── sse.service.ts
│ │ │ └── websocket.service.ts
│ │ └── utils/
│ │ ├── storage.service.ts
│ │ └── cache.service.ts
│ ├── router/
│ │ ├── AppRouter.tsx
│ │ ├── ProtectedRoute.tsx
│ │ ├── routes.config.ts
│ │ └── index.ts
│ ├── styles/
│ │ ├── globals.css
│ │ ├── components.css
│ │ ├── animations.css
│ │ └── themes/
│ │ ├── light.css
│ │ └── dark.css
│ ├── utils/
│ │ ├── format.ts
│ │ ├── validation.ts
│ │ ├── constants.ts
│ │ ├── date.ts
│ │ └── currency.ts
│ ├── types/
│ │ ├── auth.types.ts
│ │ ├── inventory.types.ts
│ │ ├── production.types.ts
│ │ ├── sales.types.ts
│ │ ├── forecasting.types.ts
│ │ ├── api.types.ts
│ │ └── index.ts
│ ├── locales/
│ │ ├── es/
│ │ │ ├── common.json
│ │ │ ├── auth.json
│ │ │ ├── inventory.json
│ │ │ └── errors.json
│ │ └── index.ts
│ ├── App.tsx
│ ├── main.tsx
│ └── vite-env.d.ts
├── .env.example
├── .gitignore
├── index.html
├── package.json
├── tsconfig.json
├── vite.config.ts
├── tailwind.config.js
└── README.md
# 🚀 Bakery AI Platform - Complete Frontend Rebuild from Scratch
## 📋 Project Context
You are working on **Bakery AI (PanIA)**, an intelligent platform for Madrid's bakery ecosystem that provides AI-powered demand forecasting, inventory management, and automated onboarding. The current frontend codebase has become disorganized and unmaintainable. **Your task is to build a completely new frontend from scratch** using modern best practices while preserving the existing backend API infrastructure.
## 🎯 Mission: Complete Frontend Rebuild
### Current Situation
- ❌ **Frontend architecture is a mess** - components, pages, and logic scattered without organization
- ❌ **No consistent design system** - UI components lack standardization
- ❌ **Poor code structure** - files and folders organized without logic
- ❌ **Outdated patterns** - not following modern React/TypeScript best practices
- ❌ **Poor user experience** - interface doesn't meet 2024-2025 standards
### Your Objective
✅ **Build a brand new frontend from the ground up** that is:
- Modern, maintainable, and scalable
- Following 2024-2025 UX/UI best practices
- Properly organized with clear architecture
- Type-safe and performant
- Mobile-first and accessible
## 🏗️ What to Preserve vs Rebuild
### ✅ **PRESERVE: Existing Backend Microservices Architecture**
The backend has a comprehensive microservices architecture that should be fully integrated:
```
🏗️ Backend Microservices:
├── 🔐 auth/ # Authentication & user management
├── 🏢 tenant/ # Multi-tenant organization management
├── 📊 sales/ # Sales data processing & onboarding
├── 📦 inventory/ # Product catalog & stock management
├── 📈 forecasting/ # AI demand predictions & analytics
├── 🎯 training/ # ML model training & management
├── 🌍 data/ # External data (weather, traffic)
├── 📧 notification/ # Email & WhatsApp alerts
├── 📋 orders/ # Order management & tracking
├── 🏭 production/ # Production planning & batches
├── 🛍️ procurement/ # Purchase orders & supplier management
├── 📍 pos/ # Point of sale integrations
└── 🌐 gateway/ # API gateway & routing
```
**Complete API Endpoint Mapping:**
### 🔐 Authentication Service
```
POST /api/v1/auth/register
POST /api/v1/auth/login
POST /api/v1/auth/refresh
DELETE /api/v1/auth/logout
GET /api/v1/auth/me
PUT /api/v1/auth/profile
POST /api/v1/auth/password/reset
PUT /api/v1/auth/password/change
```
### 🏢 Tenant Service
```
POST /api/v1/tenants/register
GET /api/v1/tenants/{tenant_id}
PUT /api/v1/tenants/{tenant_id}
DELETE /api/v1/tenants/{tenant_id}
GET /api/v1/tenants/{tenant_id}/members
POST /api/v1/tenants/{tenant_id}/invite
DELETE /api/v1/tenants/{tenant_id}/members/{user_id}
PATCH /api/v1/tenants/{tenant_id}/members/{user_id}
GET /api/v1/tenants/{tenant_id}/stats
GET /api/v1/tenants/user/{user_id}
```
### 📊 Sales Service (includes Onboarding & Analytics)
```
# Sales Data Management
GET /api/v1/tenants/{tenant_id}/sales
POST /api/v1/tenants/{tenant_id}/sales/upload
GET /api/v1/tenants/{tenant_id}/sales/summary
GET /api/v1/tenants/{tenant_id}/sales/trends
# AI Onboarding Automation
POST /api/v1/tenants/{tenant_id}/onboarding/analyze
POST /api/v1/tenants/{tenant_id}/onboarding/create-inventory
POST /api/v1/tenants/{tenant_id}/onboarding/import-sales
GET /api/v1/tenants/{tenant_id}/onboarding/business-model-guide
# Analytics
GET /api/v1/tenants/{tenant_id}/analytics/revenue
GET /api/v1/tenants/{tenant_id}/analytics/products
GET /api/v1/tenants/{tenant_id}/analytics/trends
GET /api/v1/tenants/{tenant_id}/analytics/reports
```
### 📦 Inventory Service (Product Catalog & Stock Management)
```
# Product Management
GET /api/v1/tenants/{tenant_id}/inventory/products
POST /api/v1/tenants/{tenant_id}/inventory/products
GET /api/v1/tenants/{tenant_id}/inventory/products/{product_id}
PUT /api/v1/tenants/{tenant_id}/inventory/products/{product_id}
DELETE /api/v1/tenants/{tenant_id}/inventory/products/{product_id}
# Stock Management
GET /api/v1/tenants/{tenant_id}/inventory/stock
POST /api/v1/tenants/{tenant_id}/inventory/stock/adjustment
GET /api/v1/tenants/{tenant_id}/inventory/stock/movements
GET /api/v1/tenants/{tenant_id}/inventory/stock/alerts
# AI Classification (300+ Bakery Products)
POST /api/v1/tenants/{tenant_id}/inventory/classify-product
POST /api/v1/tenants/{tenant_id}/inventory/classify-products-batch
# Import/Export
POST /api/v1/tenants/{tenant_id}/inventory/import
GET /api/v1/tenants/{tenant_id}/inventory/export
GET /api/v1/tenants/{tenant_id}/inventory/search
```
### 📈 Forecasting Service (AI Demand Predictions)
```
GET /api/v1/tenants/{tenant_id}/forecasts
POST /api/v1/tenants/{tenant_id}/forecasts/generate
GET /api/v1/tenants/{tenant_id}/forecasts/{forecast_id}
GET /api/v1/tenants/{tenant_id}/predictions
GET /api/v1/tenants/{tenant_id}/predictions/daily
GET /api/v1/tenants/{tenant_id}/predictions/weekly
GET /api/v1/tenants/{tenant_id}/predictions/alerts
POST /api/v1/tenants/{tenant_id}/predictions/validate
```
### 🎯 Training Service (ML Model Management)
```
POST /api/v1/tenants/{tenant_id}/training/start
GET /api/v1/tenants/{tenant_id}/training/status
GET /api/v1/tenants/{tenant_id}/training/history
POST /api/v1/tenants/{tenant_id}/training/stop
GET /api/v1/tenants/{tenant_id}/models
GET /api/v1/tenants/{tenant_id}/models/{model_id}
GET /api/v1/tenants/{tenant_id}/models/{model_id}/metrics
```
### 🌍 Data Service (External Data Integration)
```
GET /api/v1/tenants/{tenant_id}/weather
GET /api/v1/tenants/{tenant_id}/weather/forecast
GET /api/v1/tenants/{tenant_id}/traffic
GET /api/v1/tenants/{tenant_id}/traffic/patterns
GET /api/v1/tenants/{tenant_id}/holidays
GET /api/v1/tenants/{tenant_id}/events
```
### 📧 Notification Service
```
POST /api/v1/tenants/{tenant_id}/notifications/send
GET /api/v1/tenants/{tenant_id}/notifications/history
GET /api/v1/tenants/{tenant_id}/notifications/preferences
PUT /api/v1/tenants/{tenant_id}/notifications/preferences
POST /api/v1/tenants/{tenant_id}/notifications/test
```
### 📋 Orders Service
```
GET /api/v1/tenants/{tenant_id}/orders
POST /api/v1/tenants/{tenant_id}/orders
GET /api/v1/tenants/{tenant_id}/orders/{order_id}
PUT /api/v1/tenants/{tenant_id}/orders/{order_id}
DELETE /api/v1/tenants/{tenant_id}/orders/{order_id}
GET /api/v1/tenants/{tenant_id}/orders/dashboard-summary
POST /api/v1/tenants/{tenant_id}/orders/{order_id}/status
```
### 🏭 Production Service
```
GET /api/v1/tenants/{tenant_id}/production/batches
POST /api/v1/tenants/{tenant_id}/production/batches
GET /api/v1/tenants/{tenant_id}/production/batches/{batch_id}
PUT /api/v1/tenants/{tenant_id}/production/batches/{batch_id}
GET /api/v1/tenants/{tenant_id}/production/schedule
POST /api/v1/tenants/{tenant_id}/production/schedule
GET /api/v1/tenants/{tenant_id}/production/equipment
```
### 🛍️ Procurement Service
```
GET /api/v1/tenants/{tenant_id}/procurement/plans
POST /api/v1/tenants/{tenant_id}/procurement/plans/generate
GET /api/v1/tenants/{tenant_id}/procurement/plans/{plan_id}
PUT /api/v1/tenants/{tenant_id}/procurement/plans/{plan_id}/status
GET /api/v1/tenants/{tenant_id}/procurement/suppliers
GET /api/v1/tenants/{tenant_id}/procurement/requirements
```
### 📍 POS Service (Point of Sale Integration)
```
GET /api/v1/tenants/{tenant_id}/pos/configurations
POST /api/v1/tenants/{tenant_id}/pos/configurations
GET /api/v1/tenants/{tenant_id}/pos/transactions
POST /api/v1/tenants/{tenant_id}/pos/sync
GET /api/v1/tenants/{tenant_id}/pos/sync-status
```
### 📡 **Real-Time SSE Infrastructure**
The backend includes a sophisticated Server-Sent Events (SSE) system for real-time alerts and recommendations:
#### SSE Service Architecture:
```
🔄 Real-Time Stream Flow:
Alert/Recommendation Generated → Alert Processor → Redis Channel → SSE Service → Frontend Dashboard
📡 SSE Endpoints:
GET /api/v1/sse/alerts/stream/{tenant_id} # Real-time alert & recommendation stream
🚨 Alert Types & Severity Levels:
- URGENT: All channels (WhatsApp, Email, Push, Dashboard)
- HIGH: WhatsApp + Email (6AM-10PM), Email only (night)
- MEDIUM: Email (business hours 7AM-8PM), Dashboard always
- LOW: Dashboard only
💡 Recommendation Types:
- Production optimization suggestions
- Inventory reorder recommendations
- Demand forecast insights
- Cost optimization tips
- Equipment maintenance alerts
```
#### Channel Routing Logic:
```typescript
// Backend determines channels by severity & time:
const channels = {
urgent: ['whatsapp', 'email', 'push', 'dashboard'], // Immediate
high: ['whatsapp', 'email', 'dashboard'], // Extended hours
medium: ['email', 'dashboard'], // Business hours
low: ['dashboard'] // Always visible
};
// Frontend receives via SSE:
eventSource.addEventListener('alert', (event) => {
const alert = JSON.parse(event.data);
// Auto-display urgent/high alerts
// Browser notifications for urgent alerts
// Sound alerts for critical items
});
eventSource.addEventListener('recommendation', (event) => {
const recommendation = JSON.parse(event.data);
// Display in recommendations panel
// Non-intrusive UI integration
});
```
#### SSE Message Format:
```typescript
interface SSEMessage {
id: string;
item_type: 'alert' | 'recommendation';
type: string; // Specific alert type
severity: 'urgent' | 'high' | 'medium' | 'low';
title: string;
message: string;
actions: string[]; // Suggested actions
metadata: Record<string, any>; // Context data
timestamp: string;
status: 'active' | 'acknowledged' | 'resolved';
}
```
### 🔄 **Real-Time WebSocket Training Monitoring**
In addition to SSE alerts, the system includes dedicated WebSocket connections for ML model training progress:
#### WebSocket Training Architecture:
```
🎯 Training WebSocket Flow:
Training Job Started → WebSocket Connection → Real-time Progress → Completion Status
📡 WebSocket Endpoints:
WS /api/v1/ws/tenants/{tenant_id}/training/jobs/{job_id}/live # Real-time training progress
🤖 ML Training Process Types:
- Data validation and preprocessing
- Prophet model training (demand forecasting)
- Model performance evaluation (MAPE, MAE, RMSE, R2 score)
- Model storage and versioning
- Training completion with metrics
```
#### WebSocket Message Types:
```typescript
interface TrainingWebSocketMessage {
// Progress Updates
type: 'training_progress';
job_id: string;
progress: {
percentage: number; // 0-100
current_step: string; // "Data validation", "Model training", etc.
products_completed: number; // Products processed so far
products_total: number; // Total products to process
estimated_time_remaining: number; // Seconds
started_at: string;
};
// Completion Events
type: 'training_completed';
job_id: string;
results: {
successful_trainings: number;
failed_trainings: number;
models_created: string[];
performance_metrics: {
accuracy: number; // R2 score
mape: number; // Mean Absolute Percentage Error
mae: number; // Mean Absolute Error
rmse: number; // Root Mean Square Error
};
training_duration: number; // Total training time in seconds
};
// Error Events
type: 'training_error';
job_id: string;
error: string;
timestamp: string;
}
```
#### Training Configuration:
```typescript
// Backend training settings optimized for bakery data:
const trainingConfig = {
maxTrainingTimeMinutes: 30, // 30 minute timeout
maxConcurrentJobs: 3, // Max 3 parallel training jobs
minTrainingDataDays: 30, // Require 30+ days of sales data
// Prophet algorithm parameters for bakery forecasting:
seasonalityMode: 'additive', // Better for bakery patterns
changePointPriorScale: 0.05, // Sensitivity to trend changes
seasonalityPriorScale: 10.0, // Strength of seasonal patterns
holidaysPriorScale: 10.0, // Spanish/Madrid holiday impact
// Spanish context:
enableSpanishHolidays: true, // National holidays
enableMadridHolidays: true, // Local Madrid holidays
enableCustomHolidays: true // Bakery-specific holidays
};
```
#### WebSocket Integration Features:
- ✅ **Real-Time Progress**: Live percentage updates during training
- ✅ **Step-by-Step Monitoring**: Current training phase visibility
- ✅ **Performance Metrics**: Live model accuracy metrics (MAPE, MAE, RMSE)
- ✅ **Connection Management**: Auto-reconnection with JWT authentication
- ✅ **Tenant Isolation**: Secure per-tenant training job monitoring
- ✅ **Completion Detection**: Automatic WebSocket closure on job completion
- ✅ **Error Handling**: Comprehensive error reporting and recovery
### ❌ **REBUILD COMPLETELY: Frontend**
Replace the entire frontend directory structure and codebase:
```bash
# Remove the old frontend completely:
rm -rf frontend/src/components/
rm -rf frontend/src/pages/
rm -rf frontend/src/hooks/
rm -rf frontend/src/styles/
rm -rf frontend/src/router/
# Keep only: package.json, vite.config.ts, index.html
```
## 📱 New Frontend Requirements
### Target Users & Use Cases
1. **Small Bakery Owners (Madrid)**: Mobile-first, simple workflows, 4AM production schedules
2. **Operations Managers**: Desktop analytics, detailed reports, multi-location oversight
3. **Production Staff**: Tablet-friendly, quick actions, hands-free when possible
### Core User Workflows to Support
```
1. Morning Production Planning (4:00 AM):
Login → Check Forecasts → Plan Production → Update Inventory
2. Daily Operations Management:
Monitor Sales → Adjust Production → Track Inventory → Handle Alerts
3. Weekly Business Analysis:
Review Performance → Analyze Trends → Plan Improvements → Generate Reports
4. New User Onboarding:
Register → Upload Sales Data → AI Setup → Start Forecasting (5-10 minutes)
```
## 🎨 Modern Frontend Architecture to Build
### Tech Stack (Keep Existing Dependencies)
```json
{
"react": "^18.2.0",
"typescript": "^5.0.2",
"vite": "^4.4.5",
"react-router-dom": "^6.15.0",
"@reduxjs/toolkit": "^1.9.5",
"tailwindcss": "^3.3.0",
"react-hook-form": "^7.45.4",
"lucide-react": "^0.263.1",
"recharts": "^2.8.0",
"zod": "^3.22.2"
}
```
### 🏗️ New Architecture Pattern: Service-Aligned Hub-and-Spoke
Based on the comprehensive backend microservices, organize the frontend around service domains:
```
🏠 Central Dashboard
├── 🔐 Authentication Hub
│ ├── Login/Register
│ ├── Profile Management
│ └── Password Reset
├── 🥖 Operations Hub
│ ├── 📦 Inventory (Products, Stock, Alerts)
│ ├── 🏭 Production (Batches, Schedule, Equipment)
│ ├── 📋 Orders (Management, Status, Tracking)
│ ├── 🛍️ Procurement (Plans, Suppliers, Requirements)
│ └── 📍 POS (Integration, Sync, Transactions)
├── 📊 Analytics Hub
│ ├── 🔮 Forecasting (Predictions, Models, Validation)
│ ├── 📈 Sales Analytics (Trends, Reports, Revenue)
│ ├── 📉 Performance KPIs (Metrics, Dashboards)
│ └── 🤖 AI Insights (Classifications, Recommendations)
├── 🌍 Data Hub
│ ├── Weather Integration (AEMET API)
│ ├── Traffic Patterns
│ ├── External Events
│ └── Market Data
├── 📧 Communications Hub
│ ├── Notifications (Email, WhatsApp)
│ ├── Alert Management
│ └── Preference Settings
└── ⚙️ Settings Hub
├── 👥 Team Management (Members, Roles, Invites)
├── 🏢 Bakery Configuration (Business Model, Settings)
├── 🎯 Training (ML Models, Status, History)
└── 🔧 System Settings (API Keys, Integrations)
```
### 🧱 Component Architecture to Build
```typescript
// Design System Foundation
components/ui/
├── Button/ # Primary, secondary, ghost variants
├── Input/ # Text, email, number with validation
├── Card/ # Elevation levels, padding variants
├── Modal/ # Sizes, overlay, animations
├── Table/ # Sorting, filtering, pagination
├── Form/ # React Hook Form + Zod integration
├── Badge/ # Status indicators, color variants
├── Avatar/ # User profile images, initials
└── index.ts # Export all UI components
// Layout Components
components/layout/
├── AppShell/ # Main application container
├── Header/ # Top navigation, user menu
├── Sidebar/ # Main navigation, collapsible
├── Breadcrumbs/ # Navigation trail
├── PageHeader/ # Page title, actions
└── Footer/ # Copyright, links
// Business Components
components/domain/
├── auth/ # Login, register, password reset
├── dashboard/ # KPI cards, charts, activity feed
├── inventory/ # Product cards, stock alerts
├── production/ # Batch cards, equipment status
├── sales/ # Transaction lists, POS integration
├── forecasting/ # Prediction charts, confidence indicators
└── onboarding/ # Step-by-step setup wizard
// Shared Components
components/shared/
├── LoadingSpinner/ # Various loading states
├── EmptyState/ # No data illustrations
├── ErrorBoundary/ # Error handling with retry
├── ConfirmDialog/ # Confirmation modals
└── DataTable/ # Reusable table with features
```
## 🎨 2024-2025 Design System to Implement
### Visual Identity (Bakery Theme)
```css
/* Color Palette */
:root {
/* Primary: Warm Orange (artisan bread) */
--orange-50: #fff7ed;
--orange-500: #f97316;
--orange-900: #9a3412;
/* Secondary: Golden Wheat */
--amber-50: #fffbeb;
--amber-500: #f59e0b;
--amber-900: #92400e;
/* Success: Fresh Green */
--green-500: #22c55e;
/* Warning: Alert Orange */
--red-500: #ef4444;
/* Neutral: Modern Grays */
--slate-50: #f8fafc;
--slate-500: #64748b;
--slate-900: #0f172a;
}
/* Typography System */
.text-display { font-size: 2.25rem; font-weight: 700; } /* Page headlines */
.text-heading { font-size: 1.875rem; font-weight: 600; } /* Section titles */
.text-title { font-size: 1.5rem; font-weight: 600; } /* Card titles */
.text-body { font-size: 1rem; font-weight: 400; } /* Body text */
.text-caption { font-size: 0.875rem; font-weight: 400; } /* Captions */
/* Spacing System (8px grid) */
.space-xs { margin: 0.5rem; } /* 8px */
.space-sm { margin: 1rem; } /* 16px */
.space-md { margin: 1.5rem; } /* 24px */
.space-lg { margin: 2rem; } /* 32px */
.space-xl { margin: 3rem; } /* 48px */
```
### Modern UI Patterns to Implement
1. **Glassmorphism Cards**:
```css
.glass-card {
background: rgba(255, 255, 255, 0.25);
backdrop-filter: blur(10px);
border: 1px solid rgba(255, 255, 255, 0.18);
border-radius: 12px;
}
```
2. **Neumorphism Buttons**:
```css
.neu-button {
background: linear-gradient(145deg, #f0f0f0, #cacaca);
box-shadow: 20px 20px 60px #bebebe, -20px -20px 60px #ffffff;
}
```
3. **Micro-Interactions**:
- Hover state transitions (200ms ease)
- Loading button animations
- Form field focus effects
- Success/error state changes
## 📱 Mobile-First Design Requirements
### Responsive Breakpoints
```css
/* Mobile First Approach */
.container {
padding: 1rem; /* Mobile: 16px */
}
@media (min-width: 640px) { /* Tablet */
.container { padding: 1.5rem; }
}
@media (min-width: 1024px) { /* Desktop */
.container { padding: 2rem; }
}
@media (min-width: 1280px) { /* Large Desktop */
.container { max-width: 1200px; margin: 0 auto; }
}
```
### Touch-Optimized Interactions
- **44px minimum touch targets** for all buttons/links
- **Swipe gestures** for mobile navigation
- **Pull-to-refresh** on data lists
- **Long press** for context menus
- **Double-tap** for quick actions
### Progressive Web App Features
```typescript
// Implement PWA capabilities:
- Service Worker for offline functionality
- Web App Manifest for home screen install
- Push notifications for alerts
- Background sync for data updates
- Cache strategies for fast loading
```
## 🤖 AI-Enhanced UX Features
### Intelligent Interface Elements
1. **Smart Search**: Predictive suggestions based on context
2. **AI Recommendations**: Contextual tips and insights
3. **Auto-Complete**: Forms pre-filled with AI predictions
4. **Anomaly Highlights**: Visual indicators for unusual data
5. **Voice Commands**: "Show today's production plan"
### Conversational Interface Components
```typescript
// AI Assistant Components to Build:
<AIAssistant /> // Floating chat widget
<SmartSearch /> // Predictive search bar
<ContextualHelp /> // Smart help tooltips
<VoiceInput /> // Speech-to-text input
<AIInsightCard /> // AI-generated insights
```
## 🔄 State Management Architecture
### Modern State Pattern with Zustand
```typescript
// Replace Redux with focused Zustand stores:
// Authentication State
interface AuthState {
user: User | null;
isAuthenticated: boolean;
login: (credentials: LoginRequest) => Promise<void>;
logout: () => void;
}
// UI State
interface UIState {
sidebarOpen: boolean;
theme: 'light' | 'dark';
currentModal: string | null;
toggleSidebar: () => void;
setTheme: (theme: 'light' | 'dark') => void;
}
// Business State
interface BakeryState {
currentTenant: Tenant | null;
businessModel: 'individual' | 'central';
notifications: Notification[];
setTenant: (tenant: Tenant) => void;
}
```
### API Integration with React Query
```typescript
// Replace custom hooks with React Query:
import { useQuery, useMutation } from '@tanstack/react-query';
export const useInventory = (tenantId: string) => {
return useQuery({
queryKey: ['inventory', tenantId],
queryFn: () => apiClient.get(`/tenants/${tenantId}/inventory/products`),
staleTime: 5 * 60 * 1000, // 5 minutes
cacheTime: 10 * 60 * 1000, // 10 minutes
});
};
export const useCreateProduct = () => {
return useMutation({
mutationFn: (product: CreateProductRequest) =>
apiClient.post('/inventory/products', product),
onSuccess: () => {
queryClient.invalidateQueries(['inventory']);
},
});
};
```
## 🛣️ Routing & Navigation Architecture
### URL-Based Navigation with Service-Aligned Structure
```typescript
// Clean, RESTful URL structure aligned with backend services:
const routes = [
// Public Routes
'/', # Landing page
'/auth/login', # Authentication
'/auth/register',
// Protected Application Routes
'/app', # Redirect to dashboard
'/app/dashboard', # Cross-service dashboard
// Operations Hub (aligned with backend services)
'/app/operations', # Operations hub overview
'/app/operations/inventory', # Inventory service frontend
'/app/operations/inventory/products', # Product catalog
'/app/operations/inventory/stock', # Stock management
'/app/operations/inventory/alerts', # Low stock alerts
'/app/operations/production', # Production service frontend
'/app/operations/production/batches', # Production batches
'/app/operations/production/schedule', # Production scheduling
'/app/operations/orders', # Orders service frontend
'/app/operations/orders/management', # Order management
'/app/operations/orders/tracking', # Order status tracking
'/app/operations/procurement', # Procurement service frontend
'/app/operations/procurement/plans', # Procurement planning
'/app/operations/procurement/suppliers', # Supplier management
'/app/operations/pos', # POS service frontend
'/app/operations/pos/integration', # POS configuration
'/app/operations/pos/transactions', # Transaction sync
// Analytics Hub (forecasting + sales analytics)
'/app/analytics', # Analytics hub overview
'/app/analytics/forecasting', # Forecasting service frontend
'/app/analytics/forecasting/predictions', # AI demand predictions
'/app/analytics/forecasting/models', # ML model management
'/app/analytics/sales', # Sales analytics
'/app/analytics/sales/trends', # Sales trend analysis
'/app/analytics/sales/reports', # Sales reporting
'/app/analytics/performance', # Performance KPIs
// Data Hub (external data integration)
'/app/data', # Data hub overview
'/app/data/weather', # Weather integration (AEMET)
'/app/data/traffic', # Traffic patterns
'/app/data/events', # External events
// Communications Hub
'/app/communications', # Communications overview
'/app/communications/notifications', # Notification management
'/app/communications/alerts', # Alert configuration
'/app/communications/preferences', # Communication preferences
// Settings Hub
'/app/settings', # Settings hub overview
'/app/settings/team', # Tenant service frontend
'/app/settings/team/members', # Team member management
'/app/settings/team/roles', # Role management
'/app/settings/bakery', # Bakery configuration
'/app/settings/training', # Training service frontend
'/app/settings/training/models', # ML model settings
'/app/settings/training/history', # Training history
'/app/settings/system', # System configuration
// Onboarding (special workflow)
'/app/onboarding', # AI-powered onboarding
'/app/onboarding/upload', # Sales data upload
'/app/onboarding/analysis', # AI analysis phase
'/app/onboarding/review', # Review AI suggestions
'/app/onboarding/setup', # Complete setup
];
// Context-aware navigation based on backend service responses
<Route path="/app/operations/inventory/products/:productId" />
<Route path="/app/operations/production/batches/:batchId" />
<Route path="/app/analytics/forecasting/models/:modelId" />
```
### Context-Aware Navigation
```typescript
// Smart navigation based on user context:
- Bakery type (individual vs central) determines available features
- User role (owner, manager, staff) controls access levels
- Business model affects workflow organization
- Mobile vs desktop changes navigation patterns
```
## 📊 Data Visualization & Analytics
### Chart Components with Recharts
```typescript
// Standardized chart components:
<ForecastChart
data={forecastData}
confidence={confidenceInterval}
period="week"
interactive={true}
/>
<SalesChart
data={salesData}
comparison="previous_period"
breakdown="product_category"
/>
<InventoryChart
data={inventoryLevels}
alerts={lowStockAlerts}
predictions={restockPredictions}
/>
```
### Dashboard Widget System
```typescript
// Modular dashboard widgets:
<DashboardGrid>
<Widget title="Today's Sales" size="md">
<SalesKPICard />
</Widget>
<Widget title="Production Status" size="lg">
<ProductionStatusTable />
</Widget>
<Widget title="AI Insights" size="sm">
<AIInsightsList />
</Widget>
</DashboardGrid>
```
## 🔐 Authentication & Authorization
### Modern Auth Flow
```typescript
// JWT-based authentication with refresh tokens:
interface AuthContext {
user: User | null;
isLoading: boolean;
login: (email: string, password: string) => Promise<void>;
register: (data: RegisterRequest) => Promise<void>;
logout: () => void;
refreshToken: () => Promise<void>;
}
// Route protection:
<ProtectedRoute requiredRoles={['admin', 'manager']}>
<AdvancedAnalytics />
</ProtectedRoute>
```
### Permission-Based UI
```typescript
// Components adapt based on user permissions:
<ActionButton
visible={hasPermission('inventory:create')}
onClick={handleCreateProduct}
>
Add Product
</ActionButton>
```
## 🧪 Form Management & Validation
### React Hook Form + Zod Integration
```typescript
// Type-safe forms with validation:
const productSchema = z.object({
name: z.string().min(1, 'Product name required'),
category: z.enum(['bread', 'pastry', 'ingredient']),
price: z.number().positive('Price must be positive'),
});
const CreateProductForm = () => {
const form = useForm({
resolver: zodResolver(productSchema),
defaultValues: { name: '', category: 'bread', price: 0 }
});
return (
<Form onSubmit={form.handleSubmit(onSubmit)}>
<FormField name="name" label="Product Name" />
<FormField name="category" label="Category" type="select" />
<FormField name="price" label="Price" type="number" />
</Form>
);
};
```
## 📁 New Project Structure to Build
```
frontend/
├── public/
│ ├── icons/ # PWA icons
│ ├── manifest.json # PWA manifest
│ └── sw.js # Service worker
├── src/
│ ├── components/ # Component library
│ │ ├── ui/ # Design system components
│ │ │ ├── Button/
│ │ │ │ ├── Button.tsx
│ │ │ │ ├── Button.stories.tsx
│ │ │ │ ├── Button.test.tsx
│ │ │ │ └── index.ts
│ │ │ ├── Input/
│ │ │ ├── Card/
│ │ │ └── index.ts # Export all UI components
│ │ ├── layout/ # Layout components
│ │ │ ├── AppShell/
│ │ │ ├── Header/
│ │ │ ├── Sidebar/
│ │ │ └── index.ts
│ │ ├── domain/ # Business components
│ │ │ ├── auth/
│ │ │ ├── dashboard/
│ │ │ ├── inventory/
│ │ │ ├── production/
│ │ │ └── index.ts
│ │ └── shared/ # Shared utilities
│ │ ├── LoadingSpinner/
│ │ ├── ErrorBoundary/
│ │ └── index.ts
│ ├── pages/ # Page components
│ │ ├── LandingPage/
│ │ ├── LoginPage/
│ │ ├── DashboardPage/
│ │ ├── InventoryPage/
│ │ └── index.ts
│ ├── hooks/ # Custom hooks
│ │ ├── api/ # API hooks (React Query)
│ │ │ ├── useAuth.ts
│ │ │ ├── useInventory.ts
│ │ │ └── index.ts
│ │ ├── ui/ # UI state hooks
│ │ │ ├── useModal.ts
│ │ │ ├── useTheme.ts
│ │ │ └── index.ts
│ │ └── business/ # Business logic hooks
│ │ ├── useBakeryWorkflow.ts
│ │ └── index.ts
│ ├── stores/ # State management
│ │ ├── auth.store.ts # Zustand stores
│ │ ├── ui.store.ts
│ │ ├── bakery.store.ts
│ │ └── index.ts
│ ├── services/ # API services
│ │ ├── api.client.ts # HTTP client setup
│ │ ├── auth.service.ts # Authentication API
│ │ ├── inventory.service.ts # Inventory API
│ │ └── index.ts
│ ├── router/ # Routing configuration
│ │ ├── AppRouter.tsx # Main router setup
│ │ ├── ProtectedRoute.tsx # Route guards
│ │ └── index.ts
│ ├── styles/ # Global styles
│ │ ├── globals.css # Global CSS
│ │ ├── components.css # Component styles
│ │ └── animations.css # Animation utilities
│ ├── utils/ # Helper functions
│ │ ├── format.ts # Data formatting
│ │ ├── validation.ts # Validation helpers
│ │ ├── constants.ts # App constants
│ │ └── index.ts
│ ├── types/ # TypeScript definitions
│ │ ├── auth.types.ts
│ │ ├── inventory.types.ts
│ │ ├── api.types.ts
│ │ └── index.ts
│ ├── App.tsx # Root component
│ ├── main.tsx # Application entry
│ └── vite-env.d.ts # Vite types
├── package.json
├── vite.config.ts
├── tailwind.config.js
├── tsconfig.json
└── README.md
```
## 🎯 Implementation Phases
### Phase 1: Foundation (Week 1-2)
1. **Setup new project structure** with proper folder organization
2. **Build design system** - UI components with Storybook
3. **Implement authentication flow** - login, register, JWT handling
4. **Create routing structure** - React Router with protected routes
5. **Setup state management** - Zustand stores for auth, UI, business logic
### Phase 2: Core Features (Week 3-4)
1. **Dashboard implementation** - KPI cards, charts, activity feed
2. **Inventory management** - product lists, stock levels, alerts
3. **Production planning** - batch scheduling, recipe management
4. **Sales tracking** - transaction history, POS integration
5. **Mobile optimization** - responsive design, touch interactions
### Phase 3: Advanced Features (Week 5-6)
1. **Analytics hub** - forecasting charts, trend analysis, reports
2. **AI integration** - smart suggestions, predictive features
3. **PWA capabilities** - offline mode, push notifications
4. **Performance optimization** - lazy loading, caching strategies
5. **Accessibility audit** - WCAG 2.2 compliance, keyboard navigation
### Phase 4: Polish & Launch (Week 7-8)
1. **UI/UX refinement** - micro-interactions, animations
2. **Testing implementation** - unit tests, integration tests
3. **Documentation** - component docs, user guides
4. **Performance monitoring** - analytics, error tracking
5. **Production deployment** - CI/CD pipeline, monitoring
## 🔧 Development Guidelines
### Code Quality Standards
```typescript
// TypeScript strict mode with no 'any'
interface StrictTyping {
user: User; // ✅ Proper typing
data: unknown; // ✅ Use unknown for uncertain types
error: ApiError; // ✅ Define error types
// avoid: data: any; // ❌ Never use 'any'
}
// Component composition patterns:
const ProductCard = ({ product, onEdit, onDelete }: ProductCardProps) => {
return (
<Card>
<CardHeader>
<CardTitle>{product.name}</CardTitle>
</CardHeader>
<CardContent>
<ProductDetails product={product} />
</CardContent>
<CardFooter>
<Button onClick={onEdit}>Edit</Button>
<Button variant="destructive" onClick={onDelete}>Delete</Button>
</CardFooter>
</Card>
);
};
```
### Performance Best Practices
```typescript
// Lazy loading for code splitting:
const AnalyticsPage = lazy(() => import('./pages/AnalyticsPage'));
// Memoization for expensive calculations:
const expensiveCalculation = useMemo(() => {
return processLargeDataset(data);
}, [data]);
// Debounced search:
const debouncedSearch = useDebounce(searchTerm, 300);
```
### Accessibility Requirements
```typescript
// WCAG 2.2 AA compliance:
<Button
aria-label="Add new product to inventory"
tabIndex={0}
onKeyDown={handleKeyDown}
>
<PlusIcon aria-hidden="true" />
Add Product
</Button>
// Focus management:
const DialogComponent = () => {
const focusRef = useRef<HTMLButtonElement>(null);
useEffect(() => {
focusRef.current?.focus();
}, []);
return (
<Dialog>
<Button ref={focusRef}>Close</Button>
</Dialog>
);
};
```
## 📋 Specific Business Requirements
### Bakery-Specific Features
1. **Dual Business Model Support**:
- Individual bakeries: On-site production, direct sales
- Central production: Mass production, multi-outlet distribution
2. **Production Scheduling**:
- Early morning workflows (4:00-6:00 AM)
- Recipe scaling and ingredient calculations
- Equipment scheduling and capacity planning
3. **Inventory Management**:
- Ingredient tracking with expiration dates
- Finished product inventory with shelf-life
- Automated reorder points and supplier integration
4. **AI-Powered Forecasting**:
- Weather impact on demand (rainy days = less foot traffic)
- Seasonal patterns (holidays, local events)
- Product-specific demand predictions
### Madrid Market Context
- **Language**: Spanish UI with proper localization
- **Currency**: Euro (€) formatting throughout
- **Business Hours**: Early morning operations (4AM start)
- **Mobile Usage**: 60%+ of interactions on mobile devices
- **Internet**: Sometimes unreliable, need offline capabilities
## 🚀 Success Metrics & Goals
### Performance Targets
- **Page Load Time**: < 2 seconds on 3G connections
- **Bundle Size**: < 500KB initial bundle (gzipped)
- **Lighthouse Score**: 90+ for Performance, Accessibility, Best Practices
- **Mobile Score**: 95+ for mobile usability
### User Experience Goals
- **Onboarding Time**: 5-10 minutes (down from 2-3 hours)
- **Task Completion**: 90%+ success rate for core workflows
- **User Satisfaction**: NPS score > 8.5
- **Mobile Adoption**: 60%+ of daily active users on mobile
### Business Impact
- **User Retention**: 80%+ monthly active users
- **Feature Adoption**: 90%+ using core features within 30 days
- **Support Tickets**: 50% reduction in UI/UX related issues
- **Conversion Rate**: 85%+ trial-to-paid conversion
## 🎨 Design Inspiration & Research
### Modern SaaS Platforms to Study
1. **Linear** - Clean design, excellent navigation, keyboard shortcuts
2. **Notion** - Flexible layouts, contextual menus, progressive disclosure
3. **Figma** - Collaborative features, real-time updates, intuitive interactions
4. **Stripe Dashboard** - Data visualization, clear hierarchy, mobile-first
5. **Vercel** - Performance focus, minimalist design, status indicators
### AI-Enhanced Interfaces
1. **Claude.ai** - Conversational interface, contextual help, smart suggestions
2. **Cursor** - Predictive features, auto-completion, AI assistance
3. **GitHub Copilot** - Code suggestions, contextual recommendations
4. **Replit** - Real-time collaboration, AI-powered development environment
### Mobile-First Enterprise Apps
1. **Slack Mobile** - Touch-optimized, gesture navigation, offline support
2. **Asana Mobile** - Task management, quick actions, responsive design
3. **Trello Mobile** - Card-based interface, drag-and-drop interactions
## 🔍 Research Requirements
Before starting implementation, research:
### Latest Design Trends (2024-2025)
- **Micro-interactions**: Subtle animations that provide feedback
- **Glassmorphism**: Translucent elements with backdrop blur
- **Neumorphism**: Soft, inset shadow effects for buttons/cards
- **Dark Mode**: System-preference aware theming
- **Accessibility First**: WCAG 2.2 compliance from the start
### AI-UX Patterns
- **Predictive Interface**: UI that anticipates user needs
- **Contextual Help**: Smart assistance based on current task
- **Progressive Enhancement**: AI features that enhance without blocking
- **Explainable AI**: Transparent AI decision-making
### Performance Optimization
- **Core Web Vitals**: LCP, FID, CLS optimization
- **Progressive Loading**: Critical path prioritization
- **Edge Computing**: CDN optimization for global performance
- **Bundle Analysis**: Tree-shaking and code-splitting strategies
## ⚡ Quick Start Checklist
### ✅ Week 1: Foundation
- [ ] Create new project structure with proper organization
- [ ] Setup Tailwind CSS with custom design system
- [ ] Implement authentication flow (login/register/logout)
- [ ] Create basic layout components (Header, Sidebar, AppShell)
- [ ] Setup React Router with protected routes
### ✅ Week 2: Core Components
- [ ] Build complete UI component library with Storybook
- [ ] Implement Zustand stores for state management
- [ ] Create API service layer with React Query
- [ ] Build dashboard with KPI cards and charts
- [ ] Add mobile-responsive navigation
### ✅ Week 3: Business Features
- [ ] Inventory management (products, stock levels, alerts)
- [ ] Production planning (batches, recipes, scheduling)
- [ ] Sales tracking (transactions, POS integration)
- [ ] Forecasting (charts, predictions, confidence intervals)
- [ ] Basic analytics and reporting
### ✅ Week 4: UX Enhancement
- [ ] AI-powered features (smart search, recommendations)
- [ ] Progressive Web App (offline, notifications, install)
- [ ] Accessibility audit and improvements (WCAG 2.2 AA)
- [ ] Performance optimization (lazy loading, caching)
- [ ] Cross-device testing and optimization
## 🎯 Final Outcome
Transform the Bakery AI Platform into:
✅ **Modern, Professional Interface** - Following 2024-2025 design standards with glassmorphism, micro-interactions, and AI-enhanced UX
✅ **Clean, Maintainable Codebase** - TypeScript-first, component-driven architecture with clear separation of concerns
✅ **Mobile-First Experience** - Touch-optimized, responsive design with PWA capabilities and offline functionality
✅ **AI-Enhanced Workflows** - Predictive features, smart suggestions, and contextual help that guide users intelligently
✅ **High-Performance Application** - Fast loading, efficient rendering, and optimized for Madrid bakery operations
✅ **Accessible Platform** - WCAG 2.2 AA compliant with support for all users and assistive technologies
Remember: You're building for Madrid bakery owners who start work at 4:00 AM and need reliable, fast, intuitive tools to manage their businesses profitably. Every design and technical decision should prioritize their real operational needs over technical elegance.
Reference in New Issue Copy Permalink