# geen-19/nautilus-interface architecture

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

- Interactive diagram: https://gitdiagram.com/geen-19/nautilus-interface
- Repository: https://github.com/geen-19/nautilus-interface

## Overview

##### Project type and purpose
- This is a Single-Page Application (SPA) front-end built with React and TypeScript, bundled by Vite.
- It serves as the user interface for the Nautilus NFT Marketplace on the Voi Network, letting users browse collections, list/buy NFTs, stake tokens, interact with smart contracts, and manage their wallet.

##### File structure
- Top level:
- src/ → all application code
- components/ → small, reusable UI pieces and modals
- pages/ → page-level components mapped by the router
- clients/ → network layer classes (e.g. VNSRegistrarClient) handling JSON-RPC calls to the Voi blockchain
- hooks/ → custom React hooks encapsulating data-fetching & business logic
- store/ → Redux Toolkit slices & Context providers for global state (marketplace, cart, user, theme, etc.)
- config/ + constants/ → API endpoints, contract addresses, feature flags
- utils/ + lib/ → shared helper functions
- router/ → React Router setup
- theme/ + style.css + tailwind.config.js → styling configuration
- index.tsx & App.tsx → React entry point and root component

##### README
- Confirms this is the open-source front-end for Nautilus NFT Marketplace on Voi Network.
- No back-end code here—interactions go directly from the client to smart contracts.

- Browser/Client – hosts the SPA
- UI Layer – React Pages & Components
- State Management – Redux slices & Context providers
- Network Layer – client classes (AirdropClient, VNSRegistryClient, etc.) + custom hooks
- Wallet Provider – Metamask/WalletConnect injected web3 provider
- Voi Network – Voi RPC nodes & smart contracts
- Static Asset Host or CDN – serves public/ and built static files
- Build/Deployment – Vite → bundler, Tailwind/PostCSS → styles

b. Relationships and data flows:
1. User interacts with UI → dispatches actions to State
2. UI/Hooks read from State to render data
3. UI/Hooks call Network Layer (Clients) for on-chain queries or transactions
4. Clients send JSON-RPC over HTTP/WebSocket to Voi RPC node
5. RPC node executes smart contract call & returns data/tx receipts
6. Responses pass back to State → UI re-renders
7. UI fetches NFT metadata/images from public/ or IPFS/CDN URLs
8. Wallet Provider signs transactions initiated by Clients

c. Architectural patterns & principles:
- Layered Architecture – UI → State → Network → Blockchain
- Flux pattern – unidirectional data flow (React + Redux)
- Directory-per-feature & atomic component organization

d. Key technologies and libraries:
- React + TypeScript + JSX/TSX
- Redux Toolkit (store/slices)
- React Router
- Vite + PostCSS + Tailwind CSS
- JSON-RPC clients for Voi smart contracts
- Custom React Hooks

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Entities
    Browser["Browser / Client"]:::external
    Wallet["Wallet Provider<br/>(MetaMask / WalletConnect)"]:::external
    CDN["Static Asset Host / CDN"]:::external
    Blockchain["Voi Network<br/>(RPC Nodes & Smart Contracts)"]:::external

    %% UI Layer
    subgraph "UI Layer" 
        direction TB
        Pages["Pages<br/>(src/pages/)"]:::ui
        Components["Reusable Components<br/>(src/components/)"]:::ui
        Layouts["Layouts<br/>(src/layouts/Default.tsx)"]:::ui
        Hooks["Custom Hooks<br/>(src/hooks/)"]:::ui
    end

    %% State Management
    subgraph "State Management" 
        direction TB
        ReduxStore["Redux Slices<br/>(src/store/*.ts)"]:::state
        Context["Context Providers<br/>(src/store/MarketplaceProvider.tsx)"]:::state
    end

    %% Network Layer
    subgraph "Network Layer"
        direction TB
        Clients["JSON-RPC Clients<br/>(src/clients/)"]:::network
        ConfigAPI["API Config<br/>(src/config/api.ts)"]:::network
    end

    %% Core App Entry & Config
    subgraph "Core & Config"
        direction TB
        Entry["Entry Point<br/>(src/index.tsx)"]:::core
        AppComp["Root Component<br/>(src/App.tsx)"]:::core
        Router["Router Setup<br/>(src/router/index.tsx)"]:::core
        Constants["Constants & Routes<br/>(src/constants/routes.ts)"]:::core
        Theme["Theming & Styles<br/>(src/theme/index.ts)"]:::core
        Utils["Utilities<br/>(src/utils/ & src/lib/utils.ts)"]:::core
        WalletInt["Wallet Integration<br/>(src/wallets.ts)"]:::core
    end

    %% Build / Deployment
    subgraph "Build / Deployment"
        direction TB
        ViteCfg["Vite Config<br/>(vite.config.js)"]:::build
        TailwindCfg["Tailwind & PostCSS<br/>(tailwind.config.js,<br/>postcss.config.cjs)"]:::build
    end

    %% Data Flows
    Browser -->|"loads SPA"| Entry
    Entry --> AppComp
    AppComp --> Pages
    AppComp --> Components
    Pages -->|use Hooks| Hooks
    Components -->|use Hooks| Hooks
    Hooks -->|dispatch actions| ReduxStore
    ReduxStore -->|provide state| Pages
    ReduxStore -->|provide state| Components
    Pages -->|invoke| Clients
    Components -->|invoke| Clients
    Clients -->|HTTP/WebSocket| Blockchain
    Blockchain -->|response| Clients
    Clients -->|update| ReduxStore
    Clients -->|read config| ConfigAPI
    AppComp --> Router
    Router --> Pages
    AppComp --> Theme
    AppComp --> Utils
    AppComp --> Constants
    AppComp --> WalletInt
    Wallet -->|sign transactions| WalletInt
    CDN -->|serve assets| Browser

    %% Click Events
    click Browser "https://github.com/geen-19/nautilus-interface/blob/beta/index.html"
    click Pages "https://github.com/geen-19/nautilus-interface/tree/beta/src/pages/"
    click Components "https://github.com/geen-19/nautilus-interface/tree/beta/src/components/"
    click Layouts "https://github.com/geen-19/nautilus-interface/blob/beta/src/layouts/Default.tsx"
    click ReduxStore "https://github.com/geen-19/nautilus-interface/blob/beta/src/store/store.ts"
    click Context "https://github.com/geen-19/nautilus-interface/blob/beta/src/store/MarketplaceProvider.tsx"
    click Clients "https://github.com/geen-19/nautilus-interface/blob/beta/src/clients/AirdropClient.ts"
    click Hooks "https://github.com/geen-19/nautilus-interface/blob/beta/src/hooks/useCollectionInfo.ts"
    click WalletInt "https://github.com/geen-19/nautilus-interface/blob/beta/src/wallets.ts"
    click ConfigAPI "https://github.com/geen-19/nautilus-interface/blob/beta/src/config/api.ts"
    click CDN "https://github.com/geen-19/nautilus-interface/tree/beta/public/"
    click ViteCfg "https://github.com/geen-19/nautilus-interface/blob/beta/vite.config.js"
    click TailwindCfg "https://github.com/geen-19/nautilus-interface/blob/beta/tailwind.config.js"
    click TailwindCfg "https://github.com/geen-19/nautilus-interface/blob/beta/postcss.config.cjs"
    click Constants "https://github.com/geen-19/nautilus-interface/blob/beta/src/constants/routes.ts"
    click Theme "https://github.com/geen-19/nautilus-interface/blob/beta/src/theme/index.ts"
    click Utils "https://github.com/geen-19/nautilus-interface/tree/beta/src/utils/"
    click Utils "https://github.com/geen-19/nautilus-interface/blob/beta/src/lib/utils.ts"
    click Router "https://github.com/geen-19/nautilus-interface/blob/beta/src/router/index.tsx"
    click Entry "https://github.com/geen-19/nautilus-interface/blob/beta/src/index.tsx"
    click AppComp "https://github.com/geen-19/nautilus-interface/blob/beta/src/App.tsx"

    %% Styles
    classDef external fill:#f3f4f6,stroke:#333,stroke-width:1px,color:#000;
    classDef ui fill:#cce5ff,stroke:#004085,stroke-width:1px,color:#004085;
    classDef state fill:#d4edda,stroke:#155724,stroke-width:1px,color:#155724;
    classDef network fill:#fff3cd,stroke:#856404,stroke-width:1px,color:#856404;
    classDef core fill:#e2e3e5,stroke:#383d41,stroke-width:1px,color:#383d41;
    classDef build fill:#f5c6cb,stroke:#721c24,stroke-width:1px,color:#721c24;
```
