# johnykoudsi/nfc_host_card_emulation architecture

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

- Interactive diagram: https://gitdiagram.com/johnykoudsi/nfc_host_card_emulation
- Repository: https://github.com/johnykoudsi/nfc_host_card_emulation

## Overview

##### Project type and purpose
- This is a Flutter-based cross-platform mobile application (“nfa”) focused on NFC functionality (read/write and host card emulation).
- Key indicators:
- lib/core/notifier/nfc_notifier.dart – state-management for NFC events
- lib/presentation/screen/read_write_nfc_screen.dart – UI to read/write tags
- android/app/src/.../MyHostApduService.java/.kt and apduservice.xml – Android HCE service

##### File structure
- Top-level:
- android/ – native Android project with Java/Kotlin HCE service
- ios/ – native iOS runner (no custom NFC code)
- lib/
– core/notifier – business logic for NFC
– presentation/screen/widgets – UI layer
– main.dart – app entry point
- test/ – widget tests
- Patterns: MVVM / layered architecture (presentation ↔ core/notifier ↔ platform channel ↔ native)
- Config & build: pubspec.yaml (Dart deps), AndroidManifest.xml (permissions, HCE service), Gradle, Xcode projects

##### Detailed capture of essential elements
- Flutter UI (screens + widgets)
- Business logic (notifier, state)
- Engine / Platform interface
- Native platform modules (Android HCE vs. iOS runner)
- Physical NFC components (chip, tags)
- Callback loop: Native → Flutter → UI

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Flutter Layer
    subgraph "Flutter Layer"
        direction TB
        UI1["ReadWriteNfcScreen"]:::frontend
        UI2["Dialogs"]:::frontend
        BL["NfcNotifier"]:::business
        ENTRY["main.dart"]:::frontend
    end

    %% Platform Interface
    subgraph "Platform Interface"
        direction TB
        PC["MethodChannel"]:::platform
    end

    %% Android Native
    subgraph "Android Native"
        direction TB
        ACT["MainActivity.kt"]:::native
        HCE_J["MyHostApduService.java"]:::native
        HCE_K["MyHostApduService.kt"]:::native
        XML["apduservice.xml"]:::native
        AM["AndroidManifest.xml"]:::native
    end

    %% iOS Native
    subgraph "iOS Native"
        direction TB
        IOS["AppDelegate.swift"]:::native
    end

    %% Configuration & Tests
    subgraph "Config & Tests"
        direction TB
        PUB["pubspec.yaml"]:::config
        TEST["widget_test.dart"]:::test
    end

    %% Physical Components
    subgraph "Physical Components"
        direction TB
        CHIP["NFC Chip"]:::hardware
        TAG["External NFC Tag/Reader"]:::external
    end

    %% Data Flows
    UI1 -->|"user taps Scan"| BL
    UI2 -->|uses dialogs| BL
    ENTRY -->|initializes Channel| PC
    BL -->|"invoke read/write"| PC
    PC -->|"invoke Android APIs"| HCE_J
    PC -->|"invoke Android APIs"| HCE_K
    PC -->|"invoke iOS NFC"| IOS
    HCE_J -->|"registered via XML"| XML
    HCE_K -->|"registered via XML"| XML
    HCE_J -->|"declared in"| AM
    HCE_K -->|"declared in"| AM
    AM -->|grants NFC permission| CHIP
    IOS -->|"access NFC hardware"| CHIP
    HCE_J -->|"APDU commands"| CHIP
    HCE_K -->|"APDU commands"| CHIP
    CHIP ---|magnetic field| TAG
    TAG ---|response| CHIP
    CHIP -->|"hardware callback"| PC
    PC -->|"method call response"| BL
    BL -->|"state update"| UI1
    BL -->|"state update"| UI2
    ENTRY -->|"loads dependencies"| PUB
    UI1 -->|tested by| TEST

    %% Click Events
    click UI1 "https://github.com/johnykoudsi/nfc_host_card_emulation/blob/master/lib/presentation/screen/read_write_nfc_screen.dart"
    click UI2 "https://github.com/johnykoudsi/nfc_host_card_emulation/blob/master/lib/presentation/widgets/dialogs.dart"
    click BL "https://github.com/johnykoudsi/nfc_host_card_emulation/blob/master/lib/core/notifier/nfc_notifier.dart"
    click ENTRY "https://github.com/johnykoudsi/nfc_host_card_emulation/blob/master/lib/main.dart"
    click ACT "https://github.com/johnykoudsi/nfc_host_card_emulation/blob/master/android/app/src/main/kotlin/com/example/nfa/MainActivity.kt"
    click HCE_J "https://github.com/johnykoudsi/nfc_host_card_emulation/blob/master/android/app/src/main/java/com/example/nfa/MyHostApduService.java"
    click HCE_K "https://github.com/johnykoudsi/nfc_host_card_emulation/blob/master/android/app/src/main/kotlin/com/example/nfa/MyHostApduService.kt"
    click XML "https://github.com/johnykoudsi/nfc_host_card_emulation/blob/master/android/app/src/main/res/xml/apduservice.xml"
    click AM "https://github.com/johnykoudsi/nfc_host_card_emulation/blob/master/android/app/src/main/AndroidManifest.xml"
    click IOS "https://github.com/johnykoudsi/nfc_host_card_emulation/blob/master/ios/Runner/AppDelegate.swift"
    click PUB "https://github.com/johnykoudsi/nfc_host_card_emulation/blob/master/pubspec.yaml"
    click TEST "https://github.com/johnykoudsi/nfc_host_card_emulation/blob/master/test/widget_test.dart"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#0366D6,color:#0366D6;
    classDef business fill:#DFF7DF,stroke:#28A745,color:#28A745;
    classDef platform fill:#E6F4EA,stroke:#2C9A3F,color:#2C9A3F;
    classDef native fill:#FFE8CC,stroke:#E36209,color:#E36209;
    classDef config fill:#F0E5FF,stroke:#6F42C1,color:#6F42C1;
    classDef test fill:#FFF5F5,stroke:#CB2431,color:#CB2431;
    classDef hardware fill:#F6F8FA,stroke:#586069,color:#586069;
    classDef external fill:#F6F8FA,stroke:#586069,color:#586069;
```
