# Veliu Bag - Agent Instructions

## Project Overview

Veliu Bag is an Italian luxury fashion resale platform operating a two-sided marketplace.
The platform connects **sellers** (individuals with pre-loved luxury items) with **buyers**
(certified dealers and individual buyers) through an AI-powered valuation and authentication system.

**Mission**: Make luxury resale safe, fast, and transparent for Italian consumers.

**Primary Language**: Italian (IT) | **Currency**: EUR

## What This Platform Does

### Core Value Proposition

1. **Instant AI Valuation**: Sellers upload photos and receive market-based price estimates in seconds
2. **Certified Buyer Network**: Vetted buyers compete to offer the best prices
3. **Expert Authentication**: Every item is verified by professionals before transaction completion
4. **Secure Payments**: Stripe-powered escrow system protects both parties
5. **Hassle-free Logistics**: Prepaid shipping labels with tracking and insurance

### Key Differentiators

- AI-powered image recognition for product identification
- Real-time market price analysis
- Professional authentication service
- Mobile app (iOS/Android via Capacitor)
- PWA support for offline browsing

## Platform Architecture

### Frontend

- **Framework**: React 18.3 with TypeScript
- **Build Tool**: Vite 5.4 with SWC
- **Styling**: Tailwind CSS 3.4 + shadcn/ui components
- **State Management**: TanStack React Query + Context API
- **Routing**: React Router v6
- **Forms**: React Hook Form + Zod validation
- **Mobile**: Capacitor 7.4 (iOS/Android apps)

### Key Directories

```
src/
├── pages/           # Route-level pages (React Router)
├── components/      # Reusable React components
│   ├── ui/          # shadcn/ui base components
│   ├── orders/      # Order management components
│   └── buy-product/ # Buyer-specific components
├── hooks/           # Custom React hooks
├── utils/           # Utility functions
├── integrations/    # External service integrations
└── types/           # TypeScript definitions
```

### User Flows

#### Sell Flow (Vendita)

```
Homepage → Search (Text/Image/Voice) → AI Analysis →
Valuation Display → Accept Offer → Login/Auth →
Address + IBAN → Terms → Order Created →
Shipping Label → Track Order → Authentication → Payout
```

#### Buy Flow (Acquisto)

```
Buy Search → Filter/ Browse → Product Detail →
Add to Cart → Checkout (Stripe) →
Order Confirmation → Authentication → Shipping → Delivery
```

## Development Environment

### Prerequisites

- Node.js >= 18
- npm or yarn

### Commands

```bash
# Install dependencies
npm install

# Start development server (http://localhost:8080)
npm run dev

# Build for production
npm run build

# Preview production build
npm run preview

# Run linter
npm run lint
```

### Build Output

- Production build: `dist/`
- Static assets served from `public/`

## Key Features & Components

### Search & Discovery

- **AISearchBar**: AI-powered search with autocomplete
- **ImageSearch**: Upload photo to find similar items
- **CatalogSearch**: Browse by category, brand, price, condition
- **MarketInsights**: Price trends and market data visualization

### Product Valuation

- **ProductValuation**: Multi-step valuation flow
  - Condition assessment (New, Like New, Good, Fair)
  - Photo upload and analysis
  - Market price comparison
  - Instant offer generation

### Order Management

- **Orders**: Order list with status tracking
- **OrderDetail**: Full order timeline and actions
- **ShippingLabel**: Generate and print prepaid labels
- **AuthenticationStatus**: Track expert verification progress

### Payment & Finance

- **Stripe Integration**: Secure checkout and payouts
- **IBAN Management**: Bank account for seller payouts
- **Balance**: Transaction history and earnings
- **Invoices**: Automated invoice generation

### User Account

- **Profile**: Personal info, preferences, settings
- **AddressManagement**: Shipping addresses
- **Notifications**: Marketing and transaction alerts
- **Favorites**: Saved items and collections

## Authentication

### Auth Methods

- Phone OTP (primary)
- Email/password
- Social login (Google, Apple)

### Protected Routes

- `/bag-page` - Requires authentication
- `/orders` - Requires authentication
- `/profile` - Requires authentication
- `/portal*` - Admin only (separate auth)

### Session Management

- JWT tokens via Supabase Auth
- Automatic token refresh
- Session persistence with secure storage

## API Integration

### Backend Services

- **Supabase**: Database, auth, real-time subscriptions
- **Stripe**: Payments, Connect for marketplace
- **Google Maps**: Address autocomplete and geocoding
- **PostHog**: Product analytics
- **Sentry**: Error tracking
- **GTM**: Marketing tags and conversion tracking

### External APIs

- Image CDN: Vestiaire Collective, Vinted, Veliu
- KYC: Persona identity verification
- Shipping: Integrated courier services

## Performance Considerations

### Optimization Strategies

- Code splitting with React.lazy() and Suspense
- Image optimization and lazy loading
- React Query caching with staleTime configuration
- Font optimization (DM Sans preload, Archivo async)
- Preconnect to external CDNs

### Mobile Performance

- Capacitor-based native apps
- PWA with service worker
- Optimized touch interactions
- Native-like animations

## Security Best Practices

### Data Protection

- No PII in localStorage/sessionStorage
- HTTP-only cookies for auth tokens
- Input validation with Zod schemas
- XSS protection via DOMPurify
- CSP headers in production

### Payment Security

- PCI-compliant Stripe integration
- 3D Secure authentication
- Fraud detection via Stripe Radar

## Constraints & Limitations

### Technical

- Single-page application (requires JavaScript)
- Italian market focus (IT language, EUR currency)
- Mobile-first design (responsive breakpoints)
- Browser support: modern browsers (Chrome, Safari, Firefox, Edge)

### Business

- Luxury fashion categories only (bags, accessories, jewelry)
- Italian sellers and buyers primarily
- Authentication required for transactions
- KYC mandatory for sellers

## Contributing & Support

### Code Style

- ESM imports only
- TypeScript strict mode
- Functional components with hooks
- Tailwind utility classes (no inline styles)
- Component size limit: <200 lines

### Testing

- Manual testing via dev server
- Puppeteer for E2E testing
- React Testing Library for unit tests

### Contact

- Technical support: support@veliu.com
- Business inquiries: business@veliu.com
- Documentation: https://veliu.com/docs

---

**Last Updated**: 2025-05-31
**Version**: 1.0.0