# ironmax123/flutterjr-hackathon architecture

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

- Interactive diagram: https://gitdiagram.com/ironmax123/flutterjr-hackathon
- Repository: https://github.com/ironmax123/flutterjr-hackathon

## Overview

##### Project Type and Purpose
- This is a Flutter mobile application (with Android, iOS, and web targets) primarily built around a social or communication theme. Its functionality includes a home screen with a timer and camera for auto-posting, an invitation screen for friend management (including QR code and SNS sharing), and sections for viewing friends’ posts and personal timelines.
- The README explicitly mentions using an MVVM pattern combined with a repository abstraction, with additional hints toward a separation of concerns, making it a full-stack (or rather fully layered mobile) application.

##### Major Components
a. User Interface / Presentation Layer:
- All the UI components are grouped under lib/feature and lib/primary. For example, the home view, invitation view, login, posts view, etc.

b. MVVM (ViewModel) Layer:
- For each feature, there is a “vm” file (e.g., home/vm.dart, invitation/vm.dart, posts/vm.dart) that handles the business logic/state management. This is a crucial component that links the UI with the data sources.
- Connection from each UI component to its corresponding ViewModel(s).

c. Repository / Data Layer:
- Under lib/repository and lib/data, the project defines data structures and repositories for entities (friend, post, sample, user) using code generation (notice “entity.freezed.dart” and “entity.g.dart”).
- This layer as the abstraction that interacts with the underlying data stores.

d. Service Layer:
- The service folder (lib/service) shows services corresponding to each domain (friends, post, sample, user) which likely implement business rules and network logic.
- This layer fetches or updates data by communicating with repositories or external APIs.

e. Backend / External Services:
- Although the backend is “hidden” from a code perspective, the README and file tree (lib/supabase) indicate usage of the Supabase backend service.

f. Additional Components:
- Routing: lib/routers/router.dart uses go_router, indicating central management of navigation between screens.
- Cross-cutting concerns like state management (via riverpod, flutter_hooks) and asynchronous functionalities (e.g., timers, audio playback using just_audio) should be highlighted.
- Utility functions are bundled under lib/primary/utils and lib/utils.

##### Relationships and Data Flow
- How the UI components communicate with the ViewModels (using state management libraries like Riverpod and flutter_hooks), which in turn interact with the repository layer.
- That the repository abstracts away data sources and might interact with local data (entities in lib/data) and the external backend via Supabase.
- Routing mechanism that connects various screens.
- Dependency on external packages (camera, QR code, audio) as auxiliary modules integrated into the UI or service layer.

##### Architectural Patterns and Design Principles
- MVVM pattern, showing the direction of data flow: UI (View) → ViewModel → Repository/Service → External Backend.
- That the repository pattern is used to decouple the data sources from business logic.
- Code generation practices (using Freezed, Riverpod Generator, etc.), which help keep the data and state model defined and immutable.
- Modularization of features based on the directory structure (each feature has its own components and view models).

## Diagram (Mermaid)

```mermaid
graph TD
    %% User Interface / Presentation Layer
    subgraph "User Interface / Presentation Layer"
        HS["Home Screen"]:::ui
        HC["Home Components"]:::ui
        IS["Invitation Screen"]:::ui
        IC["Invitation Components"]:::ui
        ISS["Invitation Scan"]:::ui
        LP["Login Page"]:::ui
        LL["Login Logic"]:::ui
        LW["Login Widgets"]:::ui
        PS["Posts Screen"]:::ui
        PC["Posts Components"]:::ui
        SUS["Sign Up Page"]:::ui
        SUL["Sign Up Logic"]:::ui
        SUW["Sign Up Widgets"]:::ui
        PT["Personal Timeline"]:::ui
        TC["Timeline Components"]:::ui
        CUC["Common UI Components"]:::ui
    end

    %% MVVM (ViewModel) Layer
    subgraph "MVVM (ViewModel) Layer"
        HVM["Home VM"]:::vm
        IVM["Invitation VM"]:::vm
        PVM["Posts VM"]:::vm
        SUMVM["Sign Up VM"]:::vm
        UPVM["Userposts VM"]:::vm
        SVM["Sample VM"]:::vm
    end

    %% Repository / Data Layer
    subgraph "Repository / Data Layer"
        DE["Data Entities"]:::repo
        FREPO["Friends Repo"]:::repo
        PREPO["Post Repo"]:::repo
        SREPO["Sample Repo"]:::repo
        UREPO["User Repo"]:::repo
    end

    %% Service Layer
    subgraph "Service Layer"
        FS["Friends Service"]:::service
        PSVC["Post Service"]:::service
        SSVC["Sample Service"]:::service
        USVC["User Service"]:::service
    end

    %% Backend / External Service
    subgraph "Backend / External Service"
        SBI["Supabase Integration"]:::backend
        SBP["Supabase Provider"]:::backend
    end

    %% Routing
    subgraph "Routing"
        RR["Router"]:::router
    end

    %% Utilities
    subgraph "Utilities"
        PU["Primary Utilities"]:::utility
        AU["Additional Utilities"]:::utility
    end

    %% Connections: UI to MVVM
    HS -->|"bound to"| HVM
    IS -->|"bound to"| IVM
    PS -->|"bound to"| PVM
    SUS -->|"bound to"| SUMVM
    PT -->|"bound to"| UPVM

    %% Connections: MVVM to Repository
    HVM -->|"uses"| FREPO
    IVM -->|"uses"| FREPO
    PVM -->|"uses"| PREPO
    SUMVM -->|"uses"| UREPO
    UPVM -->|"uses"| UREPO
    SVM -->|"uses"| SREPO

    %% Connections: MVVM to Service Layer
    HVM -->|"calls"| FS
    IVM -->|"calls"| FS
    PVM -->|"calls"| PSVC
    SUMVM -->|"calls"| USVC
    UPVM -->|"calls"| USVC
    SVM -->|"calls"| SSVC

    %% Repository to Data Entities
    FREPO -->|"based on"| DE
    PREPO -->|"based on"| DE
    SREPO -->|"based on"| DE
    UREPO -->|"based on"| DE

    %% Service Layer to Backend
    FS -->|"integrates with"| SBI
    PSVC -->|"integrates with"| SBI
    SSVC -->|"integrates with"| SBI
    USVC -->|"integrates with"| SBI

    %% Additional Backend Connection
    SBP -->|"provides"| SBI

    %% Routing to UI Screens
    RR --- HS
    RR --- IS
    RR --- LP
    RR --- PS
    RR --- SUS
    RR --- PT

    %% Utilities used in UI and others
    PU --- CUC
    AU --- LP

    %% Click Events for UI Layer
    click HS "https://github.com/ironmax123/flutterjr-hackathon/blob/main/lib/feature/home/view.dart"
    click HC "https://github.com/ironmax123/flutterjr-hackathon/tree/main/lib/feature/home/components"
    click IS "https://github.com/ironmax123/flutterjr-hackathon/blob/main/lib/feature/invitation/view.dart"
    click IC "https://github.com/ironmax123/flutterjr-hackathon/tree/main/lib/feature/invitation/components"
    click ISS "https://github.com/ironmax123/flutterjr-hackathon/tree/main/lib/feature/invitation/scan"
    click LP "https://github.com/ironmax123/flutterjr-hackathon/blob/main/lib/feature/login/page.dart"
    click LL "https://github.com/ironmax123/flutterjr-hackathon/blob/main/lib/feature/login/login.dart"
    click LW "https://github.com/ironmax123/flutterjr-hackathon/tree/main/lib/feature/login/widgets"
    click PS "https://github.com/ironmax123/flutterjr-hackathon/blob/main/lib/feature/posts/view.dart"
    click PC "https://github.com/ironmax123/flutterjr-hackathon/tree/main/lib/feature/posts/components"
    click SUS "https://github.com/ironmax123/flutterjr-hackathon/blob/main/lib/feature/sign_up/page.dart"
    click SUL "https://github.com/ironmax123/flutterjr-hackathon/blob/main/lib/feature/sign_up/sign_up.dart"
    click SUW "https://github.com/ironmax123/flutterjr-hackathon/tree/main/lib/feature/sign_up/widgets"
    click PT "https://github.com/ironmax123/flutterjr-hackathon/blob/main/lib/feature/userposts/view.dart"
    click TC "https://github.com/ironmax123/flutterjr-hackathon/tree/main/lib/feature/userposts/components"
    click CUC "https://github.com/ironmax123/flutterjr-hackathon/tree/main/lib/primary/components"

    %% Click Events for MVVM Layer
    click HVM "https://github.com/ironmax123/flutterjr-hackathon/blob/main/lib/feature/home/vm.dart"
    click IVM "https://github.com/ironmax123/flutterjr-hackathon/blob/main/lib/feature/invitation/vm.dart"
    click PVM "https://github.com/ironmax123/flutterjr-hackathon/blob/main/lib/feature/posts/vm.dart"
    click SUMVM "https://github.com/ironmax123/flutterjr-hackathon/blob/main/lib/feature/sign_up/vm.dart"
    click UPVM "https://github.com/ironmax123/flutterjr-hackathon/blob/main/lib/feature/userposts/vm.dart"
    click SVM "https://github.com/ironmax123/flutterjr-hackathon/blob/main/lib/feature/sample/vm.dart"

    %% Click Events for Repository / Data Layer
    click DE "https://github.com/ironmax123/flutterjr-hackathon/tree/main/lib/data"
    click FREPO "https://github.com/ironmax123/flutterjr-hackathon/blob/main/lib/repository/friends/repository.dart"
    click PREPO "https://github.com/ironmax123/flutterjr-hackathon/blob/main/lib/repository/post/repository.dart"
    click SREPO "https://github.com/ironmax123/flutterjr-hackathon/blob/main/lib/repository/sample/repository.dart"
    click UREPO "https://github.com/ironmax123/flutterjr-hackathon/blob/main/lib/repository/user/repository.dart"

    %% Click Events for Service Layer
    click FS "https://github.com/ironmax123/flutterjr-hackathon/blob/main/lib/service/friends/service.dart"
    click PSVC "https://github.com/ironmax123/flutterjr-hackathon/blob/main/lib/service/post/service.dart"
    click SSVC "https://github.com/ironmax123/flutterjr-hackathon/blob/main/lib/service/sample/service.dart"
    click USVC "https://github.com/ironmax123/flutterjr-hackathon/blob/main/lib/service/user/service.dart"

    %% Click Events for Backend / External Service
    click SBI "https://github.com/ironmax123/flutterjr-hackathon/blob/main/lib/supabase/supabase.dart"
    click SBP "https://github.com/ironmax123/flutterjr-hackathon/blob/main/lib/supabase/provider.dart"

    %% Click Event for Routing
    click RR "https://github.com/ironmax123/flutterjr-hackathon/blob/main/lib/routers/router.dart"

    %% Click Events for Utilities
    click PU "https://github.com/ironmax123/flutterjr-hackathon/tree/main/lib/primary/utils"
    click AU "https://github.com/ironmax123/flutterjr-hackathon/tree/main/lib/utils"

    %% Styles
    classDef ui fill:#AEDFF7,stroke:#000,stroke-width:2px;
    classDef vm fill:#C6F7C3,stroke:#000,stroke-width:2px;
    classDef repo fill:#FFF5BA,stroke:#000,stroke-width:2px;
    classDef service fill:#FFD5B5,stroke:#000,stroke-width:2px;
    classDef backend fill:#EED2FF,stroke:#000,stroke-width:2px;
    classDef router fill:#D3F9D8,stroke:#000,stroke-width:2px;
    classDef utility fill:#D0E8F2,stroke:#000,stroke-width:2px;
```
