# HSuite Developer Documentation
Enterprise-grade and Degen-grade Web3 Infrastructure Platform
## Overview
HSuite is a comprehensive Web3 infrastructure platform that bridges the gap between enterprise and retail blockchain solutions. Our ecosystem provides battle-tested tools and services designed for both businesses (B2B) and consumers (B2C), enabling seamless blockchain integration, management, and scalability on the Hedera Hashgraph network.
The platform is built with a security-first approach, offering robust transaction processing, node operation management, and distributed systems capabilities that power everything from NFT marketplaces to decentralized exchanges.
## Repository Structure
This monorepo is organized into two primary sections:
```
/
├── libs/ # Core libraries and reusable modules
└── apps/ # Standalone applications
```
### Core Libraries (`/libs`)
Our libraries follow a modular architecture with clear separation of concerns and are designed to be used independently or as part of the larger ecosystem.
#### Authentication & Security
* **`auth`** - Core authentication module supporting both Web2 and Web3 authentication methods, including API-key, JWT, and wallet-based authentication
* **`auth-types`** - Type definitions for authentication systems, security contexts, and identity verification
* **`api-key`** - API key management, validation, and security controls with rate limiting capabilities
#### Client & Network
* **`client`** - Main HSUITE client module for interacting with the ecosystem with connection pooling and retry mechanisms
* **`client-types`** - Type definitions for client operations, requests, and responses
* **`smart-network`** - Smart Network ecosystem implementation and node management with peer discovery
* **`smart-network-types`** - Type definitions for network operations, topology, and peer information
* **`hashgraph`** - Hedera Hashgraph integration and interaction layer for transaction creation and account management
* **`hashgraph-types`** - Type definitions for Hashgraph operations, accounts, and consensus services
#### Security & Access Control
* **`throttler`** - Rate limiting and DDoS protection mechanisms with configurable rules
* **`throttler-types`** - Type definitions for throttling operations and rate limit configurations
* [**`validators`**](https://github.com/HSuiteNetwork/smart-engines/blob/develop/docs/developers/libs/validators/README.md) - 🔍 [**Comprehensive NestJS validation library**](https://github.com/HSuiteNetwork/smart-engines/blob/develop/docs/developers/libs/validators/README.md) for Hedera Hashgraph transactions and operations with multi-entity support, REST API, and type-safe validation rules
* 📋 [**Implementation Guide**](https://github.com/HSuiteNetwork/smart-engines/blob/develop/docs/developers/libs/validators/src/README.md) - Detailed source code documentation, architecture, and usage examples
* 🏗️ **Core Components**: ValidatorsService, ValidatorsController, ValidatorsModule with full NestJS integration
* ✅ **Supported Operations**: Consensus topics, token operations, account management, and transaction validation
* 🌐 **REST API**: Complete HTTP endpoints for validator management and rule configuration
* [**`validators-types`**](https://docs.hsuite.network/developers/libs/validators-types) - 🏷️ [**Complete TypeScript type system**](https://docs.hsuite.network/developers/libs/validators-types) for validators with comprehensive interfaces, models, and enums
* 📝 [**Type System Documentation**](https://github.com/HSuiteNetwork/smart-engines/blob/develop/docs/developers/libs/validators-types/src/README.md) - Detailed interface definitions, model implementations, and design patterns
* 🎯 **Namespace Architecture**: Organized hierarchy by domain (IConsensus, IToken, IAccount)
* 🔧 **Model Implementations**: Concrete validation classes with factory and strategy patterns
* 📊 **Transaction Enums**: Standardized transaction type constants for type safety
* **`license-manager`** - License generation, verification, and management for enterprise deployments
#### User Management
* **`users`** - User management functionality and account operations with profile management
* **`users-types`** - Type definitions for user data structures and account states
* **`subscriptions`** - Subscription and service tier management with billing integration
* **`subscriptions-types`** - Type definitions for subscription models and payment structures
#### Distributed Systems
* **`dkg`** - Distributed Key Generation for secure multi-party operations and threshold signatures
* **`dkg-types`** - Type definitions for DKG operations and key sharing protocols
* **`smartnode-sdk`** - SDK for interacting with SmartNode infrastructure, including node provisioning
* **`ipfs`** - IPFS integration for decentralized storage with file management capabilities
* **`cluster`** - Clustering and distributed processing capabilities for horizontal scaling
#### System Utilities
* **`smart-config`** - Configuration management and environment handling with secure storage
* **`smart-transaction`** - Transaction processing and management with atomicity guarantees
* **`smart-transaction-types`** - Type definitions for transactions and multi-step operations
* **`health`** - Health checks and system monitoring with alerting capabilities
* **`helpers`** - Common utility functions and shared tools for cross-module operations
* **`snapshots`** - System state snapshot management for backup and restore operations
* **`mirrors`** - Mirror node integration and data access with query optimization
* **`trust-score`** - Trust scoring and reputation systems for network participants
* **`_tools`** - Command-line utilities for development, build, and deployment workflows including library building and NPM publishing
### Applications (`/apps`)
Each application in the ecosystem is a standalone service with specific functionality while maintaining interoperability with the entire suite.
#### Infrastructure & Node Services
* **`smart-node`** - Core node infrastructure service providing:
* Network operations and Hedera interaction
* Transaction processing and management
* Blockchain state synchronization
* Performance monitoring and optimization
* High-availability configuration
* **`smart-app`** - Application management and orchestration service featuring:
* Microservice deployment and configuration
* Service discovery and routing
* Health monitoring and auto-remediation
* Application metrics and analytics
* **`smart-registry`** - Service registry and discovery system providing:
* Dynamic service registration
* Health checking and availability monitoring
* Configuration management
* Service dependency tracking
#### NFT Ecosystem
* **`nft-exchange`** - Complete NFT marketplace with:
* Collection management and curation
* Royalty systems and creator benefits
* Trading mechanisms and order books
* Auction systems and price discovery
* Metadata management and verification
#### DeFi Infrastructure
* **`exchange`** - Decentralized exchange (DEX) platform featuring:
* Token swapping and liquidity pools
* Automated Market Maker (AMM) functionality
* Advanced trading features
* Order book management
* Price discovery mechanisms
* **`cross-chain-exchange`** - Multi-chain bridge and trading system:
* Cross-chain asset transfers
* Liquidity management across networks
* Security protocols for multi-chain operations
* Transaction verification and finality
#### Project Launch & Governance
* **`launchpad`** - Token and project launch platform with:
* Token sale management
* Vesting schedule implementation
* KYC/AML compliance tools
* Fair launch mechanisms
* Project milestone tracking
* **`dao`** - Decentralized Autonomous Organization platform:
* Governance and voting systems
* Treasury management
* Proposal creation and execution
* Delegate management
* On-chain and off-chain governance integration
#### Enterprise Tools
* **`multisig`** - Multi-signature wallet and approval system:
* Multi-party transaction approval
* Configurable signature thresholds
* Transaction proposal workflow
* Key management and recovery
* Role-based access controls
* **`token-manager`** - Token creation and management system:
* Token issuance and configuration
* Asset management and distribution
* Compliance and regulatory tools
* Supply management and monitoring
* Token burn and mint capabilities
## Technical Stack
* **Backend Framework**: NestJS with Express adapters
* **Language**: TypeScript 4.x+ with strict typing
* **Primary Database**: MongoDB with Mongoose ODM
* **Cache Database**: Redis with clustering support
* **Message Queue**: Bull for background processing
* **Blockchain Network**: Hedera Hashgraph (@hashgraph/sdk v2.51.0+)
* **Distributed Storage**: IPFS with kubo-rpc-client
* **Containerization**: Docker with multi-platform support
* **Monitoring**: OpenTelemetry with Prometheus integration
* **Documentation**: Swagger/OpenAPI and Compodoc
* **Testing**: Jest with MongoDB memory server
## Development Guidelines
### Library Development
1. **Type Safety**
* Use corresponding `-types` libraries for consistent interfaces
* Define clear interfaces and types with JSDoc documentation
* Implement runtime validation with class-validator
2. **Modularity**
* Design for independent importability with minimal dependencies
* Minimize cross-dependencies between modules
* Follow dependency injection patterns for testability
* Use NestJS providers and services pattern
3. **Documentation**
* Include comprehensive JSDoc comments for all public methods
* Provide usage examples with TypeScript code
* Mark experimental features clearly with @beta or @experimental tags
* Document error handling and edge cases
### Application Development
1. **Security-First Approach**
* Follow blockchain security best practices and OWASP guidelines
* Implement proper input validation at all entry points
* Handle edge cases and failure scenarios
* Use rate limiting and implement appropriate access controls
* Follow principle of least privilege
2. **Testing Strategy**
* Maintain high unit test coverage for business logic
* Implement integration testing for service interactions
* Perform security and performance testing
* Use test doubles and mocks appropriately
* Test for race conditions in distributed systems
3. **Integration Patterns**
* Ensure cross-application compatibility through standard interfaces
* Design for shared resource management
* Follow consistent API patterns across the ecosystem
* Implement circuit breakers for external dependencies
* Use standardized error handling and logging
## Installation & Setup
Each library can be installed individually:
```bash
npm install @hsuite/[library-name]
# Example: npm install @hsuite/client
```
For multiple libraries, you can install them together:
```bash
npm install @hsuite/client @hsuite/auth @hsuite/smart-config
```
For application setup, refer to the README in each application directory for specific instructions.
### Quick Start
```typescript
// Example: Initializing the client
import { HsuiteClient } from '@hsuite/client';
const client = new HsuiteClient({
apiKey: 'your-api-key',
environment: 'development'
});
// Using the client to interact with the Hedera network
const accountInfo = await client.network.getAccountInfo('0.0.12345');
```
## Documentation
Generate documentation for any module:
```bash
# Generate documentation for a specific module
cd libs/[library-name] # or apps/[app-name]
yarn compodoc
# Generate documentation with coverage information
yarn compodoc:coverage
# Generate documentation for the entire project
yarn generate:compodocs
```
Comprehensive API documentation is available in the `documentation/` and `docs/` directories after generation.
## Contributing
We welcome contributions from the community. Please read our [Contributing Guidelines](https://github.com/HSuiteNetwork/smart-engines/blob/develop/docs/developers/CONTRIBUTING.md) for details on our code of conduct and the process for submitting pull requests.
The contribution process includes:
1. Fork the repository and create your branch from `main`
2. Install dependencies and set up your development environment
3. Make your changes with appropriate tests and documentation
4. Submit a pull request with a clear description of the changes
Before submitting your PR:
* Ensure tests pass: `yarn test`
* Verify linting standards: `yarn lint`
* Generate documentation: `yarn compodoc`
* Make sure all CI checks pass
## License
This project is part of the HSuite ecosystem and is covered by its license terms.
***
Built with ❤️ by the HSuite Team
Copyright © 2025 HSuite. All rights reserved.
