# tw-bc-group/twallet architecture

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

- Interactive diagram: https://gitdiagram.com/tw-bc-group/twallet
- Repository: https://github.com/tw-bc-group/twallet

## Overview

##### Project Type and Purpose
- TWallet is a mobile-first digital wallet application built using Flutter. It supports blockchain token transactions (DC/EP), decentralized identifiers (DID), and includes a DApp browser interface.
- The README explains key concepts (digital wallet, DID, DApp) and clarifies that the app targets multiple platforms (Android, iOS) while leveraging Flutter’s cross-platform capabilities.

##### Analyzing the File Structure
- Top-Level Directories: The project includes platform-specific directories (“android”, “ios”), a “lib” folder with all the Dart source code, “assets” for images, fonts, dummy data, and “docs” for architecture decision records (ADRs). This clearly indicates a layered architecture.
- Inside “lib”, note:
- “views” – contains UI pages and components (presentation layer).
- “widgets” – encapsulates reusable UI components.
- “router” – manages routing with separate router handlers and declarations.
- “store” – houses state management (likely using GetX as seen from “lib/common/getx.dart”), which indicates an application/business logic layer.
- “service” – includes service classes (api_provider, blockchain, contract, firebase service, identity, pincode, etc.) that interact with external systems and perform business logic.
- “models” – defines data entities and DTOs with auto-generated serializers.
- Other files such as “pubspec.yaml”, various .dart files, and test cases further confirm a clean separation between UI, business logic, and data models.

a. Mobile Client (Flutter App):
- Two sub-nodes for Native Platforms (Android and iOS). Represent these as containers showing their native configuration and integration (e.g., “android”, “ios” folders).
- “lib” directory representing the bulk of Flutter code.
b. Presentation Layer (UI):
- “views” and “widgets” are the screens, dialogs, and UI components. Mark these as the front-end representation where user interactions occur.
- “router” for navigation among screens.
c. Business Logic / State Management Layer:
- “store” contains application state (e.g., wallet balances, identity, transactions) with GetX-based or similar state management.
- “common”, “l10n” (localization), and “generated” are supporting modules.
d. Service / Data Access Layer:
- “service” folder includes key services like API Provider, Blockchain, Contract, Identity, and even Firebase service for additional features.
- “models” represent the data transfer objects that flow between layers.
e. External Systems:
- Blockchain Network: Illustrate connections to the blockchain for transaction signing, smart contract interactions, and token operations.
- DID Services and Third-Party APIs: Show potential integrations for verification and decentralized identity functions.
- (Optionally) BLE module for payments under “lib/ble”, if it interacts with external devices.

##### Architectural Patterns and Design Principles
- The code follows a layered/multi-tiered architecture: UI (views, widgets) → State Management (store) → Service Layer (API clients and business logic) → External Systems (blockchain, identity, third-party services).
- There is clear separation of concerns which exemplifies the MVC (or MVVM/GetX) pattern used in Flutter.
- The project leverages auto-generated code (e.g., serializer.g.dart, various *.g.dart files) to ensure consistency in data management.
- Localization (l10n), theme management, and modular routing further enhance maintainability.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Mobile Client (Flutter App)
    subgraph "Mobile Client (Flutter App)"
        M1["Shared Code (lib)"]:::mobile
        M2["Android Native"]:::mobile
        M3["iOS Native"]:::mobile
    end

    %% Presentation Layer (UI)
    subgraph "Presentation Layer (UI)"
        P1["UI Screens"]:::presentation
        P2["Reusable Widgets"]:::presentation
        P3["Routing"]:::presentation
        P4["dApp Browser"]:::presentation
    end

    %% Business Logic / State Management
    subgraph "Business Logic / State Management"
        B1["State Management"]:::business
        B2["Common Utilities"]:::business
        B3["Localization"]:::business
    end

    %% Service / Data Access Layer
    subgraph "Service Layer (API/Blockchain)"
        S1["API & Blockchain Service"]:::service
        S2["Contract Service"]:::service
        S3["Identity Service"]:::service
        S4["dApp Service"]:::service
        S5["Firebase & Pincode Service"]:::service
    end

    %% Data Models
    subgraph "Data Models"
        D1["Data Models (DTOs & Serializers)"]:::models
    end

    %% External Integration
    subgraph "External Integration"
        E1["Blockchain Network"]:::external
        E2["Decentralized Identity (DID) Service"]:::external
        E3["BLE Payment"]:::external
    end

    %% Connections
    M1 -->|"supplies code to"| P1
    M2 --> M1
    M3 --> M1

    P1 -->|"triggers"| B1
    P2 --> B1
    P3 --> P1
    P4 <--> S4

    B1 -->|"calls"| S1
    B1 -->|"may invoke"| S5

    S1 -->|"interacts with"| E1
    S3 -->|"verifies with"| E2

    %% Data Models used by Service Layer
    S1 --- D1
    S2 --- D1
    S3 --- D1
    S4 --- D1
    S5 --- D1
    B1 --- D1

    %% Click Events for Mobile Client
    click M1 "https://github.com/tw-bc-group/twallet/tree/master/lib"
    click M2 "https://github.com/tw-bc-group/twallet/tree/master/android"
    click M3 "https://github.com/tw-bc-group/twallet/tree/master/ios"

    %% Click Events for Presentation Layer
    click P1 "https://github.com/tw-bc-group/twallet/tree/master/lib/views"
    click P2 "https://github.com/tw-bc-group/twallet/tree/master/lib/widgets"
    click P3 "https://github.com/tw-bc-group/twallet/blob/master/lib/router/router_handler.dart"
    click P3 "https://github.com/tw-bc-group/twallet/blob/master/lib/router/routers.dart"
    click P4 "https://github.com/tw-bc-group/twallet/blob/master/lib/views/dapp/dapp.dart"

    %% Click Events for Business Logic / State Management
    click B1 "https://github.com/tw-bc-group/twallet/tree/master/lib/store"
    click B2 "https://github.com/tw-bc-group/twallet/blob/master/lib/common/getx.dart"
    click B3 "https://github.com/tw-bc-group/twallet/tree/master/lib/l10n"
    click B3 "https://github.com/tw-bc-group/twallet/blob/master/lib/generated/l10n.dart"

    %% Click Events for Service Layer
    click S1 "https://github.com/tw-bc-group/twallet/blob/master/lib/service/api_provider.dart"
    click S1 "https://github.com/tw-bc-group/twallet/blob/master/lib/service/blockchain.dart"
    click S2 "https://github.com/tw-bc-group/twallet/blob/master/lib/service/contract.dart"
    click S3 "https://github.com/tw-bc-group/twallet/blob/master/lib/service/identity.dart"
    click S4 "https://github.com/tw-bc-group/twallet/blob/master/lib/service/dapp.dart"
    click S5 "https://github.com/tw-bc-group/twallet/blob/master/lib/service/firbase_service.dart"
    click S5 "https://github.com/tw-bc-group/twallet/blob/master/lib/service/pincode.dart"

    %% Click Events for Data Models
    click D1 "https://github.com/tw-bc-group/twallet/tree/master/lib/models"

    %% Click Events for External Integration
    click E3 "https://github.com/tw-bc-group/twallet/tree/master/lib/ble"

    %% Styles
    classDef mobile fill:#f9c,stroke:#333,stroke-width:2px;
    classDef presentation fill:#bbf,stroke:#333,stroke-width:2px;
    classDef business fill:#bfb,stroke:#333,stroke-width:2px;
    classDef service fill:#ffb,stroke:#333,stroke-width:2px;
    classDef models fill:#cff,stroke:#333,stroke-width:2px;
    classDef external fill:#fdd,stroke:#333,stroke-width:2px;
```
