Skip to content

rragnarsd/pawsy

BranchesTags

Repository files navigation

Pawsy 🐾

Finding furry friends their forever homes.

Pawsy is a Flutter application that connects pets with loving homes. The app allows users to browse adoptable pets, shop for pet supplies, and manage their pet-related activities all in one place.

📱 Features

Core Functionality

  • Pet Browsing: Browse adoptable dogs and cats with detailed information
  • Pet Registration: Register new pets for adoption, lost pets, found pets, and volunteer opportunities
  • Donations: Support pet shelters and organizations through donation screen
  • E-commerce Store: Browse and purchase pet supplies and accessories
  • Product Search: Search for products by name or category
  • Shopping Cart: Add products to cart with quantity management
  • Checkout: Complete purchases with address and payment information
  • Promo Codes: Apply discount codes at checkout (TEST10 for 10% off, SAVE5 for $5 off, BIG20 for 20% off)
  • Order Management: Create orders, view order history, and see order details
  • User Authentication: Secure login, registration, and password recovery
  • User Profile: Manage profile, view favorites, track orders, and change language preferences
  • Favorites: Save favorite pets and products for quick access
  • Multi-language Support: Switch between English and Icelandic

User Experience

  • Bottom Navigation: Easy navigation between Home, Pets, Store, and Profile
  • Responsive Design: Beautiful UI with smooth animations
  • Authentication Flow: Seamless login/logout with protected routes
  • Real-time Updates: Live authentication state management

🏗️ Architecture

Feature-Based Architecture

The app follows a feature-based architecture where each feature is self-contained with its own:

  • Screens
  • Widgets
  • Providers (state management)
  • Services (data layer)
  • Models
lib/
├── common/           # Shared utilities, widgets, and configurations
│   ├── routes.dart   # Navigation configuration
│   ├── theme/        # App theming
│   ├── widgets/      # Reusable widgets
│   └── validators/   # Form validation
├── features/         # Feature modules
│   ├── auth/         # Authentication
│   ├── home/         # Home screen
│   ├── pets/         # Pet browsing and management
│   ├── store/        # E-commerce functionality
│   └── profile/      # User profile and settings
└── main.dart         # App entry point

Key Architectural Patterns

  1. Separation of Concerns

    • Screens: UI layer
    • Widgets: Reusable UI components
    • Providers: State management
    • Services: Business logic and API calls
    • Models: Data structures

  2. Dependency Injection

    • Services are provided via Riverpod providers
    • Easy to mock for testing
    • Loose coupling between layers

  3. Navigation

    • Declarative routing with GoRouter
    • StatefulShellRoute for bottom navigation persistence
    • Route guards based on authentication state

🔄 State Management

Riverpod

The app uses Flutter Riverpod 3.0.3 for state management, providing:

  • Type-safe dependency injection
  • Automatic dependency tracking
  • Easy testing and mocking
  • Performance optimizations

State Management Features

  • Reactive Updates: UI automatically updates when state changes
  • Computed Values: Derived state (e.g., cart totals)
  • Error Handling: AsyncValue for loading, data, and error states
  • Optimistic Updates: Local state updates before server confirmation

🛠️ Technology Stack

Core

  • Flutter: ^3.9.2 - Cross-platform UI framework
  • Dart: Modern language with strong typing

State Management & Navigation

  • flutter_riverpod: ^3.0.3 - State management
  • go_router: ^16.3.0 - Declarative routing
  • riverpod_lint: ^3.0.3 - Linting rules for Riverpod

Backend & Database

  • supabase_flutter: ^2.12.0 - Backend-as-a-Service
    • Authentication
    • Database (PostgreSQL)
    • Real-time subscriptions
    • Row Level Security (RLS) policies
    • Edge Functions (for secure payment processing)

Payment Processing

  • flutter_stripe: ^12.1.1 - Stripe payment integration
    • Secure payment processing via Stripe Payment Sheet
    • Server-side payment intent creation using Supabase Edge Functions
    • Test mode support for development

Database Schema

The app uses Supabase PostgreSQL with the following key tables:

  • users: User authentication (managed by Supabase Auth)
  • profiles: User profile information and delivery addresses
  • pets: Adoptable pets information
  • products: Store products catalog
  • cart_items: Shopping cart items
  • orders: Order history with products, addresses, and payment methods
  • promocodes: Promo code definitions with discount rules
  • promo_code_usage: Tracks promo code usage per user and order
  • favorites: User favorites for pets and products
  • lost_pets: Lost pet registrations
  • found_pets: Found pet registrations
  • volunteers: Volunteer registrations

Storage Buckets

The app uses Supabase Storage for file uploads:

  • lost-pets: Storage bucket for lost pet images

UI & Design

  • google_fonts: ^6.3.2 - Typography
  • flutter_animate: ^4.5.2 - Animations
  • cached_network_image: ^3.4.1 - Image caching
  • flutter_svg: ^2.2.3 - SVG support
  • shimmer: ^3.0.0 - Loading placeholders
  • smooth_page_indicator: ^2.0.1 - Page indicators
  • wolt_modal_sheet: ^0.11.0 - Modal sheets
  • flutter_spinkit: ^5.2.2 - Loading spinners
  • dropdown_button2: ^2.3.9 - Enhanced dropdown buttons
  • device_preview: ^1.3.1 - Device preview for development

Utilities

  • intl: ^0.20.2 - Internationalization
  • easy_localization: ^3.0.8 - Translations
  • flutter_dotenv: ^5.2.1 - Environment variable management
  • shared_preferences: ^2.5.4 - Local storage
  • image_picker: ^1.2.1 - Image selection for pet registration
  • url_launcher: ^6.3.2 - URL handling
  • phone_form_field: ^10.0.16 - Phone number input with validation
  • collection: ^1.19.1 - Collection utilities

Development

  • build_runner: ^2.10.4 - Code generation
  • json_serializable: ^6.11.2 - JSON serialization
  • json_annotation: ^4.9.0 - JSON annotations
  • flutter_lints: ^6.0.0 - Linting rules
  • flutter_launcher_icons: ^0.14.4 - App icon generation

📂 Project Structure

lib/
├── common/
│   ├── api_key.dart              # API configuration
│   ├── app_config.dart           # App configuration
│   ├── spacing_constants.dart    # Spacing constants
│   ├── text_constants.dart       # Text constants
│   ├── extensions.dart           # Dart extensions
│   ├── root.dart                 # Root navigation shell
│   ├── routes.dart               # Route definitions
│   ├── data/                     # Shared data models
│   ├── theme/                    # Theme configuration
│   ├── validators/               # Form validators
│   └── widgets/                  # Reusable widgets
│
├── features/
│   ├── auth/                     # Authentication feature
│   │   ├── auth_screen.dart      # Auth screen
│   │   ├── login/                # Login screen & logic
│   │   ├── register/             # Registration
│   │   ├── forgot_password/      # Password recovery
│   │   ├── provider/             # Auth state providers
│   │   └── shared/               # Shared auth widgets
│   │
│   ├── home/                     # Home screen feature
│   │   ├── home_screen.dart
│   │   ├── donation_screen.dart  # Donation screen
│   │   ├── models/               # Home-specific models (pet registration, volunteer, etc.)
│   │   ├── service/              # Home services (registration, donation)
│   │   ├── provider/             # Home state providers
│   │   ├── local_data/           # Local data and extensions
│   │   └── widgets/              # Home widgets (forms, lists, banners)
│   │
│   ├── pets/                     # Pet browsing feature
│   │   ├── pet_screen.dart
│   │   ├── pet_description_screen.dart
│   │   ├── models/               # Pet models
│   │   ├── provider/             # Pet state providers
│   │   ├── service/              # Pet services
│   │   ├── local_data/           # Pet local data
│   │   └── widgets/              # Pet widgets
│   │
│   ├── store/                    # E-commerce feature
│   │   ├── store_screen.dart
│   │   ├── search_screen.dart    # Product search screen
│   │   ├── model/                # Product models
│   │   ├── provider/             # Store providers (products, search)
│   │   ├── service/              # Store services
│   │   ├── widgets/              # Store widgets
│   │   ├── cart/                 # Shopping cart
│   │   │   ├── cart_screen.dart
│   │   │   ├── model/            # Cart models
│   │   │   ├── provider/         # Cart state management
│   │   │   ├── service/          # Cart services
│   │   │   └── widgets/          # Cart widgets
│   │   ├── checkout/             # Checkout flow
│   │   │   ├── checkout_screen.dart
│   │   │   ├── model/            # Checkout/Order models
│   │   │   ├── provider/         # Checkout state management
│   │   │   ├── service/          # Order creation service
│   │   │   └── widgets/          # Checkout widgets
│   │   │       ├── delivery_section.dart
│   │   │       ├── payment_section.dart
│   │   │       ├── payment_confirmation_sheet.dart
│   │   │       └── summary_section.dart
│   │
│   └── profile/                  # User profile feature
│       ├── profile_screen.dart
│       ├── favorite/             # Favorites management
│       │   ├── favorite_screen.dart
│       │   ├── favorite_pet_screen.dart
│       │   ├── favorite_product_screen.dart
│       │   ├── model/            # Favorite models
│       │   ├── provider/         # Favorite state management
│       │   ├── service/          # Favorite services
│       │   └── widgets/          # Favorite widgets
│       ├── order/                # Order history
│       │   ├── order_screen.dart # Order list screen
│       │   └── widgets/          # Order widgets
│       │       └── order_list.dart # Order details modal
│       ├── local_data/           # Profile local data
│       ├── provider/             # Profile providers
│       ├── service/              # Profile services
│       └── widgets/              # Profile widgets (language selector, edit form, etc.)
│
└── main.dart                     # App entry point

🔐 Authentication Flow

The app implements a secure authentication flow using Supabase:

  1. Landing Screen: Initial screen for unauthenticated users
  2. Login/Register: User authentication
  3. Password Recovery: Forgot password flow with email reset
  4. Protected Routes: Profile tab only visible when authenticated
  5. Auto-redirect: Authenticated users redirected from auth screens

Authentication State Management

  • Uses StreamProvider to listen to Supabase auth state changes
  • GoRouter automatically refreshes on auth state changes
  • Route guards prevent unauthorized access

📦 Order Management & Payments

Order Creation Flow

  1. User adds products to cart
  2. Navigates to checkout screen
  3. Selects/enters delivery address
  4. Optionally applies promo code for discount
  5. Confirms payment via Stripe:
    • Payment intent created securely via Supabase Edge Function
    • Stripe Payment Sheet presented to user
    • User completes payment (or can cancel)
  6. Order is created (only after successful payment):
    • Unique order number (ORD-XXXXX)
    • Current timestamp
    • All cart products
    • Delivery address snapshot
    • Payment method (Credit Card via Stripe)
    • Applied promo code (if any)
    • Discount amount (if promo code applied)
    • Total amount (after discount)
  7. Cart is automatically cleared after successful order creation
  8. Order confirmation modal displays order details

Payment Processing with Stripe

The app uses Stripe for secure payment processing with a server-side architecture:

Security Architecture

  • Client-side (Flutter app):
    • Presents Stripe Payment Sheet UI
    • Stores only publishable key (safe to expose)
  • Server-side (Supabase Edge Function):
    • Creates payment intents with Stripe secret key
    • Secret key stored securely in Supabase secrets
    • Never exposed in client code

Payment Flow

1. User initiates checkout
2. Flutter app → Supabase Edge Function (create-payment-intent)
3. Edge Function → Stripe API (create payment intent)
4. Stripe → Edge Function (client secret)
5. Edge Function → Flutter app (client secret)
6. Flutter app presents Stripe Payment Sheet
7. User completes payment
8. On success → Order created in database
9. On cancel → User returns to checkout

Test Mode

  • Use test card: 4242 4242 4242 4242
  • Any future expiry date
  • Any CVC

Order History

  • Order List: View all past orders in profile section
  • Order Details: Tap any order to view complete information
  • Empty States: Friendly messages when no orders exist
  • Error Handling: Graceful error messages for failed operations

Order Data Model

Each order contains:

  • user_id: User who placed the order
  • order_number: Unique identifier (e.g., ORD-12345)
  • order_placed_date: Timestamp of order creation
  • total: Total order amount (after discount)
  • products: JSON array of product details
  • delivery_address: JSON object with address information
  • payment_method: Selected payment method
  • promo_code_id: ID of applied promo code (if any)
  • discount_amount: Discount amount applied from promo code

🛍️ E-commerce Flow

  1. Browse Products: View available pet supplies by category
  2. Search Products: Use search functionality to find specific products
  3. Add to Cart: Select products and quantities
  4. Cart Management: Update quantities, remove items, view cart total
  5. Checkout: Enter delivery address and payment method
  6. Apply Promo Code: Enter promo code at checkout to receive discounts
  7. Order Creation: Create order with unique order number
  8. Order Confirmation: View order details and confirmation
  9. Order History: View all past orders in profile section
  10. Order Details: Tap any order to view full details in a modal

🎟️ Promo Codes

The app supports promotional discount codes that can be applied during checkout:

Available Test Codes

  • TEST10: 10% discount on your order (no minimum order amount)
  • SAVE5: $5 fixed discount on orders over $20 (each user can use up to 3 times)
  • BIG20: 20% discount on orders over $30 (limited to 500 total uses)

Features

  • Discount Types: Supports both percentage and fixed amount discounts
  • Validation: Promo codes are validated for:
    • Active status
    • Validity dates (valid_from and valid_until)
    • Maximum uses (if set)
    • Maximum uses per user
    • Minimum order amount requirements
  • Automatic Calculation: Discounts are automatically calculated and applied to order total
  • Usage Tracking: Promo code usage is tracked per user and order
  • Real-time Updates: Discount amount updates automatically when cart total changes

How to Use

  1. Add items to cart
  2. Navigate to checkout screen
  3. Scroll to "Promo Code" section
  4. Enter promo code (e.g., TEST10, SAVE5, or BIG20)
  5. Tap "Apply" to validate and apply the discount
  6. Discount will be reflected in the order summary
  7. Complete checkout to use the promo code

🐾 Pet Registration Features

The app supports multiple types of pet-related registrations:

  1. New Pet Registration: Register pets available for adoption

    • Pet details (name, category, gender, description)
    • Image upload
    • Location information

  2. Lost Pet Registration: Report lost pets

    • Pet information and description
    • Image upload to Supabase Storage
    • Automatic image URL generation

  3. Found Pet Registration: Report found pets

    • Similar to lost pet registration
    • Helps reunite pets with owners

  4. Volunteer Registration: Register as a volunteer

    • Personal information (name, email, phone)
    • Location selection
    • Contact information for organizations

🌍 Internationalization

The app supports two languages:

  • English (default)
  • Icelandic (Íslenska)

Users can switch languages from the profile screen. Language preferences are stored locally using shared_preferences.

🎨 Theming

The app uses a custom theme defined in lib/common/theme/:

  • Light Theme: Primary color scheme
  • Custom Colors: Brand-specific color palette
  • Typography: Google Fonts integration
  • Consistent Styling: Reusable theme components

📱 Navigation

Bottom Navigation Tabs

  1. Home (/) - Main dashboard with pet listings, registration options, and donation
  2. Pets (/pets) - Browse adoptable pets with detailed descriptions
  3. Store (/store) - E-commerce section with product browsing and search
  4. Profile (/profile) - User profile, favorites, orders, and settings (authenticated only)

Additional Routes

  • Landing (/landing) - Initial screen for unauthenticated users
  • Login (/login) - User authentication
  • Register (/register) - User registration
  • Forgot Password (/login/forgot_password) - Password recovery flow (In progress)
  • Donation (/donation) - Donation screen
  • Search (/store/search) - Product search screen
  • Cart (/store/cart) - Shopping cart
  • Checkout (/store/checkout) - Checkout and order creation

🗄️ Database Setup

Required Tables

The app requires the following Supabase tables to be set up:

  1. orders - Stores order information

    • id (BIGSERIAL PRIMARY KEY)
    • user_id (UUID, references auth.users)
    • order_number (TEXT, UNIQUE)
    • order_placed_date (TIMESTAMPTZ)
    • total (DECIMAL) - Final total after discount
    • products (JSONB)
    • delivery_address (JSONB)
    • payment_method (TEXT)
    • promo_code_id (UUID, NULLABLE, references promocodes)
    • discount_amount (DECIMAL, DEFAULT 0) - Discount applied from promo code
    • created_at (TIMESTAMPTZ)
    • updated_at (TIMESTAMPTZ)

  2. lost_pets - Stores lost pet registrations

    • id (BIGSERIAL PRIMARY KEY)
    • name (TEXT)
    • category (TEXT) - Pet category (dog/cat)
    • gender (TEXT) - Pet gender
    • description (TEXT)
    • img_url (TEXT) - URL to uploaded image
    • created_at (TIMESTAMPTZ)

  3. found_pets - Stores found pet registrations

    • Similar structure to lost_pets

  4. volunteers - Stores volunteer registrations

    • id (BIGSERIAL PRIMARY KEY)
    • full_name (TEXT)
    • email (TEXT)
    • phone (TEXT)
    • location_code (TEXT)
    • location_name (TEXT)
    • created_at (TIMESTAMPTZ)

⚙️ Setup & Configuration

Environment Variables

The app uses flutter_dotenv for secure credential management. To set up:

  1. Copy the example file:

    cp .env.example .env

  2. Fill in your credentials in .env:

    STRIPE_PUBLISHABLE_KEY=pk_test_your_key_here
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_ANON_KEY=your_anon_key_here

  3. Never commit .env to git (already in .gitignore)

Supabase Edge Functions Setup

For payment processing to work, you need to deploy the Supabase Edge Function:

  1. Install Supabase CLI:

    brew install supabase/tap/supabase

  2. Login and link your project:

    supabase login
supabase link --project-ref YOUR_PROJECT_REF

  3. Set Stripe secret key:

    supabase secrets set STRIPE_SECRET_KEY=sk_test_your_secret_key

  4. Deploy the Edge Function:

    supabase functions deploy create-payment-intent

For detailed setup instructions, see SUPABASE_SETUP.md.

Running the App

# Install dependencies
flutter pub get

# Run the app
flutter run

📚 Additional Documentation

📷 Screenshots

pawsy_screenshot

📷 Live Preview

pawsy.mov

Made with ❤️ for pets and their future families 🐾

About

⋆🐾⋆ Finding furry friends their forever homes. ⋆🐾⋆

Topics

dart cross-platform stripe software-development pet-project flutter gorouter uiux flutter-apps flutter-app flutter-developer riverpod uiux-design riverpod-state-management

Resources

Readme
Activity

Stars

1 star

Watchers

0 watching

Forks

1 fork
Report repository

Releases

No releases published

Packages

No packages published

Languages