# rubberduckcrew/gitdone architecture

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

- Interactive diagram: https://gitdiagram.com/rubberduckcrew/gitdone
- Repository: https://github.com/rubberduckcrew/gitdone

## Overview

##### Project type and purpose
- GitDone is a **Flutter-based Android mobile app** whose sole responsibility is to let users authenticate with GitHub (OAuth) and convert to-dos into GitHub issues by talking directly to the GitHub REST API.
- It is a **client-only** application (no custom backend), structured around Flutter’s standard folder layout and following an **MVVM-style separation** of UI, view-models, and core services.

##### File structure
- Top-level directories:
- **android/**: native Android app wrapper and Gradle build files.
- **lib/**: all Dart code, subdivided into:
– **app.dart / main.dart**: app entrypoint and configuration.
– **core/**: domain & infrastructure (API handler, models, token management, theme, utilities).
– **ui/**: presentation layer (screens, widgets, view-models) organized by feature (welcome, login, home, settings).
- Patterns: MVVM in **ui/** (screen ⇄ view-model), layered core services for API calls and token management.

##### Pulling additional insights from README
- Key features: GitHub OAuth, issue management (sync planned).
- Roadmap indicates future syncing, but current focus is on OAuth flow and issue creation.
- Tech stack: Flutter & Dart on Android, HTTP REST client to GitHub, standard Flutter widgets.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Configuration & Entrypoint
    subgraph "Configuration & Entrypoint"
        Main["main.dart"]:::config
        App["app.dart"]:::config
        Config["app_config.dart"]:::config
    end

    %% UI Layer
    subgraph "UI Layer"
        Welcome["Welcome Screen"]:::ui
        LoginOAuthScreen["Login OAuth Screen"]:::ui
        LoginTokenView["Login Token Screen"]:::ui
        HomeScreen["Home Screen"]:::ui
        SettingsView["Settings Screen"]:::ui
        SharedAppBar["App Bar"]:::ui
        SharedAppTitle["App Title"]:::ui
        SharedOctoCat["Octo Cat"]:::ui
        SharedPageTitle["Page Title"]:::ui
        SharedTextLink["Text Link"]:::ui
    end

    %% ViewModel Layer
    subgraph "ViewModel Layer"
        LoginOAuthVM["Login OAuth ViewModel"]:::vm
        LoginTokenVM["Login Token ViewModel"]:::vm
        HomeVM["Home Screen ViewModel"]:::vm
    end

    %% Core Services & Models
    subgraph "Domain/Service Layer"
        APIHandler["GitHub API Handler"]:::service
        OAuthModel["GitHub OAuth Model"]:::service
        TokenHandler["Token Handler"]:::service
        Logger["Logger & Utilities"]:::service
        ThemeConfig["App Color Theme"]:::service
    end

    %% External Services
    subgraph "External APIs"
        GitHubOAuth["GitHub OAuth Server"]:::external
        GitHubAPI["GitHub REST API"]:::external
    end

    %% Relationships
    Main -->|initializes| App
    App -->|loads config| Config
    App -->|renders| Welcome

    Welcome -->|navigate| LoginOAuthScreen
    LoginOAuthScreen -->|user action| LoginOAuthVM
    LoginOAuthVM -->|request token| OAuthModel
    OAuthModel -->|OAuth flow| GitHubOAuth
    GitHubOAuth -->|returns code| OAuthModel
    OAuthModel -->|provides token| TokenHandler
    TokenHandler -->|stores token| LoginOAuthVM
    LoginOAuthVM -->|navigate| LoginTokenView

    LoginTokenView -->|input token| LoginTokenVM
    LoginTokenVM -->|validate| TokenHandler
    TokenHandler -->|confirmed| LoginTokenVM
    LoginTokenVM -->|navigate| HomeScreen

    HomeScreen -->|render| HomeVM
    HomeVM -->|fetch issues| APIHandler
    APIHandler -->|GET /issues| GitHubAPI
    GitHubAPI -->|issue data| APIHandler
    APIHandler -->|map to models| HomeVM
    HomeVM -->|update UI| HomeScreen

    HomeScreen -->|navigate| SettingsView

    %% Shared Widgets usage
    Welcome --> SharedAppTitle
    LoginOAuthScreen --> SharedAppBar
    LoginTokenView --> SharedPageTitle
    HomeScreen --> SharedOctoCat
    SettingsView --> SharedTextLink

    %% Click Events
    click Welcome "https://github.com/rubberduckcrew/gitdone/blob/main/lib/ui/welcome/welcome_view.dart"
    click LoginOAuthScreen "https://github.com/rubberduckcrew/gitdone/blob/main/lib/ui/login/oauth/login_oauth_screen.dart"
    click LoginOAuthVM "https://github.com/rubberduckcrew/gitdone/blob/main/lib/ui/login/oauth/login_oauth_view_model.dart"
    click OAuthModel "https://github.com/rubberduckcrew/gitdone/blob/main/lib/core/models/github_oauth_model.dart"
    click TokenHandler "https://github.com/rubberduckcrew/gitdone/blob/main/lib/core/models/token_handler.dart"
    click APIHandler "https://github.com/rubberduckcrew/gitdone/blob/main/lib/core/github_api_handler.dart"
    click LoginTokenView "https://github.com/rubberduckcrew/gitdone/blob/main/lib/ui/login/token/login_token_view.dart"
    click HomeScreen "https://github.com/rubberduckcrew/gitdone/blob/main/lib/ui/home/home_screen.dart"
    click HomeVM "https://github.com/rubberduckcrew/gitdone/blob/main/lib/ui/home/home_screen_view_model.dart"
    click SettingsView "https://github.com/rubberduckcrew/gitdone/blob/main/lib/ui/settings/settings_view.dart"
    click SharedAppBar "https://github.com/rubberduckcrew/gitdone/blob/main/lib/ui/_widgets/app_bar.dart"
    click SharedAppTitle "https://github.com/rubberduckcrew/gitdone/blob/main/lib/ui/_widgets/app_title.dart"
    click SharedOctoCat "https://github.com/rubberduckcrew/gitdone/blob/main/lib/ui/_widgets/octo_cat.dart"
    click SharedPageTitle "https://github.com/rubberduckcrew/gitdone/blob/main/lib/ui/_widgets/page_title.dart"
    click SharedTextLink "https://github.com/rubberduckcrew/gitdone/blob/main/lib/ui/_widgets/text_link.dart"
    click Main "https://github.com/rubberduckcrew/gitdone/blob/main/lib/main.dart"
    click App "https://github.com/rubberduckcrew/gitdone/blob/main/lib/app.dart"
    click Config "https://github.com/rubberduckcrew/gitdone/blob/main/lib/app_config.dart"
    click ThemeConfig "https://github.com/rubberduckcrew/gitdone/blob/main/lib/core/theme/app_color.dart"
    click Logger "https://github.com/rubberduckcrew/gitdone/blob/main/lib/core/utils/logger.dart"
    click GitHubOAuth "https://github.com/rubberduckcrew/gitdone/tree/main/external"
    click GitHubAPI "https://github.com/rubberduckcrew/gitdone/tree/main/external"

    %% Styles
    classDef ui fill:#cfe2f3,stroke:#2a64a8,color:#000;
    classDef vm fill:#d9ead3,stroke:#38761d,color:#000;
    classDef service fill:#fff2cc,stroke:#b45f06,color:#000;
    classDef config fill:#d9d9d9,stroke:#636363,color:#000;
    classDef external fill:#eeeeee,stroke:#666666,stroke-dasharray: 5 5,color:#000;
```
