# 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`**](/developers/libs/validators-types.md) - 🏷️ [**Complete TypeScript type system**](/developers/libs/validators-types.md) 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.
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.hsuite.network/developers.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
