Tayri | طيري 🦅

Your smart guide to birds of the GCC | دليلك الذكي لطيور الخليج

---

📖 Overview

Tayri is a GCC-focused bird identification and birdwatching mobile app that combines:

• 🤖 AI-powered bird identification from photos
• 📚 Comprehensive GCC bird guide (bilingual EN/AR)
• 📝 Personal sighting logger with location tracking
• 📸 Beautiful photo branding for social sharing
• 💰 Freemium monetization (Free + Pro subscriptions)
• 🌍 Regional focus: Kuwait, Saudi Arabia, UAE, Qatar, Bahrain, Oman

This repository contains a fully functional Flutter MVP with:

• ✅ Complete UI/UX in Arabic + English (RTL/LTR)
• ✅ Mock bird identification service (ready for AI integration)
• ✅ 8 GCC bird species with detailed profiles
• ✅ Camera, sharing, and watermarking features
• ✅ Clean architecture ready for production APIs

---

🚀 Quick Start

Prerequisites

• Flutter 3.16+ (Install)
• Dart 3.2+
• IDE: VS Code or Android Studio

Installation

# 1. Clone the repository
cd berd-ai/flutter_app

# 2. Install dependencies
flutter pub get

# 3. Generate code (Hive adapters, localization)
flutter pub run build_runner build --delete-conflicting-outputs

# 4. Add font files (download Poppins + Cairo from Google Fonts)
# Place in assets/fonts/Poppins/ and assets/fonts/Cairo/

# 5. Add app logo
# Place tayri_logo.png in assets/logo/

# 6. Run the app
flutter run

---

📂 Documentation

Essential Guides

1. TAYRI_ARCHITECTURE.md Complete architecture overview, design system, data models, and technical decisions.

2. TAYRI_IMPLEMENTATION_GUIDE.md Detailed implementation guide with integration roadmap, testing strategy, and deployment instructions.

Quick Reference

• Entry Point: flutter_app/lib/main.dart
• Routing: flutter_app/lib/app/router.dart
• Theme: flutter_app/lib/app/theme.dart
• Constants: flutter_app/lib/core/constants/app_constants.dart
• Mock Birds: flutter_app/lib/data/mock_data/mock_birds.dart
• Localization: flutter_app/lib/core/l10n/intl_*.arb

---

🎯 Key Features

1. Bird Identification

• Camera with grid overlay and social mode
• AI identification (mock service ready for real ML model)
• Confidence scoring with alternative matches
• GCC-optimized species recognition

2. Bird Guide

• 8 GCC species (flamingos, herons, bulbuls, larks, terns, etc.)
• Bilingual profiles (English + Arabic)
• Detailed info: habitat, behavior, diet, migration, conservation status
• Birdwatching tips specific to GCC regions

3. Social Sharing

• Branded watermarking (Free tier)
• 3 share templates: Minimal, Bottom Strip, Full Card (Pro)
• Pre-filled captions with hashtags
• System share sheet (Instagram, WhatsApp, X, etc.)

4. Monetization

• Free Tier: 20 IDs/month, 50 sightings, watermarked photos
• Tayri Pro: Unlimited IDs, offline packs, export, premium templates
• Paywall UI ready for in-app purchases

5. Localization

• Full bilingual support (English + Arabic)
• RTL/LTR layouts automatically switch
• 80+ translated strings
• Locale-aware dates and numbers

---

🏗️ Architecture

Tech Stack

Layer	Technology
Framework	Flutter 3.16+
State Management	Riverpod 2.x
Routing	GoRouter
Local Storage	Hive
Localization	flutter_localizations + intl
Camera	camera plugin
Image Processing	image package
Sharing	share_plus

Project Structure

flutter_app/
├── lib/
│   ├── main.dart                # Entry point
│   ├── app/                     # App config, routing, theme
│   ├── core/                    # Constants, utils, localization
│   ├── domain/                  # Entities (9 data models)
│   ├── data/                    # Services, repositories, mock data
│   └── features/                # UI screens by feature
├── pubspec.yaml
└── assets/
    ├── logo/
    ├── images/
    └── fonts/

---

🔌 Integration Roadmap

Phase	What	When	Status
Phase 0	MVP with mock data	✅ Complete	✅ Done
Phase 1	Backend + Auth	Week 1-2	🔲 TODO
Phase 2	Bird ID AI	Week 3-4	🔲 TODO
Phase 3	Bird Database CMS	Week 5-6	🔲 TODO
Phase 4	Sightings Sync	Week 7-8	🔲 TODO
Phase 5	Payments	Week 9-10	🔲 TODO
Phase 6	Content & Shops	Week 11-12	🔲 TODO
Phase 7	Analytics	Week 13-14	🔲 TODO

TODO: Real API Integration Points

// 1. Bird Identification AI
// Replace: lib/data/services/mock_bird_identification_service.dart
// With: TensorFlow Lite, Google Vision API, or custom ML model

// 2. Backend & Auth
// Add: Firebase, Supabase, or custom API
// Implement: User auth, profile management

// 3. Bird Database
// Replace: lib/data/mock_data/mock_birds.dart
// With: Strapi CMS, Contentful, or REST API

// 4. Payments
// Add: in_app_purchase (iOS/Android) or Stripe
// Implement: Subscription validation

// 5. Analytics
// Add: Firebase Analytics, Mixpanel
// Track: User engagement, IDs, shares

---

🎨 Branding

Colors

• Primary Sky Blue: #1E88E5 – main brand color
• Soft Sea Blue: #90CAF9 – accents
• Palm Green: #4CAF50 – nature, success
• Desert Sand: #FFE0B2 – warm backgrounds

Typography

• Latin: Poppins (friendly, rounded)
• Arabic: Cairo (modern, readable)

Assets Needed

• App icon (1024x1024)
• Splash screen image
• Bird photos (100+ species)
• Logo variations (light/dark)

---

🧪 Testing

# Unit tests
flutter test

# Widget tests
flutter test test/

# Integration tests
flutter test integration_test/

# Coverage
flutter test --coverage

---

📦 Build & Deploy

Android (APK)

flutter build apk --release

iOS (IPA)

flutter build ios --release
# Then upload via Xcode Organizer

Production Checklist

• Test on iOS + Android (physical devices)
• Test Arabic RTL layout thoroughly
• Add camera/photo permissions to manifests
• Create privacy policy and terms of service
• Prepare App Store / Play Store listings (EN + AR)
• Create screenshots (both languages)
• Set up analytics and crash reporting
• Configure CI/CD (GitHub Actions, Codemagic)

---

📞 Support

Questions?

• Architecture: See TAYRI_ARCHITECTURE.md
• Implementation: See TAYRI_IMPLEMENTATION_GUIDE.md
• Flutter Docs: docs.flutter.dev

Common Issues

Camera not working?

• Add permissions to Info.plist (iOS) and AndroidManifest.xml (Android)

Fonts not loading?

• Download Poppins and Cairo from Google Fonts
• Place in assets/fonts/ and verify pubspec.yaml

Build runner fails?

flutter pub run build_runner build --delete-conflicting-outputs

---

🌟 Features Highlight

Current (MVP - Mock Data)

• ✅ Full bilingual UI/UX (EN/AR, RTL/LTR)
• ✅ Bird camera with grid + social mode
• ✅ Mock AI bird identification (2-3s delay)
• ✅ 8 GCC bird species profiles
• ✅ Share editor with watermarking
• ✅ Paywall (Free vs Pro comparison)
• ✅ Clean architecture ready for APIs

Coming Soon (With Real APIs)

• 🔲 Real AI bird identification (TF Lite / Vision API)
• 🔲 100+ GCC bird species database
• 🔲 User accounts with cloud sync
• 🔲 Offline bird packs (Pro)
• 🔲 Export sightings (CSV/PDF)
• 🔲 GCC shops and tours integration
• 🔲 Educational articles
• 🔲 In-app purchases (Pro subscriptions)
• 🔲 Push notifications (rare bird alerts)
• 🔲 Community features (leaderboards)

---

📄 License

© 2025 Tayri. All rights reserved.

Tayri | طيري - Built with ❤️ for the GCC birdwatching community

---

Ready to take flight! 🦅

دليلك الذكي لطيور الخليج 🐦

Documentation • Implementation Guide • Flutter Docs