SWIRL revolutionizes online fashion discovery by combining:

• Swipe-based Interface: Tinder-like mechanics for effortless browsing
• AI Personalization: Machine learning that learns your style preferences
• Weekly Outfit Drops: Curated outfit recommendations every Monday
• Multi-Store Discovery: Products from Amazon, Noon, Namshi, and more
• Zero Friction: Browse anonymously, no login required

• 🎨 Beautiful UI: Smooth 60 FPS animations with haptic feedback
• 🤖 Smart Recommendations: ML-powered personalization engine
• 🛍️ Seamless Shopping: Direct purchase links to product pages
• 📱 Cross-Platform: Native iOS & Android with single Flutter codebase
• ⚡ Blazing Fast: Optimized feed preloading and image caching

• Swipe Gestures

  • 👉 Swipe Right → Like (add to Swirls)
  • 👈 Swipe Left → View Details
  • 👆 Swipe Up → Skip
  • 👇 Swipe Down → Add to Wishlist

• Personalized Feed

  • Style filters (Minimalist, Urban Vibe, Streetwear, Avant-Garde)
  • Brand following with priority in feed
  • ML-based recommendations (coming soon)

• Weekly Outfits

  • 2 coordinated outfits delivered every Monday
  • 5 individual high-confidence items
  • Push notifications for new drops

• Search & Browse

  • Advanced filters (price, brand, color, size, category)
  • Real-time search suggestions
  • Grid and swipe view modes

• Shopping Features

  • Swirls collection (liked items)
  • Wishlist with price alerts
  • Direct "Buy Now" links to stores
  • Shopping cart (Phase 2)

[Coming Soon]

• Flutter SDK 3.9.2 or higher
• Dart SDK 3.0+
• Android Studio / Xcode
• Supabase account (free tier)

# 1. Clone the repository
git clone https://github.com/yourusername/swirl.git
cd swirl

# 2. Navigate to the app directory
cd swirl

# 3. Install dependencies
flutter pub get

# 4. Set up environment variables
# Copy .env.example to .env and fill in your credentials
cp .env.example .env

# 5. Run the app
flutter run

Create a .env file in the swirl/ directory:

SUPABASE_URL=https://your-project-id.supabase.co
SUPABASE_ANON_KEY=your-anon-key-here

See SUPABASE_SETUP.md for detailed backend setup instructions.

Frontend

• Framework: Flutter 3.9.2+ (Dart)
• State Management: Riverpod 2.4+
• UI/Animations: flutter_animate, shimmer
• Image Caching: cached_network_image

Backend

• Database: Supabase (PostgreSQL)
• Storage: Supabase Storage (CDN-backed)
• Auth: Supabase Auth (anonymous + social login)
• Analytics: Firebase Analytics

Machine Learning (Phase 2)

• Content-based filtering with CLIP embeddings
• Collaborative filtering
• Hybrid recommendation model

swirl/
├── lib/
│   ├── core/                      # Core utilities
│   │   ├── theme/                 # Design system
│   │   ├── constants/             # App constants
│   │   └── providers/             # Global providers
│   │
│   ├── features/                  # Feature modules
│   │   ├── home/                  # Main swipe feed
│   │   ├── detail/                # Product details
│   │   ├── search/                # Search & filters
│   │   ├── swirls/                # Liked items
│   │   ├── profile/               # User profile
│   │   └── onboarding/            # First-time experience
│   │
│   ├── data/                      # Data layer
│   │   ├── models/                # Data models
│   │   ├── repositories/          # Repository pattern
│   │   └── services/              # API services
│   │
│   └── shared/                    # Shared widgets
│
├── assets/                        # Assets
│   ├── fonts/                     # Inter font family
│   ├── images/                    # App images
│   └── mock_data/                 # Mock JSON data
│
├── docs/                          # Documentation
├── android/                       # Android config
└── ios/                          # iOS config

10 core tables:

• users - User profiles and preferences
• products - Product catalog
• swipes - Comprehensive swipe tracking (13 fields)
• swirls - Liked items
• brands - Brand catalog
• brand_follows - User-brand relationships
• wishlist_items - Saved items
• carts / cart_items - Shopping cart
• weekly_outfits - ML-generated recommendations

See supabase_schema.sql for full schema.

Comprehensive documentation is available:

• 📘 Quick Start Guide - Get up and running in 5 minutes
• 🏃 Run App Guide - Detailed running instructions
• 🗄️ Supabase Setup - Backend configuration

• 📋 Product Requirements Document - Complete feature specifications
• 🏛️ Architecture Overview - System design
• ✅ Implementation Status - Current progress
• 🚀 Optimization Guide - Performance tips

• 🎨 Design System - Colors, typography, spacing
• 🔧 Testing Checklist - QA guidelines
• 🐛 Bug Fix Reports - Known issues

Primary Black: #1A1A1A
Primary White: #FFFFFF
Accent Coral:  #FF6B6B    // Like action
Accent Blue:   #4A90E2    // Details
Accent Green:  #4CAF50    // Wishlist

• Font Family: Inter (Variable)
• Scales: 12px to 32px
• Weights: Regular, SemiBold, Bold

• Card transitions: 300ms ease-out
• Detail modal: 400ms ease-in-out
• Shimmer loading: Continuous
• 60 FPS guaranteed

# Unit tests
flutter test

# Integration tests
flutter test integration_test/

# Widget tests
flutter test test/features/

• Swipe gestures work smoothly
• Feed preloading (20 cards ahead)
• Image caching operational
• Analytics tracking verified
• Detail view animations smooth
• Search filters functional
• ML recommendations (Phase 2)
• Social features (Phase 3)

# Android APK
flutter build apk --release

# Android App Bundle
flutter build appbundle --release

# iOS
flutter build ios --release

Different configs for dev/staging/production:

• Development: Mock data, debug logging
• Staging: Real database, analytics enabled
• Production: Optimized build, error tracking

• Initial Load: < 2 seconds
• Card Transitions: < 300ms (60 FPS)
• Image Load: < 1 second (cached after first view)
• Search Response: < 500ms
• Memory Usage: < 150 MB average

• Progressive image loading with BlurHash
• Aggressive feed preloading (20 cards)
• Image caching (100 MB limit)
• Lazy loading for off-screen content
• Virtual scrolling for large lists

• Core swipe functionality
• Product detail view
• Swirls (liked items)
• Basic search & filters
• Anonymous browsing
• Analytics tracking

• ML-powered personalization
• Weekly outfit recommendations
• Advanced search filters
• Price drop alerts
• Social sharing

• Shopping cart & checkout
• Payment integration (Stripe)
• User profiles & following
• Outfit collections
• Comments & likes

• AR virtual try-on
• Video product demos
• Live shopping events
• Stylist consultations
• Regional expansion (GCC)

We welcome contributions! Please see our Contributing Guidelines for details.

# Fork the repository
git clone https://github.com/yourusername/swirl.git

# Create a feature branch
git checkout -b feature/amazing-feature

# Make your changes and commit
git commit -m "Add amazing feature"

# Push to your fork
git push origin feature/amazing-feature

# Open a Pull Request

• Follow Flutter style guide
• Use Riverpod for state management
• Write tests for new features
• Document public APIs

This project is licensed under the MIT License - see the LICENSE file for details.

• Supabase - Backend infrastructure
• Flutter Team - Amazing framework
• Unsplash - Product images
• Inter Font - Typography
• Open Source Community - Inspiration and support

• Email: support@swirlapp.com
• Twitter: @SwirlApp
• Discord: Join our community
• Issues: GitHub Issues

If you like SWIRL, please give us a ⭐ on GitHub!