xo-stack/packages/docs/src/architecture.md

XO Stack Architecture Documentation

Overview

The XO Stack is a comprehensive framework designed for building applications on the Bitcoin Cash (BCH) network. It employs an Object-Oriented architecture that prioritizes modularity, extensibility, and developer experience.

Core Design Philosophy

Object-Oriented Architecture

The XO Stack adopts an Object-Oriented design for several key reasons:

1. Encapsulation and Data Privacy

   • Internal implementation details are hidden from consumers
   • State management is contained within specific classes
   • Clear boundaries between different system components
   • Reduced likelihood of state-related bugs

2. Adapter Pattern Benefits

   • Pluggable components that can be swapped without changing application code
   • Easy to add new implementations for different environments
   • Testing simplified through mock adapters
   • Reduced vendor lock-in

3. Developer Experience

   • Strong IDE support with autocomplete suggestions
   • Type safety when using TypeScript
   • Clear inheritance hierarchies
   • Intuitive method discovery through class interfaces

4. Code Organization

   • Logical grouping of related functionality
   • Clear separation of concerns
   • Consistent patterns across the codebase
   • Easier to maintain and extend

Core Components

EventEmitter

The EventEmitter serves as the foundational building block of the XO Stack. It provides:

• Pub/sub functionality for component communication
• Framework-agnostic event handling
• Seamless integration with frontend frameworks
• Consistent event patterns across the stack

Base Classes

BaseStore

The storage adapter interface that defines how data is persisted:

• Abstract methods for CRUD operations
• Consistent API across storage implementations
• Transaction support
• Query capabilities

Available implementations:

• StoreInMemory: Volatile storage for testing and development
• StoreIndexedDB: Browser-based persistent storage
• StoreSQLite: Native application storage solution

BaseBlockchain

Defines the interface for interacting with the BCH network:

• Network communication abstraction
• Transaction broadcasting
• Block and transaction monitoring
• Network status management

Available implementations:

• BlockchainInMemory: Mock blockchain for testing
• BlockchainElectrum: Production-ready Electrum protocol client

BaseWallet

Represents different wallet types for managing BCH:

• Key management
• Address generation
• Transaction signing
• Balance tracking

Available implementations:

• WalletP2PKH: Basic Pay-to-Public-Key-Hash wallet
• WalletHD: Hierarchical Deterministic wallet implementation
  • WalletXO: Extended HD wallet with XO-specific features

Architecture Diagram

graph LR
    EventEmitter --> BaseStore
    BaseStore --> StoreInMemory
    BaseStore --> StoreIndexedDB
    BaseStore --> StoreSQLite
    BaseStore --> StoreHTTP

    EventEmitter --> BaseWallet
    BaseWallet --> WalletP2PKH
    BaseWallet --> WalletHD
    BaseWallet --> WalletMultisig

    EventEmitter --> BaseBlockchain
    BaseBlockchain --> BlockchainInMemory
    BaseBlockchain --> BlockchainElectrum
    BaseBlockchain --> BlockchainChaingraph
    BaseBlockchain --> BlockchainP2PNetwork

    EventEmitter --> BaseP2PChannel
    BaseP2PChannel --> P2PChannelLibP2P

    EventEmitter --> BaseRates
    BaseRates --> RatesComposite
    BaseRates --> RatesCoinbase
    BaseRates --> RatesOracle

    EventEmitter --> BaseBCMR
    BaseBCMR --> BCMRHTTP
    BaseBCMR --> BCMRComposite