# nguyenminhduc163/card-mind architecture

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

- Interactive diagram: https://gitdiagram.com/nguyenminhduc163/card-mind
- Repository: https://github.com/nguyenminhduc163/card-mind

## Overview

##### Main Components
a. Presentation (UI) Layer
- Flutter widgets & screens under lib/modules/**
- Common widgets under lib/common/**
- Entry points: lib/main.dart, lib/main_preview.dart
b. State Management Layer
- Notifiers under lib/providers/provider_setup.dart & lib/modules/**/**_notifier.dart
- theme_cubit.dart (in lib/core/theme)
c. Domain/Core Layer
- Business-rules & app-wide services in lib/core/**
- NavigationService, EventService, Authentication, Debouncer, etc.
d. Data Layer
- API client, interceptors, secure storage in lib/data/**
- Services: auth_service.dart, connectivity_service.dart, course_service.dart, etc.
- Models (DTOs) under lib/data/models/**
e. Persistence & Cache
- Local: Hive DB, Flutter Secure Storage (lib/data/secure_storage.dart)
- In-memory cache: in_memory_cache_client.dart
f. External Services
- Firebase (Auth, Firestore)
- Google Sign-In
- Chatbot AI (external API)
- Connectivity check
g. Platform Runners
- Android (android/…)
- iOS (ios/…)
- Linux (linux/…)
- Web (web/…)

##### Relationships & Data Flow
- User interacts with Presentation → triggers State Management (Notifier/Cubit)
- Notifier invokes Domain/Core services (e.g., Authentication, EventService)
- Core services call Data Layer APIs or local storage helpers
- Data Layer → HTTP calls (Dio) to Firebase or Chatbot API, interceptors handle tokens, logging
- Responses → mapped to domain models → returned up to Notifier → UI widget renders
- Caching layer (Hive/In-memory) sits between Data Layer & External Services to optimize fetches

##### Architectural Patterns
- Clean Architecture (layers depend inward only)
- Provider/BLoC for state management
- Dependency-injection via provider_setup.dart
- Repositories (services implement interfaces)
- Separation of concerns: UI vs. domain vs. data vs. infra

##### Technologies & Frameworks to annotate
- Flutter & Dart
- Provider / Riverpod (or plain Provider)
- Hive / Secure Storage (local persistence)
- Firebase Auth / Firestore (cloud persistence)
- Dio + Interceptors (network client)
- Easy Localization (i18n)
- Material 3 / Shimmer / FlipCard animations

##### Essential Elements
- Clear labels: “UI: Course Screens”, “Notifier: CourseInfoNotifier”, “Service: CourseService”

## Diagram (Mermaid)

```mermaid
graph TD
    %% Platform Runners
    subgraph "Platform Runners"
        Android["android/"]:::platform
        IOS["ios/"]:::platform
        Linux["linux/"]:::platform
        WebRunner["web/"]:::platform
    end

    %% UI Layer
    subgraph "UI (Presentation) Layer"
        Main["main.dart"]:::ui
        MainPreview["main_preview.dart"]:::ui
        Widgets["common/widgets"]:::ui
        Modules["modules"]:::ui
    end

    %% State Management Layer
    subgraph "State Management Layer"
        ProviderSetup["provider_setup.dart"]:::state
        Notifiers["**_notifier.dart"]:::state
        ThemeCubit["theme_cubit.dart"]:::state
    end

    %% Domain/Core Layer
    subgraph "Domain/Core Layer"
        AppAuth["app_authentication.dart"]:::core
        EventService["event_service.dart"]:::core
        NavigationService["navigation_service.dart"]:::core
        Debouncer["debouncer.dart"]:::core
        DataMgmtService["data_management_service.dart"]:::core
        Constants["constants"]:::core
    end

    %% Data Layer
    subgraph "Data Layer"
        APIClient["api_client.dart"]:::data
        TokenInterceptor["api_token_interceptor.dart"]:::data
        LogInterceptor["log_interceptor.dart"]:::data
        DataServices["services"]:::data
        Models["models"]:::data
    end

    %% Persistence & Cache
    subgraph "Persistence & Cache"
        SecureStorage["secure_storage.dart"]:::persistence
        InMemoryCache["in_memory_cache_client.dart"]:::persistence
        HiveDB["Hive DB"]:::persistence
    end

    %% External Services
    subgraph "External Services"
        Firebase["Firebase Auth / Firestore"]:::external
        GoogleSignIn["Google Sign-In"]:::external
        ChatbotAPI["Chatbot AI API"]:::external
        Connectivity["Connectivity Check"]:::external
    end

    %% Flow
    Android -->|runs| Main
    IOS -->|runs| Main
    Linux -->|runs| Main
    WebRunner -->|runs| MainPreview

    Main -->|renders UI| Widgets
    Main -->|renders UI| Modules
    Widgets -->|uses| Notifiers
    Modules -->|uses| Notifiers

    Notifiers -->|calls| AppAuth
    Notifiers -->|calls| EventService
    Notifiers -->|calls| DataMgmtService
    ThemeCubit -->|provides| Widgets

    AppAuth -->|depends on| APIClient
    EventService -->|depends on| APIClient
    NavigationService -->|injected into| Widgets
    DataMgmtService -->|depends on| SecureStorage

    APIClient -->|intercepts requests| TokenInterceptor
    APIClient -->|logs requests| LogInterceptor
    APIClient -->|calls| Firebase
    APIClient -->|calls| ChatbotAPI

    DataServices -->|uses| APIClient
    DataServices -->|uses| Connectivity
    DataServices -->|persists| SecureStorage
    DataServices -->|caches| InMemoryCache
    Models -->|used by| DataServices

    SecureStorage -->|stores tokens| APIClient
    InMemoryCache -->|caches responses| DataServices

    Firebase -->|authenticates| AppAuth
    Firebase -->|stores data| DataServices
    GoogleSignIn -->|auth flow| AppAuth
    ChatbotAPI -->|provides AI| Modules

    %% Click Events
    click Main "https://github.com/nguyenminhduc163/card-mind/blob/main/lib/main.dart"
    click MainPreview "https://github.com/nguyenminhduc163/card-mind/blob/main/lib/main_preview.dart"
    click Widgets "https://github.com/nguyenminhduc163/card-mind/tree/main/lib/common/widgets"
    click Modules "https://github.com/nguyenminhduc163/card-mind/tree/main/lib/modules"
    click ProviderSetup "https://github.com/nguyenminhduc163/card-mind/blob/main/lib/providers/provider_setup.dart"
    click Notifiers "https://github.com/nguyenminhduc163/card-mind/blob/main/lib/modules/course/provider/course_info_notifier.dart"
    click ThemeCubit "https://github.com/nguyenminhduc163/card-mind/blob/main/lib/core/theme/theme_cubit.dart"
    click AppAuth "https://github.com/nguyenminhduc163/card-mind/blob/main/lib/core/app_authentication.dart"
    click EventService "https://github.com/nguyenminhduc163/card-mind/blob/main/lib/core/event_service.dart"
    click NavigationService "https://github.com/nguyenminhduc163/card-mind/blob/main/lib/core/public/navigation_service.dart"
    click Debouncer "https://github.com/nguyenminhduc163/card-mind/blob/main/lib/core/debouncer.dart"
    click DataMgmtService "https://github.com/nguyenminhduc163/card-mind/blob/main/lib/core/services/data_management_service.dart"
    click Constants "https://github.com/nguyenminhduc163/card-mind/tree/main/lib/core/constants"
    click APIClient "https://github.com/nguyenminhduc163/card-mind/blob/main/lib/data/api_client.dart"
    click TokenInterceptor "https://github.com/nguyenminhduc163/card-mind/blob/main/lib/data/interceptors/api_token_interceptor.dart"
    click LogInterceptor "https://github.com/nguyenminhduc163/card-mind/blob/main/lib/data/interceptors/log_interceptor.dart"
    click DataServices "https://github.com/nguyenminhduc163/card-mind/blob/main/lib/data/services/auth_service.dart"
    click Models "https://github.com/nguyenminhduc163/card-mind/tree/main/lib/data/models"
    click SecureStorage "https://github.com/nguyenminhduc163/card-mind/blob/main/lib/data/secure_storage.dart"
    click InMemoryCache "https://github.com/nguyenminhduc163/card-mind/blob/main/lib/data/in_memory_cache_client.dart"
    click Firebase "https://github.com/nguyenminhduc163/card-mind/blob/main/lib/firebase_options.dart"
    click Connectivity "https://github.com/nguyenminhduc163/card-mind/blob/main/lib/data/services/connectivity_service.dart"
    click ChatbotAPI "https://github.com/nguyenminhduc163/card-mind/blob/main/lib/modules/message/services/chat_bot_service.dart"

    %% Styles
    classDef ui fill:#cce5ff,stroke:#333,stroke-width:1px
    classDef state fill:#d4edda,stroke:#333,stroke-width:1px
    classDef core fill:#d4edda,stroke:#333,stroke-width:1px
    classDef data fill:#ffe5b4,stroke:#333,stroke-width:1px
    classDef persistence fill:#ffe5b4,stroke:#333,stroke-width:1px
    classDef external fill:#f8d7da,stroke:#333,stroke-width:1px
    classDef platform fill:#e2e3e5,stroke:#333,stroke-width:1px
```
