docs: add docs & readme

Author: Patrick-Ehimen

aggregator-core/AUDIT_REPORT.md

@@ -0,0 +1,103 @@
+# Aggregator Core
+
+## Purpose & Key Features
+
+The *aggregator-core* is the backbone of the AggreGate platform, providing essential components for aggregating cryptocurrency order-book data. By interfacing with multiple exchanges, it facilitates high-frequency updates and efficient data processing.
+
+### Key Features:
+- Real-time data aggregation from multiple exchanges.
+- Extensible design allowing integration with new exchanges effortlessly.
+- High-performance order-book handling using configurable strategies.
+- Robust error handling and logging.
+
+## Supported Exchanges & Extensibility Strategy
+
+Currently Supported Exchanges:
+- Binance
+- Bitstamp
+- Bybit
+- Kraken
+- Coinbase
+- Crypto.com
+- OKX
+
+Extensibility Strategy:
+The system is designed with modular exchange connectors, allowing developers to add new exchanges by implementing the `Exchange` interface, following examples in existing modules.
+
+## High-Level Architecture
+
+![Architecture Diagram](../docs/aggregator-core-doc/diagrams/architecture.mmd)
+
+```mermaid
+graph TB
+    subgraph "Aggregator Core"
+        A[Aggregator Module] --> C[Config Module]
+        A --> E[Error Module]
+        A --> T[Types Module]
+        A --> L[Lib Module]
+        
+        C --> E
+        T --> E
+        L --> T
+    end
+    
+    subgraph "External Dependencies"
+        API[External APIs]
+        DB[Database]
+        FS[File System]
+    end
+    
+    A --> API
+    C --> FS
+    A --> DB
+    
+    subgraph "Application Layer"
+        APP[Application]
+    end
+    
+    APP --> A
+    APP --> C
+```
+
+## Quick-Start Example
+
+Here's a quick-start example of how to initialize and start the aggregator:
+```rust
+use aggregator_core::{Aggregator, Config};
+
+fn main() -> Result<(), Box<dyn std::error::Error>> {
+    let config = Config::default();
+    let aggregator = Aggregator::new(config);
+    
+    // Start the aggregator
+    tokio::runtime::Builder::new_multi_thread()
+        .worker_threads(2)
+        .enable_all()
+        .build()
+        .unwrap()
+        .block_on(async {
+            aggregator.start().await?;
+            Ok(())
+        })
+}
+```
+
+## Installation & Build Instructions
+
+To include *aggregator-core* in your project, add the following line to your `Cargo.toml`:
+```toml
+[dependencies]
+aggregator-core = { path = "aggregator-core" }
+```
+
+Use the following command to add it via Cargo:
+```bash
+cargo add aggregator-core
+```
+
+## Links to Deeper Module Docs & API Examples
+
+- [API Examples](../docs/aggregator-core-doc/api-examples.md)
+- [Aggregator Module Documentation](../docs/aggregator-core-doc/modules/aggregator.md)
+- [Lib Module Documentation](../docs/aggregator-core-doc/modules/lib.md)
+

aggregator-core/README.md

@@ -0,0 +1,33 @@
+# Aggregator Core Documentation
+
+## Overview
+
+This documentation provides comprehensive information about the aggregator-core library, including its architecture, modules, and usage examples.
+
+## Structure
+
+- **[Modules](modules/)**: Detailed documentation for each core module
+  - [Aggregator](modules/aggregator.md) - Main aggregation functionality
+  - [Config](modules/config.md) - Configuration management
+  - [Error](modules/error.md) - Error handling and types
+  - [Types](modules/types.md) - Core type definitions
+  - [Lib](modules/lib.md) - Utility functions and helpers
+
+- **[Diagrams](diagrams/)**: Visual representations of system architecture and workflows
+  - [Architecture](diagrams/architecture.mmd) - Overall system architecture
+  - [Data Flow](diagrams/data-flow.mmd) - Data processing flow
+  - [Components](diagrams/components.mmd) - Component relationships
+  - [Error Handling](diagrams/error-handling.mmd) - Error flow and handling
+  - [Config Structure](diagrams/config-structure.mmd) - Configuration hierarchy
+  - [Exchange Workflow](diagrams/exchange-workflow.mmd) - Exchange interaction patterns
+
+- **[API Examples](api-examples.md)**: Practical usage examples and code snippets
+- **[Tests](tests.md)**: Testing documentation and examples
+
+## Quick Start
+
+[Add quick start instructions here]
+
+## Contributing
+
+[Add contribution guidelines here]

docs/aggregator-core-doc/README.md

@@ -0,0 +1,65 @@
+# API Examples
+
+## Basic Usage
+
+### Initializing the Aggregator
+
+```javascript
+// Example initialization
+const aggregator = new Aggregator(config);
+```
+
+### Configuration Examples
+
+```javascript
+// Example configuration
+const config = {
+  // Add configuration examples here
+};
+```
+
+### Data Processing Examples
+
+```javascript
+// Example data processing
+const result = await aggregator.process(inputData);
+```
+
+### Error Handling Examples
+
+```javascript
+// Example error handling
+try {
+  const result = await aggregator.process(inputData);
+} catch (error) {
+  console.error('Processing failed:', error);
+}
+```
+
+## Advanced Usage
+
+### Custom Configurations
+
+[Add advanced configuration examples here]
+
+### Batch Processing
+
+[Add batch processing examples here]
+
+### Integration Examples
+
+[Add integration examples here]
+
+## Common Patterns
+
+### Retry Logic
+
+[Add retry logic examples here]
+
+### Data Validation
+
+[Add data validation examples here]
+
+### Performance Optimization
+
+[Add performance optimization examples here]

docs/aggregator-core-doc/api-examples.md

@@ -0,0 +1,30 @@
+```mermaid
+graph TB
+    subgraph "Aggregator Core"
+        A[Aggregator Module] --> C[Config Module]
+        A --> E[Error Module]
+        A --> T[Types Module]
+        A --> L[Lib Module]
+        
+        C --> E
+        T --> E
+        L --> T
+    end
+    
+    subgraph "External Dependencies"
+        API[External APIs]
+        DB[Database]
+        FS[File System]
+    end
+    
+    A --> API
+    C --> FS
+    A --> DB
+    
+    subgraph "Application Layer"
+        APP[Application]
+    end
+    
+    APP --> A
+    APP --> C
+```

docs/aggregator-core-doc/diagrams/architecture.mmd

@@ -0,0 +1,46 @@
+```mermaid
+classDiagram
+    class Aggregator {
+        +aggregate(data)
+        +configure(config)
+        +process()
+        +getResults()
+    }
+    
+    class Config {
+        +load(source)
+        +validate()
+        +get(key)
+        +set(key, value)
+    }
+    
+    class Error {
+        +handle(error)
+        +log(message)
+        +retry(operation)
+        +classify(error)
+    }
+    
+    class Types {
+        +DataType
+        +ConfigType
+        +ErrorType
+        +ResultType
+    }
+    
+    class Lib {
+        +utils()
+        +helpers()
+        +validators()
+        +transformers()
+    }
+    
+    Aggregator --> Config
+    Aggregator --> Error
+    Aggregator --> Types
+    Aggregator --> Lib
+    Config --> Error
+    Config --> Types
+    Error --> Types
+    Lib --> Types
+```

docs/aggregator-core-doc/diagrams/components.mmd

@@ -0,0 +1,37 @@
+```mermaid
+graph TD
+    Root[Configuration Root] --> App[Application Config]
+    Root --> DB[Database Config]
+    Root --> API[API Config]
+    Root --> Log[Logging Config]
+    
+    App --> AppName[app.name]
+    App --> AppVersion[app.version]
+    App --> AppEnv[app.environment]
+    
+    DB --> DBHost[db.host]
+    DB --> DBPort[db.port]
+    DB --> DBName[db.name]
+    DB --> DBCreds[db.credentials]
+    
+    API --> APIEndpoint[api.endpoint]
+    API --> APITimeout[api.timeout]
+    API --> APIRetries[api.retries]
+    API --> APIKeys[api.keys]
+    
+    Log --> LogLevel[log.level]
+    Log --> LogFormat[log.format]
+    Log --> LogOutput[log.output]
+    
+    subgraph "Configuration Sources"
+        ENV[Environment Variables]
+        FILE[Configuration Files]
+        CLI[Command Line Args]
+        DEFAULT[Default Values]
+    end
+    
+    Root --> ENV
+    Root --> FILE
+    Root --> CLI
+    Root --> DEFAULT
+```

docs/aggregator-core-doc/diagrams/config-structure.mmd

@@ -0,0 +1,23 @@
+```mermaid
+flowchart LR
+    Input[Input Data] --> Validate{Validate}
+    Validate -->|Valid| Transform[Transform Data]
+    Validate -->|Invalid| Error[Error Handler]
+    
+    Transform --> Aggregate[Aggregate Data]
+    Aggregate --> Process[Process Results]
+    Process --> Output[Output Data]
+    
+    Error --> Log[Log Error]
+    Error --> Retry{Retry?}
+    Retry -->|Yes| Transform
+    Retry -->|No| Fail[Fail]
+    
+    subgraph "Configuration"
+        Config[Config Module]
+    end
+    
+    Config --> Validate
+    Config --> Transform
+    Config --> Aggregate
+```

docs/aggregator-core-doc/diagrams/data-flow.mmd

@@ -0,0 +1,33 @@
+```mermaid
+flowchart TD
+    Start[Operation Start] --> Execute[Execute Operation]
+    Execute --> Success{Success?}
+    
+    Success -->|Yes| Complete[Operation Complete]
+    Success -->|No| Classify[Classify Error]
+    
+    Classify --> Retryable{Retryable?}
+    Retryable -->|Yes| Retry[Retry Operation]
+    Retryable -->|No| Fatal[Fatal Error]
+    
+    Retry --> Backoff[Apply Backoff]
+    Backoff --> MaxRetries{Max Retries?}
+    MaxRetries -->|No| Execute
+    MaxRetries -->|Yes| Fatal
+    
+    Fatal --> Log[Log Error]
+    Log --> Notify[Notify Handler]
+    Notify --> Fail[Operation Failed]
+    
+    subgraph "Error Types"
+        ValidationError[Validation Error]
+        NetworkError[Network Error]
+        ConfigError[Config Error]
+        SystemError[System Error]
+    end
+    
+    Classify --> ValidationError
+    Classify --> NetworkError
+    Classify --> ConfigError
+    Classify --> SystemError
+```