PetraCore Flutter Frontend Starter

A powerful CLI tool and package for generating Flutter projects with clean architecture, Firebase integration, and industry best practices. Based on proven patterns from production applications.

✨ Features

🏗️ Clean Architecture: Feature-based modular structure with clear separation of concerns
🔥 Firebase Integration: Pre-configured Firestore, Analytics, and Cloud Messaging
🎨 Design Presets: Choose from default, Vercel, Airbnb, or Apple design presets via app_ui_kit
🎨 Modern UI: Responsive design and comprehensive component library
🧩 BLoC Pattern: Predictable state management with Hydrated BLoC
🚀 CLI Tools: Generate projects and features instantly
🔐 Complete Authentication: Full auth flow with login, signup, OTP, email verification
📱 Multi-platform: iOS, Android, Web, macOS, Windows, Linux support
🔐 Security: Secure storage, environment variables, and authentication patterns
🎯 Best Practices: Linting rules, code generation, and project structure
📦 Rich Packages: Carefully selected and battle-tested dependencies
✨ Enhanced CLI: Beautiful, professional logging with levels (debug, info, warning, error, success) and colored output for improved user experience
🧩 Service Bootstrap: Add services, repositories, use cases, and BLoCs to existing features with petracore service

🆕 Recent Improvements (v1.1.0)

🧩 Service Bootstrap Command: petracore service <service_name> interactively bootstraps a new service inside an existing feature with optional model, repository, use cases, and BLoC/Cubit — all wired into the feature's barrel files and shared BlocProvider automatically
💬 Complete Chat Feature: petracore feature chat now generates a full chat feature with:
- Firestore-backed real-time messaging with chat & message models
- Chat list screen with flutter_slidable swipe-to-delete
- Chat detail screen with message bubbles, file sharing, and media preview
- Cloudinary CDN upload integration — files picked via file_picker are uploaded to Cloudinary before sending
- Voice/video call screens with call log, calling mode toggle, participant cards
- Group chat support — create group, group info screen, member management
- AttachmentSheet with gallery, camera, video, document, and audio options
- open_filex tap-to-open for file-type messages
- All dependencies (flutter_slidable, file_picker, open_filex, image_picker, cloud_firestore) auto-injected into pubspec.yaml
- flutter pub get runs automatically after generation
🗑️ MediaType Enum Removed: Replaced the custom MediaType enum with String? mimeType across both chat and media features — eliminates type conflicts and aligns with standard MIME type conventions. All isImage/isVideo/isFile checks now use mimeType?.startsWith(...) patterns
📁 FileUploadDto Simplified: fileType: MediaType → mimeType: String? in the media feature's Cloudinary DTO
♻️ Design Preset Simplification: Removed the entire local DesignPresetId/DesignPreset class hierarchy. Preset names are now plain strings — no local color/typography/radius definitions. All visual tokens come from app_ui_kit via AppUiKitPreset in generated bootstrap.dart
--design-preset Values: The design-preset CLI option accepts the same 12 preset names: default, vercel, airbnb, apple, spotify, vibrant, highContrast, starbucks, linear, notion, mongodb, raycast
--include-auth Flag: Generate auth alongside the project in one step — petracore init my_app --include-auth
app_ui_kit Theming: All theme and component generation removed locally. Everything comes from the app_ui_kit package (AppScaffold, AppUiKit.themes, design presets)
Route Deduplication: Auth route constants no longer duplicate on rerun — safe to generate auth multiple times
AnimatedSplashLogo Fix: Splash screen logo widget is now correctly generated to disk
Screen Consolidation: Flat screen directory structure, no more material/mix subdirectories

📋 What You Get

Project Structure

your_project/
├── lib/
│   ├── app/                    # App-level configuration
│   │   ├── constants/          # App constants and string values
│   │   ├── view/               # Main app widget
│   │   └── theme/              # Color values (brand palette from design preset)
│   ├── core/                   # Shared utilities and components
│   │   ├── components/        # Reusable UI components
│   │   ├── data/              # Core data services and domain logic
│   │   └── utils/             # Utility functions and extensions
│   ├── features/              # Feature modules (clean architecture)
│   │   ├── main_app/           # Dashboard screen (auto-generated)
│   │   └── shared/            # Shared feature components
│   ├── navigation/            # App navigation and routing
│   └── main.dart              # Entry point
├── assets/                     # Images, SVGs, Lottie files
├── fonts/                      # Custom fonts
├── firebase.json              # Firebase configuration
└── analysis_options.yaml     # Comprehensive linting rules

Key Components

Bootstrap Pattern: Centralized app initialization with error handling
Repository Pattern: Data layer abstraction for testability
Use Cases: Business logic separation following Clean Architecture
BLoC/Cubit: State management with persistence
Custom Components: Buttons, text fields, scaffolds, loading states
Navigation: Declarative routing with GoRouter
Extensions: Handy utilities for strings, context, and more

🚀 Installation

Global Installation (Recommended)

dart pub global activate petracore_flutter_frontend_starter

Local Installation

dart pub add petracore_flutter_frontend_starter

📖 Usage

Create a New Project

# Interactive mode (prompts for design preset, auth, etc.)
petracore init my_awesome_app

# With specific design preset (skips interactive prompt)
petracore init my_app --design-preset apple

# Generate with auth feature included
petracore init my_app --include-auth

# With custom organization
petracore init my_app --org com.mycompany

# With custom description
petracore init my_app --description "My amazing Flutter application"

# Force overwrite existing directory
petracore init existing_app --force

# Skip all interactive prompts (uses defaults)
petracore init my_app --no-interactive

Generate Features

# Generate a complete feature with all components (BLoC provider auto-registered)
petracore feature user_profile

# Generate feature without BLoC
petracore feature simple_feature --no-bloc

# Generate feature with custom output directory
petracore feature profile --output lib/modules

# Generate feature without models
petracore feature ui_feature --no-models

# Alternative syntax
petracore generate feature chat

Note: When generating features with BLoC enabled, the CLI automatically registers the feature's BLoC provider in lib/features/shared/presentation/controllers/bloc_provider.dart. No manual editing needed.

Generate Complete Authentication Flow

# Generate auth alongside project (recommended — one step)
petracore init my_app --include-auth

# Or generate auth in an existing project (interactive)
petracore auth

# Non-interactive with specific features
petracore auth --no-interactive --login --signup --forgot-password --otp

# Full auth flow with all features
petracore auth --login --signup --email-verification --forgot-password --phone-verification --otp --social-auth --device-token

# Basic auth setup
petracore auth --no-interactive --login --signup

Generate Complete Media Feature

# Interactive mode - choose full media or basic feature
petracore feature media

# Full media feature with Cloudinary, image picker, BLoCs, and widgets
# Auto-detected "media" keyword prompts for complete setup

Generate Complete Chat Feature

# Interactive mode - choose full chat or basic feature
petracore feature chat

# Full chat feature with:
# - Firestore real-time messaging
# - Cloudinary file upload integration
# - Voice/video call screens
# - Group chat support
# - File sharing with AttachmentSheet
# Auto-detected "chat" keyword prompts for complete setup

Bootstrap a Service Into an Existing Feature

# Interactive prompt walks you through the setup
petracore service payment

# The command asks:
# 1. Which existing feature to add the service to
# 2. Whether to create a model (with DTOs and Params)
# 3. Whether to create a repository (name defaults to <service>_repository)
# 4. Whether to create use cases (name defaults to <service>_use_cases)
# 5. Whether to create BLoC/Cubit (prefix defaults to the entity name)
#
# All generated files are automatically exported in the feature's barrel
# index and the shared BlocProvider is updated if BLoCs are added.

The service command is ideal for adding new API integrations to an existing feature. For example, if you have a shop feature and want to add a payment service:

petracore service payment
# Feature name: shop
# Create a model? (y/N): y
# Model name: transaction
# Create a repository? (Y/n): (enter)
# Create use cases? (Y/n): (enter)
# Create BLoC/Cubit? (Y/n): (enter)

This generates:

data/remote/payment_service.dart — Dio-based API service
data/remote/payment_repository.dart — Repository with Either pattern
data/models/transaction_model.dart — Model + DTOs + Params
data/domain/payment_use_cases.dart — Create/Delete/Get/Update use cases
presentation/controllers/ — Cubit, Action BLoC, Data BLoC, BlocProvider
Updates shop_index.dart, presentation.dart, and shared BlocProvider

Available Options

Init Command Options

--design-preset: Design preset - default (default), vercel, airbnb, or apple
--include-auth: Generate auth feature alongside the project
--no-interactive: Skip interactive prompts and use defaults
--org: Organization identifier (default: com.petracore)
--description: Project description
--force: Force creation even if directory exists
--verbose: Enable detailed output

Feature Command Options

--bloc / --no-bloc: Include BLoC/Cubit (default: true)
--repository / --no-repository: Include repository pattern (default: true)
--use-cases / --no-use-cases: Include use cases (default: true)
--models / --no-models: Include data models (default: true)
--list: Include a list screen for the feature (default: false)
--output: Custom output directory (default: lib/features)

Auth Command Options

--login / --no-login: Include login functionality (default: true)
--signup / --no-signup: Include signup functionality (default: true)
--email-verification: Include email verification (default: false)
--forgot-password: Include forgot password functionality (default: false)
--phone-verification: Include phone verification (default: false)
--otp: Include OTP (One-Time Password) functionality (default: false)
--social-auth: Include social authentication placeholders (default: false)
--device-token: Include device token support for push notifications (default: false)
--interactive / --no-interactive: Use interactive mode (default: true)
--output: Output directory (default: current directory)

🔧 Generated Architecture

Feature Structure

Each generated feature follows this structure:

features/your_feature/
├── your_feature_index.dart           # Barrel export file (exports models directly)
├── data/
│   ├── models/
│   │   └── your_feature_model.dart   # Data models with JSON serialization
│   ├── remote/
│   │   ├── your_feature_service.dart     # API service
│   │   ├── your_feature_repository.dart  # Repository interface & implementation
│   │   └── dto/
│   │       ├── create_your_feature_dto.dart
│   │       ├── update_your_feature_dto.dart
│   │       └── your_feature_params.dart
│   └── domain/
│       └── your_feature_use_cases.dart   # Business logic use cases
└── presentation/
    ├── controllers/
    │   ├── cubits/
    │   │   └── your_feature_cubit.dart   # Cubit state management
    │   ├── blocs/
    │   │   ├── multiple_your_feature_bloc/  # Data BLoC (multi-state)
    │   │   │   ├── multiple_your_feature_bloc.dart
    │   │   │   ├── multiple_your_feature_event.dart
    │   │   │   └── multiple_your_feature_state.dart
    │   │   └── your_feature_action_bloc/   # Action BLoC (single-state)
    │   │       ├── your_feature_action_bloc.dart
    │   │       ├── your_feature_action_event.dart
    │   │       └── your_feature_action_state.dart
    │   ├── your_feature_bloc_provider.dart  # BLoC provider (auto-registered)
    │   └── your_feature_controller_index.dart
    ├── screens/
    │   ├── your_feature_screen.dart  # Main feature screen
    │   └── your_feature_screens_index.dart
    ├── widgets/
    └── presentation.dart             # Presentation barrel export

Core Packages Included

# Architecture & State Management
flutter_bloc: ^8.1.3           # Predictable state management
hydrated_bloc: ^9.1.5          # State persistence
provider: ^6.0.2               # Dependency injection
equatable: ^2.0.5              # Value equality

# Navigation
go_router: ^10.0.0             # Declarative routing

# UI & Design  
flutter_screenutil: ^5.4.0     # Responsive design
flutter_hooks: ^0.18.6         # React-like hooks
animations: ^2.0.7             # Rich animations
gap: ^3.0.1                    # Spacing widgets
google_fonts: ^4.0.4           # Custom fonts
cached_network_image: ^3.2.3   # Optimized image loading
lottie: ^2.2.0                 # Lottie animations

# Network & API
dio: ^5.3.3                    # HTTP client
pretty_dio_logger: ^1.4.0      # Request/response logging

# Security & Storage  
flutter_secure_storage: ^9.0.0 # Secure key-value storage
flutter_dotenv: ^5.0.2         # Environment variables

# Code Generation
json_serializable: ^6.8.0      # JSON serialization
build_runner: ^2.4.11          # Code generation runner

# Functional Programming
dartz: ^0.10.1                 # Functional programming utilities

# Firebase (optional)
firebase_core: ^3.12.1         # Firebase core
cloud_firestore: ^5.6.5        # Cloud Firestore
firebase_analytics: ^11.4.4    # Analytics
firebase_messaging: ^15.2.4    # Cloud Messaging

🛠️ Development Workflow

After Creating a Project

Navigate to your project:
```
cd your_project_name
```
Install dependencies:
```
flutter pub get
```

Generate code (for models):

flutter packages pub run build_runner build

Run your app:
```
flutter run
```

Adding New Features

Generate the feature:
```
petracore feature user_profile
```
BLoC provider auto-registered: The CLI automatically adds the feature's BLoC provider to lib/features/shared/presentation/controllers/bloc_provider.dart - no manual step needed.

Generate code (if using models):

flutter packages pub run build_runner build

Navigation routes are auto-registered: Both auth and feature generators automatically register routes in lib/navigation/routes.dart (using the Route data class), create a per-feature route list in lib/navigation/routes/<feature>_routes.dart, and update router.dart — no manual editing needed.

Adding Services to Existing Features

Bootstrap the service:
```
petracore service payment
```
Follow the prompts to optionally create a model, repository, use cases, and BLoC/Cubit.
All wiring is automatic: The feature's barrel index is updated with new exports, the presentation barrel registers new controllers, and the shared BlocProvider is updated if BLoCs are generated — no manual editing needed.

🎨 Design Presets & Theming

PetraCore uses the app_ui_kit package for all theming and UI components — no theme files are generated locally.

Design Presets

Choose a preset when creating a project with --design-preset:

default: Balanced defaults suitable for most products
vercel: Minimal, geometric design language inspired by Vercel
airbnb: Warm and rounded consumer UI inspired by Airbnb
apple: San Francisco typography and clean surfaces inspired by Apple
spotify: Green-on-dark, media-centric style inspired by Spotify
vibrant: Saturated palettes with denser visual rhythm
highContrast: Maximum readability with strong foreground/background separation
starbucks: Warm neutrals with layered green palette inspired by Starbucks
linear: Precise dark interface with lavender accent inspired by Linear
notion: Calm neutral canvas with blue accent inspired by Notion
mongodb: Developer-focused green with dark surfaces inspired by MongoDB
raycast: Utility-dark shell with crisp neutrals inspired by Raycast

Color Values

lib/app/theme/color_values.dart is generated as the source of truth for brand colors:

Primary, secondary, technical colors
Neutral palette (50-600 scale)
Error, success, warning, info states
Surface colors (white, black, overlays)

Components

All components (AppScaffold, BaseScaffold, buttons, inputs, etc.) come from app_ui_kit. Use AppUiKit.themes to access the active theme. Modify color_values.dart to customize brand colors — all theme colors derive from these values.

🎨 Customization

Themes and Design

Modify lib/app/theme/color_values.dart to customize brand colors
Update lib/app/constants/app_constants.dart for design tokens
Add custom fonts to fonts/ directory

Components

Extend components in lib/core/components/
Add new utilities in lib/core/utils/
Create custom extensions in lib/core/utils/extensions/

Configuration

Environment variables in env.json
App-level config in lib/app/app/constants/

🧪 Testing

The generated project includes:

Unit test structure in test/
Widget test examples
BLoC testing patterns
Repository testing with mocks

Run tests:

flutter test

📚 Examples

Creating a Complete App

# Create a full-featured app with auth included
petracore init social_media_app \
  --org com.yourcompany \
  --description "A social media application with real-time features" \
  --include-auth

cd social_media_app
flutter pub get

# Generate core features
petracore feature user_profile  
petracore feature feed
petracore feature chat    # Full chat with calls, groups, file sharing

# Generate code and run
flutter packages pub run build_runner build
flutter run

Authentication Flow Examples

# Complete authentication flow (interactive)
petracore auth

# Full-featured auth with all options
petracore auth --no-interactive \
  --login --signup --email-verification \
  --forgot-password --otp --social-auth

# Basic login/signup only
petracore auth --no-interactive --login --signup

# Auth with OTP verification
petracore auth --no-interactive --login --signup --otp

Feature Generation Examples

# Basic feature generation
petracore feature user_profile

# Simple UI-only feature  
petracore feature settings --no-bloc --no-repository --no-use-cases

# Complex feature with custom location
petracore feature payment \
  --output lib/modules \
  --bloc \
  --repository \
  --use-cases \
  --models

# Bootstrap a service into an existing feature
petracore service payment

🔍 Advanced Usage

Custom Templates

You can extend the CLI by creating your own templates in the templates/ directory.

Integration with Existing Projects

The feature generator works with any Flutter project that follows similar conventions.

CI/CD Integration

The generated projects include:

GitHub Actions workflows (coming soon)
Proper linting configuration
Testing setup
Build configuration

Development Setup

git clone https://github.com/yourusername/petracore_flutter_frontend_starter.git
cd petracore_flutter_frontend_starter
dart pub get

# Run tests
dart test

# Test CLI locally
dart run bin/main.dart --help

📄 License

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

🙏 Acknowledgments

Built with inspiration from clean architecture principles
Based on patterns from production Flutter applications
Incorporates Flutter community best practices

🆘 Support

🐛 Issues: GitHub Issues

Made with ❤️ by the PetraCore Team

PetraCore Flutter Frontend Starter

✨ Features

🆕 Recent Improvements (v1.1.0)

📋 What You Get

Project Structure

Key Components

🚀 Installation

Global Installation (Recommended)

Local Installation

📖 Usage

Create a New Project

Generate Features

Generate Complete Authentication Flow

Generate Complete Media Feature

Generate Complete Chat Feature

Bootstrap a Service Into an Existing Feature

Available Options

Init Command Options

Feature Command Options

Auth Command Options

🔧 Generated Architecture

Feature Structure

Core Packages Included

🛠️ Development Workflow

After Creating a Project

Adding New Features

Adding Services to Existing Features

🎨 Design Presets & Theming

Design Presets

Color Values

Components

🎨 Customization

Themes and Design

Components

Configuration

🧪 Testing

📚 Examples

Creating a Complete App

Authentication Flow Examples

Feature Generation Examples

🔍 Advanced Usage

Custom Templates

Integration with Existing Projects

CI/CD Integration

Development Setup

📄 License

🙏 Acknowledgments

🆘 Support

Libraries

petracore_flutter_frontend_starter package