Skip to main content

​
Overview

Hermis is built with a modular, layered architecture that provides maximum flexibility while maintaining clean separation of concerns. This design allows you to use only the parts you need and easily extend or customize functionality.

​
Architecture Diagram

┌─────────────────────────────────────────────────────────────┐
│                     Application Layer                        │
│  (Your dApp UI - React, Vue, Vanilla JS, etc.)              │
└─────────────────────────┬───────────────────────────────────┘
                          │
                          │ uses
                          ▼
┌─────────────────────────────────────────────────────────────┐
│              Framework Integration Layer                     │
│  ┌────────────────────┐  ┌────────────────────┐            │
│  │  @hermis/react     │  │  @hermis/vue       │            │
│  │  - Hooks           │  │  - Composables     │            │
│  │  - Context         │  │  - Components      │            │
│  │  - Components      │  │  (Coming Soon)     │            │
│  └────────────────────┘  └────────────────────┘            │
└─────────────────────────┬───────────────────────────────────┘
                          │
                          │ built on
                          ▼
┌─────────────────────────────────────────────────────────────┐
│               Adapter Integration Layer                      │
│          @hermis/solana-headless-adapter-base               │
│  - WalletAdapterManager                                     │
│  - Wallet Standard Support                                   │
│  - Event Management                                          │
│  - Adapter Utilities                                         │
└─────────────────────────┬───────────────────────────────────┘
                          │
                          │ built on
                          ▼
┌─────────────────────────────────────────────────────────────┐
│                   External Dependencies                      │
│  - @solana/web3.js                                          │
│  - @solana/wallet-adapter-base                              │
│  - Wallet-specific adapters                                  │
└─────────────────────────────────────────────────────────────┘

​
Layer Breakdown

​
1. Adapter Integration Layer (@hermis/solana-headless-adapter-base)

Provides wallet adapter management and Wallet Standard support.

Responsibilities

  • Wallet adapter lifecycle
  • Wallet Standard integration
  • Event-driven architecture
  • Adapter prioritization
  • State management

Key Features

  • Multi-wallet support
  • Automatic wallet detection
  • Event emitters
  • Adapter sorting
  • Ready state management
When to use directly:
  • Vanilla JavaScript apps
  • Custom framework integration
  • Need event-driven updates
  • Building custom UI components

​
2. Framework Integration Layer

Framework-specific implementations with hooks, components, and utilities.

​
React (@hermis/solana-headless-react)

Features

  • React Hooks (useWallet, useConnection, etc.)
  • Context Providers
  • Automatic state management
  • React 18+ support
  • TypeScript definitions
When to use:
  • Building React applications
  • Want automatic state management
  • Need React hooks
  • Prefer declarative approach

​
Vue (@hermis/solana-headless-vue)

Vue support is under development. Follow our GitHub for updates.

​
Design Principles

​
1. Headless-First

Unlike traditional wallet adapters with built-in UI components, Hermis provides zero UI. You have complete control over look, feel, and user experience.
Use any UI library or framework:
  • Tailwind CSS
  • Material-UI
  • Ant Design
  • Custom CSS
  • Styled Components
  • CSS Modules

​
2. Modular Architecture

Each layer can be used independently or combined as needed: 
// Use adapter-base for vanilla JS apps
import { WalletAdapterManager } from '@hermis/solana-headless-adapter-base';

// Use React package for React apps
import { useWallet } from '@hermis/solana-headless-react';

​
3. Type Safety

Full TypeScript support throughout the stack: 
import type { Adapter } from '@solana/wallet-adapter-base';
import type { Connection, Transaction, PublicKey } from '@solana/web3.js';

// Compile-time type checking
const wallet: Adapter = adapter;
const pubKey: PublicKey | null = wallet.publicKey;

​
4. Framework Agnostic

The adapter-base package works anywhere:
  • React
  • Vue
  • Angular
  • Svelte
  • Vanilla JavaScript
  • Node.js (backend)
  • Electron
  • React Native

​
Data Flow

​
Connection Flow

User Action (Connect Button)
         ↓
Framework Layer (useWallet hook)
         ↓
Adapter Layer (WalletAdapterManager)
         ↓
Wallet Adapter (Phantom, Solflare, etc.)
         ↓
Browser Extension / Mobile Wallet
         ↓
User Approval
         ↓
Events propagate back up
         ↓
UI Updates

​
Transaction Flow

Create Transaction (Application)
         ↓
Sign Transaction (Wallet Adapter)
         ↓
User Approval (Wallet UI)
         ↓
Send to Network (Connection)
         ↓
Await Confirmation
         ↓
Update Application State

​
State Management

​
React

State is managed automatically through Context and hooks: 
<HermisProvider>
  {/* Wallet state available to all children */}
  <YourApp />
</HermisProvider>

​
Vanilla JS

State managed through events: 
manager.on('connect', (publicKey) => {
  // Update your state
  state.connected = true;
  state.publicKey = publicKey;
});

​
Extension Points

​
Custom Wallet Adapters

Create custom adapters for non-standard wallets: 
import { BaseWalletAdapter } from '@hermis/solana-headless-adapter-base';

class CustomWalletAdapter extends BaseWalletAdapter {
  async connect() {
    // Custom connection logic
  }

  async disconnect() {
    // Custom disconnection logic
  }

  async signTransaction(transaction) {
    // Custom signing logic
  }
}

​
Custom Hooks (React)

Build custom hooks on top of the provided ones: 
import { useWallet, useConnection } from '@hermis/solana-headless-react';

function useBalance() {
  const { publicKey } = useWallet();
  const { connection } = useConnection();

  // Custom balance fetching logic
  return balance;
}

​
Middleware Pattern

Intercept and modify transactions: 
const signAndSend = async (transaction) => {
  // Pre-process
  const modified = await middleware(transaction);

  // Sign and send
  const signature = await wallet.signAndSendTransaction(modified);

  // Post-process
  await onTransactionSent(signature);

  return signature;
};

​
Performance Considerations

​
Bundle Size

Adapter Base

~20KB gzipped

React

~25KB gzipped

​
Optimization Strategies

  1. Tree Shaking: Import only what you need 
    import { useWallet } from '@hermis/solana-headless-react';
// Not: import * as Hermis from '@hermis/solana-headless-react';
  2. Lazy Loading: Load wallet adapters on demand 
    const adapters = await import('@solana/wallet-adapter-wallets');
  3. Connection Reuse: Share connection instances 
    import { Connection, clusterApiUrl } from '@solana/web3.js';

const connection = new Connection(clusterApiUrl('devnet'));
// Reuse this connection throughout your app

​
Security Architecture

​
Key Management

  • Private keys never leave the wallet
  • Signing happens in the wallet extension
  • SDK only receives signatures

​
Transaction Verification

// Always verify transaction details before signing
const verifyTransaction = (tx: Transaction) => {
  // Check recipient, amount, etc.
  return isValid;
};

​
Network Security

import { Connection } from '@solana/web3.js';

// Use trusted RPC endpoints
const connection = new Connection('https://your-trusted-rpc.com');

​
What’s Next?

Wallet Management

Learn about wallet lifecycle and management

Transactions

Understand transaction handling

API Reference

Explore the API documentation

Examples

See complete implementations