# nahmii/nii-token-reissue architecture

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

- Interactive diagram: https://gitdiagram.com/nahmii/nii-token-reissue
- Repository: https://github.com/nahmii/nii-token-reissue

## Overview

##### Project Type & Purpose
- This repository is not a full-blown application or microservices system. Instead, it serves as a data repository for collated snapshot information of Nahmii (NII) token holders – a critical part of the token reissuance process following a security incident.
- The README emphasizes that it holds snapshot data (via snapshot.csv) with additional distribution logic (in distribution.json) and provides guidance for eligible wallet owners to claim their new tokens through an external account page.

##### Analyzing the File Structure
- Top-Level Directories and Files:
– .github directory: Contains issue templates (bug reports, feature requests, and questions) and a pull-request template. This shows the project has a maintained development process.
– distribution.json: Likely holds the reissuance logic or related data mapping the old token allocations (NII) to the new tokens (NT).
– snapshot.csv: Contains the snapshot data of token holders used to verify eligibility and calculate allocations.
– images folder: Includes visual assets to be used in the README (e.g., allocation and claiming screenshots) to support user instructions.
- The file structure is lean, emphasizing that the repository’s role is to keep accurate data files and support user instructions (as opposed to containing actual application code).

##### Insights from the README
- The README provides a clear and concise overview of the reissuance process, token conversion formula, and user instructions for claiming tokens via an external Nahmii account page.
- It describes external components (e.g., wallet connection, claim modal with MetaMask integration) that interact with the snapshot data stored in the repository.
- Token contract addresses for L1 and L2 networks are explicitly stated, hinting at the overall ecosystem where blockchain interactions are critical.

a. Main Components to Include
– Data Repository:
◦ "Snapshot Data" (snapshot.csv) – Containing eligible wallet information and token allocation details.
◦ "Distribution Mapping" (distribution.json) – Contains conversion logic or allocation adjustments from old token parameters (NII) to new (NT).
– External Interfaces:
◦ "Nahmii Account Page" – The external front-end interface through which users connect their wallets, view their snapshot balances, and trigger token claims.
◦ "Wallet & MetaMask Interaction" – Representing the process flow when users connect, view, and initiate transactions.
– Blockchain Components:
◦ "Ethereum Mainnet Contract" and "Nahmii 3.0 Contract" – Represent the token contracts deployed on L1 and L2, respectively, and are referenced in the README with addresses.
– Repository and Issue Management:
◦ "GitHub Configuration & Issue Templates" – Highlighting development practices and user reporting mechanisms as part of the broader process, though they are not part of runtime execution.

b. Relationships & Interactions
– Illustrate the user journey: User connects wallet → Data from snapshot files confirms eligibility → External account page displays allocation → User confirms claim via MetaMask → Transaction interacts with the blockchain (via token contract).
– Highlight the separation between data storage (repository files) and user interaction (front-end on the account page).

c. Architectural Patterns & Design Principles
– Although the repository is simple, emphasize a clear separation of concerns: data management (snapshot CSV/distribution JSON) versus user-facing token claim flows.
– Show that the system design treats off-chain data (in the repository) as feeding into on-chain processes (token claim and token contracts), thus using a hybrid design approach where off-chain data is used to compute on-chain transactions.

d. Relevant Technologies & Frameworks
◦ “MetaMask” – as the wallet interface for users.
◦ “Nahmii Account Page” – as a web front-end (likely built using modern web technologies) that interacts with the blockchain and uses the snapshot data.
◦ “Ethereum / Nahmii Blockchain” – representing the underlying blockchain where token contracts reside.

##### Elements
– Use clear labels (e.g., “Snapshot CSV File”, “Distribution JSON File”, “Token Claim Modal”, “User Wallet/MetaMask”, “Ethereum Mainnet Contract”, “Nahmii 3.0 Contract”).
◦ Data files (e.g. repository data)
◦ User Interface components
◦ Blockchain components
◦ Development/Issue management ecosystem (.github)

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Data Repository"
        SD["Snapshot Data (snapshot.csv)"]:::data
        DM["Distribution Mapping (distribution.json)"]:::data
    end

    subgraph "User Claim Process"
        TCP["Token Claim Process"]:::ui
        NAP["Nahmii Account Page"]:::ui
        WM["Wallet & MetaMask Interaction"]:::ui
    end

    subgraph "Blockchain"
        EMC["Ethereum Mainnet Contract"]:::blockchain
        N30C["Nahmii 3.0 Contract"]:::blockchain
    end

    subgraph "Repository Management"
        GI["GitHub Issue & PR Templates"]:::dev
        VA["Visual Assets for Documentation"]:::dev
        RD["Project Documentation (README)"]:::dev
    end

    SD -->|"feeds"| TCP
    DM -->|"feeds"| TCP
    TCP -->|"triggers"| NAP
    NAP -->|"initiates"| WM
    WM -->|"calls"| EMC
    WM -->|"calls"| N30C
    RD -->|"guides"| NAP

    classDef data fill:#ffccff,stroke:#333,stroke-width:2px;
    classDef ui fill:#bbdefb,stroke:#333,stroke-width:2px;
    classDef blockchain fill:#c8e6c9,stroke:#333,stroke-width:2px;
    classDef dev fill:#ffe0b2,stroke:#333,stroke-width:2px;

    click SD "https://github.com/nahmii/nii-token-reissue/blob/master//snapshot.csv"
    click DM "https://github.com/nahmii/nii-token-reissue/blob/master//distribution.json"
    click GI "https://github.com/nahmii/nii-token-reissue/tree/master//github"
    click VA "https://github.com/nahmii/nii-token-reissue/tree/master//images"
    click RD "https://github.com/nahmii/nii-token-reissue/blob/master//README.md"
```
