# 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

```mermaid
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
```

<!-- Clicking support if we ever want it
    click EventEmitter "https://example.com/docs/EventEmitter" "Go to EventEmitter documentation"
    click BaseStore "https://example.com/docs/BaseStore" "View BaseStore documentation"
    click StoreInMemory "https://example.com/docs/StoreInMemory" "View StoreInMemory documentation"
    click StoreIndexedDB "https://example.com/docs/StoreIndexedDB" "View StoreIndexedDB documentation"
    click StoreSQLite "https://example.com/docs/StoreSQLite" "View StoreSQLite documentation"
    click BaseWallet "https://example.com/docs/BaseWallet" "View BaseWallet documentation"
    click WalletP2PKH "https://example.com/docs/WalletP2PKH" "View WalletP2PKH documentation"
    click WalletHD "https://example.com/docs/WalletHD" "View WalletHD documentation"
    click WalletXO "https://example.com/docs/WalletXO" "View WalletXO documentation"
    click BaseBlockchain "https://example.com/docs/BaseBlockchain" "View BaseBlockchain documentation"
    click BlockchainInMemory "https://example.com/docs/BlockchainInMemory" "View BlockchainInMemory documentation"
    click BlockchainElectrum "https://example.com/docs/BlockchainElectrum" "View BlockchainElectrum documentation"
-->