# xortroll/emuiibo architecture

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

- Interactive diagram: https://gitdiagram.com/xortroll/emuiibo
- Repository: https://github.com/xortroll/emuiibo

## Overview

##### Project Type and Purpose
- This repository is a homebrew solution for Nintendo Switch that emulates amiibos (virtual amiibos). The core component (emuiibo) is written in Rust and runs on the console, intercepting amiibo access.
- In addition, there is a PC-side utility (emuiigen, written in Kotlin/Java with Maven support) that creates and edits amiibo configurations, and an overlay component (written in C++) that provides a graphical interface (integrated with Tesla-menu) for controlling the emulation.
- The project also includes auxiliary components (such as the overlay libraries and support files) that interact with the Switch’s NFC services via a custom IPC service.

##### Analysis of the File Structure
- The root contains GitHub workflow configurations, a Makefile, and global files (LICENSE, README).
- The “emuiibo” folder is a Rust/Cargo project that includes:
- Core source code (main.rs) and several modular source files (e.g., amiibo.rs, areas, ipc, logger, rand, etc.).
- Configuration files (Cargo.toml, Cargo.lock) and linker scripts (*.ld) used for building on the Switch.
- The “emuiigen” folder houses a Maven-based Kotlin project (pom.xml and .kt source files) that serves as the amiibo creation/editing tool.
- The “overlay” folder contains C++ source and header files, a Makefile, and additional language / UI resources, which compose the graphical overlay interface.
- Other folders like “.github”, “res”, “screenshots”, etc., provide support and visual assets, but the key architectural elements are in “emuiibo”, “emuiigen”, and “overlay”.

##### Key Components and Their Relationships
a. Core Emulation Engine (emuiibo):
- Implements amiibo emulation logic, including handling the amiibo JSON configuration, random UUID generation, savedata handling (per-game area data), and mimicking NFC responses.
- Provides a custom IPC service to allow external homebrew tools to control amiibo emulation.
- Interfaces with file-based data storage on the SD card (amiibo folders, miis, and areas).
b. Amiibo Configuration Generator (emuiigen):
- A PC-side GUI tool that allows users to create or edit virtual amiibo profiles.
- Uses external APIs (AmiiboAPI) to automatically fill in amiibo details.
- Outputs amiibo folders (with amiibo.json and flag files) that are later read by the emuiibo engine on the Switch.
c. Graphical Overlay (overlay):
- A C++ module that integrates with Tesla-menu/nx-ovlloader overlays.
- Provides interactive control over the emulation (e.g., toggling emulation status, selecting active amiibo, and connecting/disconnecting the virtual amiibo).
- Acts as the front-end for the user to control the core emulation service via the IPC mechanism.
d. External Dependencies and Integration Points:
- The system must interact with tools like Tesla-Menu and nx-ovlloader (which are deployed on the SD card alongside emuiibo).
- Communication from a Nintendo Switch game’s NFC service goes to the emuiibo engine, which then potentially uses overlay inputs and saved configurations from the SD card.

##### Architectural Patterns and Design Principles
- Modularization: distinct components for emulation (Rust core), configuration & generation (Kotlin utility), and user interface/overlay (C++ graphical overlay).
- Separation of Concerns: Each module is responsible for a specific part – the emulation core handles system-level amiibo behavior, the emuiigen tool manages amiibo data creation, and the overlay provides user control.
- Layered Communication: The design shows clear layers with file system storage (amiibo configuration, miis, savedata files) at the base, a core service layer that intercepts NFC calls, and a GUI layer (overlay) for direct user interaction. The IPC service within emuiibo allows external modules (like the overlay) to control behavior.

## Diagram (Mermaid)

```mermaid
flowchart TD 
    %% External nodes
    ext_Nintendo["Nintendo Switch Game (NFC)"]:::external
    storage["SD Card Amiibo Data"]:::storage

    %% Emuiibo Core (Rust) Subgraph
    subgraph "Emuiibo Core (Rust)"
        e_main["Core Application Entry"]:::rust
        e_nfc["NFC Emulation & Amiibo Handling"]:::rust
        e_nfc_file["Amiibo Handling Module"]:::rust
        e_nfc_dir["Amiibo Extensions"]:::rust
        e_fileio["File I/O & Savedata Management"]:::rust
        e_ipc["IPC Service"]:::rust
        e_ipc_file["IPC Main Module"]:::rust
        e_ipc_dir["IPC Submodules"]:::rust
        e_log["Logging Module"]:::rust
        e_rand["Random UUID Generation"]:::rust
    end

    %% Emuiigen Tool (Kotlin/Java) Subgraph
    subgraph "Emuiigen Tool (Kotlin/Java)"
        e_maven["Maven Configuration"]:::kotlin
        e_api["Amiibo Config & API Integration"]:::kotlin
        e_ui["User Interface for Amiibo Creation"]:::kotlin
        e_res["Additional UI Resources"]:::kotlin
    end

    %% Overlay UI (C++) Subgraph
    subgraph "Overlay UI (C++)"
        o_make["Build & Configuration"]:::cpp
        o_service_hdr["Overlay Service Header"]:::cpp
        o_service_src["Overlay Service Source"]:::cpp
        o_ui_hdr["Overlay UI Headers"]:::cpp
        o_ui_src["Overlay UI Sources"]:::cpp
        o_lang["Multi-language Support"]:::cpp
        o_trans_hdr["Overlay Translation Header"]:::cpp
        o_trans_src["Overlay Translation Source"]:::cpp
    end

    %% Relationships between components

    %% External interactions
    ext_Nintendo -->|"NFC_Access"| e_nfc
    e_fileio -->|"Reads/Writes"| storage
    e_api -->|"Outputs_Config"| storage
    o_ui_src -->|"Sends_Controls"| e_ipc
    o_service_hdr -.->|"Interfaces_with"| e_ipc

    %% Emuiibo Core internal flow
    e_main --> e_nfc
    e_nfc --> e_nfc_file
    e_nfc --> e_nfc_dir
    e_main --> e_fileio
    e_ipc --> e_ipc_file
    e_ipc --> e_ipc_dir
    e_main --> e_log
    e_log --> e_rand

    %% Emuiigen internal flow
    e_maven --> e_api
    e_api --> e_ui
    e_ui --> e_res

    %% Overlay internal flow
    o_make --> o_service_hdr
    o_make --> o_service_src
    o_make --> o_ui_hdr
    o_make --> o_ui_src
    o_make --> o_lang
    o_lang --> o_trans_hdr
    o_lang --> o_trans_src

    %% Click Events for Emuiibo Core (Rust)
    click e_main "https://github.com/xortroll/emuiibo/blob/master/emuiibo/src/main.rs"
    click e_nfc "https://github.com/xortroll/emuiibo/blob/master/emuiibo/src/amiibo.rs"
    click e_nfc_dir "https://github.com/xortroll/emuiibo/tree/master/emuiibo/src/amiibo/"
    click e_fileio "https://github.com/xortroll/emuiibo/blob/master/emuiibo/src/area.rs"
    click e_fileio "https://github.com/xortroll/emuiibo/blob/master/emuiibo/toolbox.json"
    click e_ipc "https://github.com/xortroll/emuiibo/blob/master/emuiibo/src/ipc.rs"
    click e_ipc_dir "https://github.com/xortroll/emuiibo/tree/master/emuiibo/src/ipc/"
    click e_log "https://github.com/xortroll/emuiibo/blob/master/emuiibo/src/logger.rs"
    click e_rand "https://github.com/xortroll/emuiibo/blob/master/emuiibo/src/rand.rs"

    %% Click Events for Emuiigen Tool (Kotlin/Java)
    click e_maven "https://github.com/xortroll/emuiibo/blob/master/emuiigen/pom.xml"
    click e_api "https://github.com/xortroll/emuiibo/tree/master/emuiigen/src"
    click e_ui "https://github.com/xortroll/emuiibo/tree/master/emuiigen/src/ui"
    click e_res "https://github.com/xortroll/emuiibo/tree/master/emuiigen/res"

    %% Click Events for Overlay UI (C++)
    click o_make "https://github.com/xortroll/emuiibo/tree/master/overlay/Makefile"
    click o_service_hdr "https://github.com/xortroll/emuiibo/blob/master/overlay/include/emu/emu_Service.hpp"
    click o_service_src "https://github.com/xortroll/emuiibo/blob/master/overlay/source/emu/emu_Service.cpp"
    click o_ui_hdr "https://github.com/xortroll/emuiibo/tree/master/overlay/include/ui"
    click o_ui_src "https://github.com/xortroll/emuiibo/tree/master/overlay/source/ui"
    click o_lang "https://github.com/xortroll/emuiibo/tree/master/overlay/lang"
    click o_trans_hdr "https://github.com/xortroll/emuiibo/tree/master/overlay/include/tr"
    click o_trans_src "https://github.com/xortroll/emuiibo/tree/master/overlay/source/tr"

    %% Styles
    classDef rust fill:#AED6F1,stroke:#1B4F72,stroke-width:2px;
    classDef kotlin fill:#A9DFBF,stroke:#196F3D,stroke-width:2px;
    classDef cpp fill:#F9E79F,stroke:#B9770E,stroke-width:2px;
    classDef external fill:#D7BDE2,stroke:#6C3483,stroke-width:2px;
    classDef storage fill:#F5CBA7,stroke:#D35400,stroke-width:2px;
```
