# isaacpater31/pyp_platform architecture

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

- Interactive diagram: https://gitdiagram.com/isaacpater31/pyp_platform
- Repository: https://github.com/isaacpater31/pyp_platform

## Overview

##### Project Type and Purpose
- This is a full-stack, cross-platform mobile application (Android, iOS, Web, Desktop) built with Flutter.
- It connects two user roles (Clients and Professionals) through on-demand home services, using Firebase as the backend and various external services (OpenStreetMap, geolocation, payments, chat).

##### File Structure
- lib/ directory shows a clean-architecture pattern with separation into “controladores” (controllers) and “vistas” (views).
- platform folders (android/, ios/, linux/, macos/, windows/, web/) house native shells generated by Flutter.
- pubspec.yaml declares dependencies on Firebase, geolocator, OpenStreetMap, Flutter Chat UI, etc.

a. Mobile App (Flutter Client)
– UI Layer: views (login_view.dart, client_register_view.dart, etc.)
– Controller/Domain Layer: client_register_controller.dart, negotiation logic, scheduling, chat handler
– Data Layer: service classes that interact with Firebase and external APIs
b. Firebase Backend
– Authentication (Email/Password + Verification)
– Firestore Database (users, service_requests, messages, reviews, schedules, payments)
– Cloud Functions (business logic: negotiation, reminders, safety PIN)
– Storage (profile images, documents)
c. External Services
– OpenStreetMap / Geolocator: for address lookup and real-time location tracking
– Payment Gateway (e.g., Stripe/PayPal) for processing online payments
– Push Notification Service (Firebase Cloud Messaging)
d. Optional Future Component
– Web Admin Dashboard (to be built later)

##### Relationships and Data Flows
- The Flutter Client UI sends user events to Controllers -> Controllers invoke Data Services.
- Data Services call Firebase Auth for login/registration and Firestore for CRUD operations.
- Cloud Functions enforce business rules (e.g., bargaining, scheduling reminders) and trigger FCM.
- For location: Data Services call Geolocator/OpenStreetMap APIs and feed results back up to UI.
- Payment flows outbound to the Payment Gateway; transaction result is stored in Firestore.
- Chat messages flow bi-directionally via Firestore or a real-time chat service.

##### Architectural Patterns and Design Principles
- Clean Architecture: clear separation of UI, domain (controllers/use-cases), and data layers.
- Modular Code: controllers and views are grouped by feature (registration, login, chat).
- Reactive Streams or BLoC-style updates (UI observes data layer for real-time updates).
- Single Source of Truth: Firestore as centralized state management for shared data.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Side Layer
    subgraph "Client Side (Flutter App)"
        direction TB
        MainEntry["Main Entry Point\n(lib/main.dart)"]:::frontend
        subgraph "UI Layer"
            direction TB
            LoginView["Login View\n(login_view.dart)"]:::frontend
            ClientRegView["Client Registration View\n(client_register_view.dart)"]:::frontend
            RegSuccessView["Registration Success View\n(Register_success_view.dart)"]:::frontend
            RoleSelView["Role Selection View\n(role_selection_view.dart)"]:::frontend
        end
        subgraph "Controller Layer"
            direction TB
            ClientRegCtrl["Client Registration Controller\n(client_register_controller.dart)"]:::frontend
            NegotiationCtrl["Negotiation Controller"]:::frontend
            SchedulingCtrl["Scheduling Controller"]:::frontend
            ChatCtrl["Chat Controller"]:::frontend
        end
        subgraph "Data Services"
            direction TB
            FirebaseSDK["Firebase SDK Wrapper"]:::frontend
            GeoLocatorService["Geolocator Service"]:::frontend
            OSMService["OpenStreetMap Service"]:::frontend
            PaymentService["Payment Gateway Service"]:::frontend
            ChatService["Chat Service"]:::frontend
        end
    end

    %% Backend Layer
    subgraph "Backend Services (Firebase)" 
        direction TB
        Auth["Authentication"]:::backend
        Firestore["Firestore Database"]:::backend
        Functions["Cloud Functions"]:::backend
        Storage["Cloud Storage"]:::backend
        FCM["Firebase Cloud Messaging"]:::backend
    end

    %% External Third-Party APIs
    subgraph "External Services"
        direction TB
        OpenStreetMapAPI["OpenStreetMap API"]:::external
        GeolocatorAPI["Geolocator API"]:::external
        PaymentGateway["Payment Gateway\n(Stripe/PayPal)"]:::external
    end

    %% Flutter Shells
    subgraph "Native Shells"
        direction TB
        AndroidShell["Android Shell"]:::frontend
        iOSShell["iOS Shell"]:::frontend
        WebShell["Web Shell"]:::frontend
        LinuxShell["Linux Shell"]:::frontend
        MacShell["macOS Shell"]:::frontend
        WinShell["Windows Shell"]:::frontend
    end

    %% Dependency Declarations
    Pubspec["Dependencies\n(pubspec.yaml)"]:::frontend

    %% Connections Client Side
    MainEntry -->|launches| LoginView
    MainEntry -->|launches| ClientRegView
    MainEntry -->|launches| RoleSelView

    LoginView -->|user input| ClientRegCtrl
    ClientRegView -->|user input| ClientRegCtrl
    ClientRegCtrl -->|calls| FirebaseSDK
    NegotiationCtrl -->|calls| Functions
    SchedulingCtrl -->|calls| Functions
    ChatCtrl -->|uses| ChatService

    %% Data Services to Backend
    FirebaseSDK -->|Auth SDK| Auth
    FirebaseSDK -->|Firestore SDK| Firestore
    FirebaseSDK -->|Storage SDK| Storage
    Functions -->|reads/writes| Firestore
    Functions -->|triggers| FCM
    ChatService -->|reads/writes| Firestore

    GeoLocatorService -->|HTTP| GeolocatorAPI
    OSMService -->|HTTP| OpenStreetMapAPI
    PaymentService -->|HTTPS| PaymentGateway

    %% UI Data Flow
    LoginView -->|calls| FirebaseSDK
    RegSuccessView -->|display| ClientRegCtrl

    %% Shells
    MainEntry --> AndroidShell
    MainEntry --> iOSShell
    MainEntry --> WebShell
    MainEntry --> LinuxShell
    MainEntry --> MacShell
    MainEntry --> WinShell

    %% Dependency Declarations Link
    MainEntry --> Pubspec

    %% Click Events
    click MainEntry "https://github.com/isaacpater31/pyp_platform/blob/main/lib/main.dart"
    click LoginView "https://github.com/isaacpater31/pyp_platform/blob/main/lib/vistas/login_view.dart"
    click ClientRegView "https://github.com/isaacpater31/pyp_platform/blob/main/lib/vistas/client_register_view.dart"
    click RegSuccessView "https://github.com/isaacpater31/pyp_platform/blob/main/lib/vistas/Register_success_view.dart"
    click RoleSelView "https://github.com/isaacpater31/pyp_platform/blob/main/lib/vistas/role_selection_view.dart"
    click ClientRegCtrl "https://github.com/isaacpater31/pyp_platform/blob/main/lib/controladores/client_register_controller.dart"
    click Pubspec "https://github.com/isaacpater31/pyp_platform/blob/main/pubspec.yaml"
    click AndroidShell "https://github.com/isaacpater31/pyp_platform/blob/main/android/app/src/main/kotlin/com/example/pyp_platform/MainActivity.kt"
    click iOSShell "https://github.com/isaacpater31/pyp_platform/blob/main/ios/Runner/AppDelegate.swift"
    click WebShell "https://github.com/isaacpater31/pyp_platform/blob/main/web/index.html"
    click LinuxShell "https://github.com/isaacpater31/pyp_platform/blob/main/linux/runner/main.cc"
    click MacShell "https://github.com/isaacpater31/pyp_platform/blob/main/macos/Runner/MainFlutterWindow.swift"
    click WinShell "https://github.com/isaacpater31/pyp_platform/blob/main/windows/runner/main.cpp"

    %% Styles
    classDef frontend fill:#D6EAF8,stroke:#000
    classDef backend fill:#D5F5E3,stroke:#000
    classDef external fill:#FCF3CF,stroke:#000
```
