# mohamad-amen/peeko architecture

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

- Interactive diagram: https://gitdiagram.com/mohamad-amen/peeko
- Repository: https://github.com/mohamad-amen/peeko

## Overview

##### Project Type and Purpose
- Peeko is a full-stack social-media style mobile application (TikTok-inspired short video sharing) where the mobile client is built in Flutter and communicates with an external MERN-stack backend API.
- The file tree reveals a single Flutter codebase (`lib/…`) with an Android folder for platform integration, plus dependencies such as Provider, GoRouter, GetIt, and Shared Preferences.

##### File Structure
- Top-level directories:
- android/… – Native Android project and Gradle configs
- lib/… – Flutter application code
- assets/ – Images and screenshots
- test/ – Widget test
- Under lib/:
- core/ – Core app services, router, DI, themes
- features/ – Feature modules (auth, comments, profile, videos) each containing UI pages, state providers, services, models, widgets
- Configuration files: pubspec.yaml, analysis_options.yaml, GitHub workflow for releases.

##### Key Architectural Insights from README
- Flutter front end with HTTP-based API calls, DI via GetIt, state management via Provider, routing via GoRouter, persistent storage via Shared Preferences.
- External dependency: MERN API (hosted separately).

##### Main Components
a. Mobile Device / OS Layer
- Android (and potentially iOS) hosting the Flutter engine
b. Flutter Application
- Presentation Layer: Feature UI pages & widgets
- Navigation Layer: GoRouter routes & deep linking
- State Management: Provider-based ViewModels/Providers per feature
- Service Layer:
- ApiService (HTTP client for MERN API)
- LocalStorageService (Shared Preferences)
- Feature-specific services (AuthService, MediaService, DeviceInfoService)
- Dependency Injection: GetIt service locator
- Data Layer: Dart Models (VideoModel, CommentModel, UserModel)
c. External Services
- MERN-stack backend API (authentication, video storage, comments, user profiles)
- CDN or file storage for video assets (via backend)

##### Relationships and Interactions
- User taps UI → Presentation Layer notifies Provider → Provider invokes Service → ApiService makes HTTP calls to MERN API → JSON response mapped to Dart Models → Provider updates state → UI re-renders
- Some flows involve LocalStorageService for caching tokens or preferences (e.g., auth tokens, theme settings)
- GoRouter intercepts deep links or navigation events, resolves to specific feature pages
- GetIt resolves service dependencies at runtime

##### Architectural Patterns and Design Principles
- Modular feature-based architecture (each major feature isolated under lib/features)
- MVVM-style separation: UI (Views) <→ Providers (ViewModels) <→ Services (Models/Data)
- Single Responsibility: each service handles one concern (API, storage, device info)
- Dependency injection for loose coupling and testability

##### Technologies and Frameworks to Annotate
- Flutter SDK and Engine
- Dart: language, models
- GoRouter: routing & deep links
- Provider: state management
- GetIt: DI container
- Shared Preferences (LocalStorage)
- HTTP (dart:io or http package)
- MERN API endpoint URLs

##### Detailed Elements to Capture
- Core service locator initialization (`service_locator.dart`)
- App router setup (`app_router.dart`) with feature route definitions
- Example feature flow: VideoFeedPage → VideosProvider → MediaService → ApiService → MERN/videos
- LocalStorage interactions in AuthService for token management
- DeviceInfoService usage for analytics or device-specific logic

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Platform
    MobileOS["Mobile OS (Android/iOS)"]:::external
    click MobileOS "https://github.com/mohamad-amen/peeko/blob/main/android/app/src/main/kotlin/com/example/peeko/MainActivity.kt"

    %% Flutter Engine
    FlutterEngine["Flutter Engine"]:::external

    %% Flutter Application
    subgraph "Flutter Application"
        %% Core
        ServiceLocator["Service Locator\n(GetIt)"]:::di
        click ServiceLocator "https://github.com/mohamad-amen/peeko/blob/main/lib/core/service_locator.dart"
        CoreThemes["Core Themes"]:::presentation
        click CoreThemes "https://github.com/mohamad-amen/peeko/blob/main/lib/core/themes.dart"

        %% Navigation Layer
        AppRouter["GoRouter\n(app_router.dart)"]:::di
        click AppRouter "https://github.com/mohamad-amen/peeko/blob/main/lib/core/app_router.dart"

        %% Presentation Layer
        subgraph "Presentation Layer"
            VideoFeedPage["VideoFeedPage"]:::presentation
            click VideoFeedPage "https://github.com/mohamad-amen/peeko/blob/main/lib/features/videos/pages/video_feed_page.dart"
            VideoPreview["VideoPreview"]:::presentation
            click VideoPreview "https://github.com/mohamad-amen/peeko/blob/main/lib/features/videos/pages/video_preview.dart"
            AuthPage["AuthPage"]:::presentation
            click AuthPage "https://github.com/mohamad-amen/peeko/blob/main/lib/features/auth/pages/auth_page.dart"
            ActivationPage["ActivationPage"]:::presentation
            click ActivationPage "https://github.com/mohamad-amen/peeko/blob/main/lib/features/auth/pages/activation_page.dart"
            CommentsSection["CommentsSection"]:::presentation
            click CommentsSection "https://github.com/mohamad-amen/peeko/blob/main/lib/features/comments/widgets/comments_section.dart"
            ProfilePage["ProfilePage"]:::presentation
            click ProfilePage "https://github.com/mohamad-amen/peeko/blob/main/lib/features/profile/pages/profile_page.dart"
        end

        %% State Management
        subgraph "State Management (Providers)"
            VideosProvider["VideosProvider"]:::logic
            click VideosProvider "https://github.com/mohamad-amen/peeko/blob/main/lib/features/videos/providers/videos_provider.dart"
            ProfileProvider["ProfileProvider"]:::logic
            click ProfileProvider "https://github.com/mohamad-amen/peeko/blob/main/lib/features/profile/provider/profile_provider.dart"
        end

        %% Service Layer
        subgraph "Service Layer"
            ApiService["ApiService"]:::services
            click ApiService "https://github.com/mohamad-amen/peeko/blob/main/lib/core/services/api_service.dart"
            LocalStorageService["LocalStorageService"]:::services
            click LocalStorageService "https://github.com/mohamad-amen/peeko/blob/main/lib/core/services/local_storage_service.dart"
            AuthService["AuthService"]:::services
            click AuthService "https://github.com/mohamad-amen/peeko/blob/main/lib/features/auth/services/auth_service.dart"
            DeviceInfoService["DeviceInfoService"]:::services
            click DeviceInfoService "https://github.com/mohamad-amen/peeko/blob/main/lib/features/auth/services/device_info_service.dart"
            MediaService["MediaService"]:::services
            click MediaService "https://github.com/mohamad-amen/peeko/blob/main/lib/features/videos/services/media_service.dart"
        end

        %% Data Models
        subgraph "Data Models"
            VideoModel["VideoModel"]:::services
            click VideoModel "https://github.com/mohamad-amen/peeko/blob/main/lib/features/videos/models/video_model.dart"
            CommentModel["CommentModel"]:::services
            click CommentModel "https://github.com/mohamad-amen/peeko/blob/main/lib/features/comments/models/comment_model.dart"
            UserModel["UserModel"]:::services
            click UserModel "https://github.com/mohamad-amen/peeko/blob/main/lib/features/profile/models/user_model.dart"
        end
    end

    %% External Backends
    ExternalAPI["MERN Backend API\n(auth, videos, comments, profiles)"]:::external
    CDN["CDN / Video Storage"]:::external

    %% Connections
    MobileOS --> FlutterEngine
    FlutterEngine --> ServiceLocator

    ServiceLocator --> AppRouter
    ServiceLocator --> ApiService
    ServiceLocator --> LocalStorageService
    ServiceLocator --> AuthService
    ServiceLocator --> DeviceInfoService
    ServiceLocator --> MediaService

    AppRouter --> VideoFeedPage
    AppRouter --> VideoPreview
    AppRouter --> AuthPage
    AppRouter --> ActivationPage
    AppRouter --> ProfilePage
    AppRouter --> CommentsSection

    VideoFeedPage --> VideosProvider
    VideosProvider --> MediaService
    MediaService --> ApiService
    ApiService --> ExternalAPI
    MediaService --> CDN
    VideosProvider --> VideoModel

    AuthPage --> AuthService
    ActivationPage --> AuthService
    AuthService --> LocalStorageService
    AuthService --> ApiService
    ApiService --> ExternalAPI
    AuthService --> DeviceInfoService

    ProfilePage --> ProfileProvider
    ProfileProvider --> ApiService
    ApiService --> ExternalAPI
    ProfileProvider --> UserModel

    CommentsSection --> ApiService
    ApiService --> ExternalAPI
    CommentsSection --> CommentModel

    %% Styling
    classDef presentation fill:#D0E8FF,stroke:#0288D1,stroke-width:1px
    classDef logic fill:#DFFFD6,stroke:#388E3C,stroke-width:1px
    classDef services fill:#FFF9C4,stroke:#FBC02D,stroke-width:1px
    classDef external fill:#ECEFF1,stroke:#607D8B,stroke-width:1px
    classDef di fill:#F3E5F5,stroke:#8E24AA,stroke-width:1px
```
