# nabla-studio/quirks architecture

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

- Interactive diagram: https://gitdiagram.com/nabla-studio/quirks
- Repository: https://github.com/nabla-studio/quirks

## Overview

##### Project Identification and Primary Purpose
- Quirks is not a full-stack dapp but a universal adapter, meaning its purpose is to provide a common, extensible layer to integrate multiple wallets (Keplr, Leap, Cosmostation, etc.) into dapps.
- It caters to multiple frontend frameworks and global state management to enable cross-framework support.

##### Analyzing the File Structure
- The top-level directories include several configuration and tooling files (.eslintrc, pnpm-workspace.yaml, nx.json, etc.), indicating a well-organized monorepo.
- The "packages" directory holds multiple packages:
a. Core: Contains the primary business logic for wallet connections (packages/core).
b. Integration packages: For framework support – Next (packages/next), Nuxt (packages/nuxt), React (packages/react), Vue (packages/vue), React Native (packages/react-native), and SSR (packages/ssr).
c. Store: Manages global state and configurations (packages/store).
d. Wallet Registry and Wallets: Provide registration, configuration, and specific implementations for each wallet adapter (packages/wallet-registry and packages/wallets).
- The “examples” directory contains real-world implementations (e.g., nextjs, vue3) which illustrate how the adapters are used in different environments.

##### Key Components
a. Core Adapter Library:
- Central “core” component that contains business logic, type definitions, and utilities.
- That this core package is the heart of the universal wallet adapter.
b. Framework-Specific Integration Layers:
- Separate nodes for NextJS (packages/next), NuxtJS (packages/nuxt), React (packages/react), Vue (packages/vue), React Native (packages/react-native), and SSR.
- These layers serve as adaptation points providing integration-specific functionalities on top of the core.
c. Global State Management:
- The “store” package which handles global state even outside of the frameworks.
d. Wallet Registry and Wallet Implementations:
- “Wallet-registry” package that consolidates registration of supported wallets.
- “Wallets” package which contains the actual implementation/adapters for each wallet (e.g., Keplr, Leap, Cosmostation, etc.).
e. Utilities and Tools:

##### Relationships and Interactions
- That the dapp (or an example integration) calls one of the framework-specific adapters.
- The integration adapter interacts with the Core component to perform wallet operations.
- The Core, in turn, calls the Wallet Registry to determine the correct wallet adapter, which is then implemented via the Wallets package.
- Additionally, the Global Store is used for managing state and can be connected with both Core and the integration layers.
- Optionally, include the examples as external demos which “consume” the integrations to show real usage.

##### Architectural Patterns and Design Principles
- Modular and layered architecture: Clear separation of framework integrations from core business logic.
- Extensibility: The wallet registry and wallets packages allow easy addition of more wallets.
- Single Responsibility: Each package handles a distinct function – core logic, integration with a UI framework, or managing state.
- Dependency inversion: Each integration layer depends on the abstracted core functionalities rather than implementing wallet logic from scratch.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Dapps
    subgraph "External Dapps"
        EX("Examples"):::external
    end

    %% Integration Layers
    subgraph "Integration Layers"
        NX("NextJS Integration"):::integration
        NU("NuxtJS Integration"):::integration
        RT("React Integration"):::integration
        VUE("Vue Integration"):::integration
        RN("React Native Integration"):::integration
        SSR("SSR Integration"):::integration
    end

    %% Core Layer
    subgraph "Core Layer"
        CORE("Core Wallet Adapter"):::core
        STORE("Global State Management"):::global
    end

    %% Wallet Adapters
    subgraph "Wallet Adapters"
        REG("Wallet Registry"):::registry
        WALLET("Wallet Implementations"):::wallet
    end

    %% Relationships from Examples to Integration Layers
    EX --> NX
    EX --> NU
    EX --> RT
    EX --> VUE
    EX --> RN
    EX --> SSR

    %% Relationships from Integration Layers to Core
    NX -->|"callsCore"| CORE
    NU -->|"callsCore"| CORE
    RT -->|"callsCore"| CORE
    VUE -->|"callsCore"| CORE
    RN -->|"callsCore"| CORE
    SSR -->|"callsCore"| CORE

    %% Relationships from Integration Layers to Global State Management
    NX -->|"updatesStore"| STORE
    NU -->|"updatesStore"| STORE
    RT -->|"updatesStore"| STORE
    VUE -->|"updatesStore"| STORE
    RN -->|"updatesStore"| STORE
    SSR -->|"updatesStore"| STORE

    %% Relationship from Core to Global State Management
    CORE -->|"updatesStore"| STORE

    %% Relationships from Core to Wallet Adapters
    CORE -->|"callsRegistry"| REG
    REG -->|"callsWallet"| WALLET

    %% Click Events
    click CORE "https://github.com/nabla-studio/quirks/tree/main/packages/core"
    click NX "https://github.com/nabla-studio/quirks/tree/main/packages/next"
    click NU "https://github.com/nabla-studio/quirks/tree/main/packages/nuxt"
    click RT "https://github.com/nabla-studio/quirks/tree/main/packages/react"
    click VUE "https://github.com/nabla-studio/quirks/tree/main/packages/vue"
    click RN "https://github.com/nabla-studio/quirks/tree/main/packages/react-native"
    click SSR "https://github.com/nabla-studio/quirks/tree/main/packages/ssr"
    click STORE "https://github.com/nabla-studio/quirks/tree/main/packages/store"
    click REG "https://github.com/nabla-studio/quirks/tree/main/packages/wallet-registry"
    click WALLET "https://github.com/nabla-studio/quirks/tree/main/packages/wallets"

    %% Style definitions
    classDef core fill:#f9c74f,stroke:#000,stroke-width:2px;
    classDef integration fill:#90be6d,stroke:#000,stroke-width:2px;
    classDef global fill:#f94144,stroke:#000,stroke-width:2px;
    classDef registry fill:#577590,stroke:#000,stroke-width:2px;
    classDef wallet fill:#277da1,stroke:#000,stroke-width:2px;
    classDef external fill:#f3722c,stroke:#000,stroke-width:2px;
```
