# mahm0udbakir/pet-paw architecture

> Architecture diagram of the GitHub repository mahm0udbakir/pet-paw, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mahm0udbakir/pet-paw
- Repository: https://github.com/mahm0udbakir/pet-paw

## Overview

##### Project Type & Purpose
- This is a full-stack, multi-platform Flutter application (“pet-paw”) targeting Android, iOS, Web, Windows, macOS, and Linux.
- It provides pet-related user flows: onboarding, authentication (signup/login), pet profile creation, password reset, and theming/localization.
- Although there’s a placeholder “backend” folder, the actual backend appears to be provided by external services (Firebase Auth/Firestore/Storage or a custom REST API).

##### High-Level File Structure Analysis
- Top-level:
– Flutter/pet_paw: root of the Flutter project
– backend: empty placeholder, likely used to store server code if migrated in-repo
- Flutter/pet_paw/lib:
– app.dart & main.dart: application entry points, initial route to splash and onboarding
– app/core: configuration (api_config, token_storage), utils (theme, constants, exceptions, helpers)
– app/domain: state management using Cubit (Bloc) for language & theme
– app/features: feature modules following MVC or MVVM-style separation
· auth (login, signup, create pet profile)
· onboarding_and_getstarted
· reset_new_password
– localization: internationalization via ARB files and generated code
- Platform folders: android, ios, macos, windows, linux, web – containing platform-specific build files, plugin registrants, assets, and manifests
- Configuration: firebase.json, google-services.json indicating Firebase integration, CI workflow (deploy.yml)

##### Key Architecture & Technology Insights
- Presentation Layer: Flutter UI widgets organized by feature under lib/app/features/*/view and shared common widgets in app/common
- State Management (Domain): Cubit (Bloc) per feature to manage state and side effects
- Core Layer: Configuration (API base URL, token storage), shared utilities (exception mapping, theming, validation)
- Data Layer: Implicit – network calls (REST or Firebase SDK) invoked inside Cubit controllers; persistent token via token_storage
- External Services:
– Firebase Auth for signup/login/password reset
– Cloud Firestore / Realtime Database for user/pet data persistence
– Cloud Storage for pet images
– Potential custom REST API if using api_config

a. Main Components
- Flutter App (multi-platform)
– Presentation (Screens & Widgets)
– State Management (Cubit controllers)
– Core Utilities & Config
- External Services
– Auth Service (Firebase Auth or custom API)
– Data Service (Firestore / REST API)
– Storage Service (Cloud Storage)
- Backend (optional custom microservice in “backend” folder)
- Third-party / Platform plugins (Google sign-in, Camera, Local storage)
b. Relationships & Data Flow
1. User interacts with Presentation Layer → triggers Cubit event
2. Cubit invokes Data/Service layer via configured API client or Firebase SDK
3. Service layer communicates over HTTPS/SDK to Auth/Data/Storage services
4. Results/emitted states propagate back to Cubit → UI updates
c. Architectural Patterns & Principles
- Feature-based modularization: each feature has its own view, controller (Cubit), model
- Layered architecture: Presentation → Domain (Cubit) → Data/Service → External
- Dependency injection/configuration via api_config & token_storage
- Separation of concerns: theming, localization, utilities kept in core
d. Relevant Technologies & Libraries
- Flutter (Dart) multi-platform framework
- Bloc (Cubit) for state management
- Firebase SDK (Auth, Firestore, Storage) or Dio/Chopper for REST
- intl for localization
- FVM for Flutter version management
- Platform-specific build systems (Gradle, Xcode, CMake)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Side
    subgraph "Mobile/Desktop App" 
        direction TB
        %% Entry Points
        Main["main.dart"]:::client
        AppD["app.dart"]:::client
        Splash["splash_screen.dart"]:::client

        %% Presentation Layer
        subgraph "Presentation Layer"
            direction TB
            AuthViews["Auth Views"]:::client
            OnboardingViews["Onboarding Views"]:::client
            ResetViews["Reset Password Views"]:::client
        end

        %% State Management
        subgraph "State Management (Cubits & Controllers)"
            direction TB
            AuthCtrl["Auth Controllers"]:::state
            OnboardCtrl["Onboarding Controller"]:::state
            ResetCtrl["Reset Password Controller"]:::state
            AppLang["AppLanguage Cubit"]:::state
            AppTheme["AppTheme Cubit"]:::state
        end

        %% Core Layer
        subgraph "Core Configuration & Utilities"
            direction TB
            APIConfig["api_config.dart"]:::client
            TokenStore["token_storage.dart"]:::client
            ConstantsHelpers["Constants & Helpers"]:::client
            Exceptions["Exceptions"]:::client
            ThemeUtils["Theming"]:::client
            Validators["Validators"]:::client
        end

        %% Service Layer
        subgraph "Service Layer"
            direction TB
            ServiceClient["Firebase SDK / REST Client"]:::client
        end
    end

    %% External Services
    subgraph "Cloud Services"
        direction TB
        AuthService["Firebase Auth"]:::external
        DataService["Firestore / REST API"]:::external
        StorageService["Cloud Storage"]:::external
    end

    %% Optional Backend
    Backend["Custom Backend (placeholder)"]:::backend

    %% Relationships
    Main -->|initializes| Splash
    Splash -->|navigates to| AuthViews
    Splash -->|navigates to| OnboardingViews
    AuthViews -->|triggers events| AuthCtrl
    OnboardingViews -->|triggers events| OnboardCtrl
    ResetViews -->|triggers events| ResetCtrl

    AppLang -->|provides locale| AuthViews
    AppTheme -->|provides theme| AuthViews

    AuthCtrl -->|uses| APIConfig
    OnboardCtrl -->|uses| APIConfig
    ResetCtrl -->|uses| APIConfig
    AuthCtrl -->|uses| TokenStore
    OnboardCtrl -->|uses| TokenStore
    ResetCtrl -->|uses| TokenStore

    AuthCtrl -->|calls| ServiceClient
    OnboardCtrl -->|calls| ServiceClient
    ResetCtrl -->|calls| ServiceClient

    ServiceClient -->|SDK/API calls| AuthService
    ServiceClient -->|SDK/API calls| DataService
    ServiceClient -->|SDK/API calls| StorageService

    APIConfig -->|can target| Backend
    ServiceClient -->|can target| Backend

    %% Click Events
    click Main "https://github.com/mahm0udbakir/pet-paw/blob/main/Flutter/pet_paw/lib/main.dart"
    click AppD "https://github.com/mahm0udbakir/pet-paw/blob/main/Flutter/pet_paw/lib/app.dart"
    click Splash "https://github.com/mahm0udbakir/pet-paw/blob/main/Flutter/pet_paw/lib/splash_screen.dart"
    click AuthViews "https://github.com/mahm0udbakir/pet-paw/tree/main/Flutter/pet_paw/lib/app/features/auth/view"
    click OnboardingViews "https://github.com/mahm0udbakir/pet-paw/tree/main/Flutter/pet_paw/lib/app/features/onboarding_and_getstarted/view"
    click ResetViews "https://github.com/mahm0udbakir/pet-paw/tree/main/Flutter/pet_paw/lib/app/features/reset_new_password/view"
    click AuthCtrl "https://github.com/mahm0udbakir/pet-paw/tree/main/Flutter/pet_paw/lib/app/features/auth/controller"
    click OnboardCtrl "https://github.com/mahm0udbakir/pet-paw/tree/main/Flutter/pet_paw/lib/app/features/onboarding_and_getstarted/controller"
    click ResetCtrl "https://github.com/mahm0udbakir/pet-paw/tree/main/Flutter/pet_paw/lib/app/features/reset_new_password/controller"
    click AppLang "https://github.com/mahm0udbakir/pet-paw/blob/main/Flutter/pet_paw/lib/app/domain/app_language_cubit.dart"
    click AppTheme "https://github.com/mahm0udbakir/pet-paw/blob/main/Flutter/pet_paw/lib/app/domain/app_theme_cubit.dart"
    click APIConfig "https://github.com/mahm0udbakir/pet-paw/blob/main/Flutter/pet_paw/lib/app/core/config/api_config.dart"
    click TokenStore "https://github.com/mahm0udbakir/pet-paw/blob/main/Flutter/pet_paw/lib/app/core/config/token_storage.dart"
    click ConstantsHelpers "https://github.com/mahm0udbakir/pet-paw/tree/main/Flutter/pet_paw/lib/app/core/utils"
    click Exceptions "https://github.com/mahm0udbakir/pet-paw/tree/main/Flutter/pet_paw/lib/app/core/utils/exceptions"
    click ThemeUtils "https://github.com/mahm0udbakir/pet-paw/tree/main/Flutter/pet_paw/lib/app/core/utils/theme"
    click Validators "https://github.com/mahm0udbakir/pet-paw/tree/main/Flutter/pet_paw/lib/app/core/utils/validators"
    click Backend "https://github.com/mahm0udbakir/pet-paw/tree/main/backend/"

    %% Styles
    classDef client fill:#87CEEB,stroke:#333,stroke-width:1px,color:#fff
    classDef state fill:#98FB98,stroke:#333,stroke-width:1px,color:#000
    classDef external fill:#FFA500,stroke:#333,stroke-width:1px,color:#000
    classDef backend fill:#D3D3D3,stroke:#333,stroke-width:1px,color:#000
```
