# goatt69/cardholder architecture

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

- Interactive diagram: https://gitdiagram.com/goatt69/cardholder
- Repository: https://github.com/goatt69/cardholder

## Overview

##### Project Type & Purpose
- This is a Flutter mobile (and web) application, built as a starting point for a card holder app (“Đồ án nhóm 6”).
- The project supports multiple screens including login, home, admin, collection, and trade – indicating it handles user authentication, card collection, and card trading functions.
- While the backend is not explicitly bundled (no dedicated server code), the “services” under lib/services suggest the app calls external APIs or services, likely over the internet.
- There is native Android configuration available under the “android” directory and a “web” folder for web deployment.

##### Analyzing the File Structure
- Top-level directories:
- "android": Contains native Android configuration and build scripts (AndroidManifest.xml, gradle, etc.) needed by Flutter for Android builds.
- "lib": The heart of the Flutter app. It comprises:
- "screen": All the UI pages (e.g., login_page, home_page, account_screen, admin pages, OCR screen, etc.).
- "model": Contains domain models (CardHolder, NewsPosts, OfferedCard, PokeCard, etc.) which represent the data structures.
- "services": Houses API client logic and various service classes (auth_service, card_service, etc.) that handle business logic and backend communication.
- "config": For configuration settings (such as config_url.dart) and "utils" for helper functions.
- "widget"/"widgets": Custom reusable UI components.
- "test": Contains tests, likely for UI behavior.
- "web": Contains the entry points for web integration.
- Configuration/build files (pubspec.yaml, gradle scripts) provide further context on the technology stack and dependency management.

##### Key Components
a. Presentation (UI) Layer:
- Components: All screens from lib/screen and custom widgets from lib/widget(s).
- Role: User-facing interface for login, collection management, admin activities, etc.
b. Business Logic and Data Access Layer:
- Components: Services found in lib/services; they act as the intermediary between UI and data/data models.
- Role: Handle API calls (via the api_client.dart), authentication (auth_service.dart), card management, and other operations.
c. Data Model Layer:
- Components: Models (e.g., CardHolder, NewsPosts, TradeOffer, UserModel, etc.) under lib/model.
- Role: Define the data structure used across the app and to interact with service responses.
d. Configuration & Utility Layer:
- Components: lib/config (for settings like URLs/endpoint configuration) and lib/utils (helpers such as authentication utilities).
- Role: Provide centralized configuration and reusable common functionalities.
e. Native Bridge & Deployment:
- Components: The “android” directory (for Android-specific build configuration) and “web” directory (for browser-based hosting).
- Role: Support platform-specific integrations required by Flutter.

##### Relationships & Interactions
- The UI screens (presentation layer) trigger user actions, which are then forwarded to the services layer.
- The services layer processes these actions (e.g., making API calls using api_client.dart) and uses models to encapsulate data.
- On receiving data, UI components update accordingly.
- Configuration and utilities provide support across layers.
- Deployment sub-systems (Android and Web) tie into the main Flutter code base for respective platform packaging and distribution.

##### Architectural Patterns and Design Principles
- The structure follows an MVC or MVVM-like paradigm where the models handle data, services encapsulate business logic and API interactions, and screens represent the view.
- Clear separation of concerns exists between UI (screens/widgets), business logic/services, and data models.
- Reusability by maintaining custom widgets and utility functions separately.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Top-level User
    User["User"]:::user

    %% Presentation Layer Subgraph
    subgraph "Presentation Layer"
        UI_Screens["UI Screens"]:::presentation
        Widgets1["Custom Widget"]:::presentation
        Widgets2["Custom Widgets"]:::presentation
    end

    %% Business Logic & Services Layer Subgraph
    subgraph "Business Logic & Services Layer"
        API_Client["API Client"]:::services
        Auth_Service["Auth Service"]:::services
        Card_Service["Card Service"]:::services
        Collection_Service["Collection Card Service"]:::services
        NewsPost_Service["NewsPost Service"]:::services
        Pokemon_Service["Pokemon Service"]:::services
        Pokepost_Service["Pokepost Service"]:::services
    end

    %% Data Model Layer Subgraph
    subgraph "Data Model Layer"
        Data_Models["Data Models"]:::models
    end

    %% Configuration & Utils Layer Subgraph
    subgraph "Configuration & Utils Layer"
        Config["Configuration"]:::config
        Utils["Utilities"]:::config
    end

    %% Native Bridge & Deployment Subgraph
    subgraph "Native Bridge & Deployment"
        Android["Android"]:::native
        Web["Web"]:::native
    end

    %% Relationships and Data Flow
    User -->|"triggers"| UI_Screens
    UI_Screens -->|"uses"| Widgets1
    UI_Screens -->|"uses"| Widgets2
    UI_Screens -->|"calls"| API_Client
    UI_Screens -->|"calls"| Auth_Service
    UI_Screens -->|"calls"| Card_Service

    API_Client -->|"feeds"| Auth_Service
    API_Client -->|"feeds"| Card_Service
    API_Client -->|"feeds"| Collection_Service
    API_Client -->|"feeds"| NewsPost_Service
    API_Client -->|"feeds"| Pokemon_Service
    API_Client -->|"feeds"| Pokepost_Service

    Auth_Service -->|"processes"| Data_Models
    Card_Service -->|"processes"| Data_Models
    Collection_Service -->|"processes"| Data_Models
    NewsPost_Service -->|"processes"| Data_Models
    Pokemon_Service -->|"processes"| Data_Models
    Pokepost_Service -->|"processes"| Data_Models

    Config -->|"supports"| Auth_Service
    Config -->|"supports"| Card_Service
    Utils -->|"assists"| Auth_Service
    Utils -->|"assists"| UI_Screens

    %% Deployment arrows from the app to native platforms
    UI_Screens -->|"deployed_on"| Android
    UI_Screens -->|"deployed_on"| Web

    %% Click Events
    click UI_Screens "https://github.com/goatt69/cardholder/tree/master/lib/screen"
    click Widgets1 "https://github.com/goatt69/cardholder/tree/master/lib/widget"
    click Widgets2 "https://github.com/goatt69/cardholder/tree/master/lib/widgets"
    click API_Client "https://github.com/goatt69/cardholder/blob/master/lib/services/api_client.dart"
    click Auth_Service "https://github.com/goatt69/cardholder/blob/master/lib/services/auth_service.dart"
    click Card_Service "https://github.com/goatt69/cardholder/blob/master/lib/services/card_service.dart"
    click Collection_Service "https://github.com/goatt69/cardholder/blob/master/lib/services/collection_card_service.dart"
    click NewsPost_Service "https://github.com/goatt69/cardholder/blob/master/lib/services/newspost_service.dart"
    click Pokemon_Service "https://github.com/goatt69/cardholder/blob/master/lib/services/pokemon_service.dart"
    click Pokepost_Service "https://github.com/goatt69/cardholder/blob/master/lib/services/pokepost_service.dart"
    click Data_Models "https://github.com/goatt69/cardholder/tree/master/lib/model"
    click Config "https://github.com/goatt69/cardholder/blob/master/lib/config/config_url.dart"
    click Utils "https://github.com/goatt69/cardholder/blob/master/lib/utils/auth.dart"
    click Android "https://github.com/goatt69/cardholder/tree/master/android"
    click Web "https://github.com/goatt69/cardholder/tree/master/web"

    %% Styles
    classDef user fill:#f48fb1,stroke:#333,stroke-width:2px
    classDef presentation fill:#a9d0f5,stroke:#333,stroke-width:2px
    classDef services fill:#a5d6a7,stroke:#333,stroke-width:2px
    classDef models fill:#fff59d,stroke:#333,stroke-width:2px
    classDef config fill:#ffcc80,stroke:#333,stroke-width:2px
    classDef native fill:#e0e0e0,stroke:#333,stroke-width:2px
```
