{"id":30117432,"url":"https://github.com/puneetkakkar/nexuskit","last_synced_at":"2025-08-10T10:44:04.244Z","repository":{"id":70280271,"uuid":"440216449","full_name":"puneetkakkar/nexuskit","owner":"puneetkakkar","description":"NexusKit is a comprehensive, extensible toolkit for building, connecting, and scaling modern microservices. From service discovery and load balancing to CQRS, gRPC, GraphQL, and resilience patterns, NexusKit gives you everything you need to create robust, production-ready distributed systems fast","archived":false,"fork":false,"pushed_at":"2025-07-18T04:16:01.000Z","size":2057,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-07-18T08:04:13.843Z","etag":null,"topics":["cloud","consul","grpc-client","http-client","loadbalancer","microservices","microservices-library","service-discovery","service-registry","toolkit","zookeeper"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/puneetkakkar.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2021-12-20T15:22:57.000Z","updated_at":"2025-07-18T04:21:29.000Z","dependencies_parsed_at":"2025-02-24T12:17:49.551Z","dependency_job_id":"bb4543e8-a0e4-45b4-b680-21537a3e73fc","html_url":"https://github.com/puneetkakkar/nexuskit","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/puneetkakkar/nexuskit","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/puneetkakkar%2Fnexuskit","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/puneetkakkar%2Fnexuskit/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/puneetkakkar%2Fnexuskit/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/puneetkakkar%2Fnexuskit/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/puneetkakkar","download_url":"https://codeload.github.com/puneetkakkar/nexuskit/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/puneetkakkar%2Fnexuskit/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":269712986,"owners_count":24463216,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-10T02:00:08.965Z","response_time":71,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cloud","consul","grpc-client","http-client","loadbalancer","microservices","microservices-library","service-discovery","service-registry","toolkit","zookeeper"],"created_at":"2025-08-10T10:44:03.522Z","updated_at":"2025-08-10T10:44:04.211Z","avatar_url":"https://github.com/puneetkakkar.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# NexusKit: The Complete Microservices Toolkit\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Node.js](https://img.shields.io/badge/Node.js-18+-green.svg)](https://nodejs.org/)\n[![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue.svg)](https://www.typescriptlang.org/)\n[![NestJS](https://img.shields.io/badge/NestJS-10.0+-red.svg)](https://nestjs.com/)\n[![Nx](https://img.shields.io/badge/Nx-17.0+-purple.svg)](https://nx.dev/)\n\nA production-ready, enterprise-grade microservices toolkit built with NestJS and Nx. NexusKit provides a robust, scalable, and maintainable foundation for building distributed systems with built-in service discovery, load balancing, dynamic scaling, multi-tenancy support, and extensible libraries for CQRS, gRPC, GraphQL, resilience, and more.\n\n## 🚀 Features\n\n### Core Architecture\n\n- **🏗️ Monorepo Structure**: Built with Nx for efficient development and build processes\n- **🔍 Service Discovery**: Automatic service registration and discovery using Consul or ZooKeeper\n- **⚖️ Load Balancing**: Intelligent load balancing with configurable strategies\n- **🔄 Dynamic Scaling**: Support for multiple instances of the same service with dynamic port allocation\n- **🌐 HTTP Client**: Declarative HTTP service clients with automatic service resolution\n- **🔄 Health Checks**: Built-in health monitoring with configurable timeouts\n- **🛡️ Graceful Shutdown**: Proper application lifecycle management\n- **📊 Real-time Monitoring**: Live service status and health tracking\n\n### Service Infrastructure\n\n- **📡 Service Registry**: Centralized service registration and management via Consul or ZooKeeper\n- **🔧 Configuration Management**: Flexible configuration loading from multiple sources\n- **📊 Service Monitoring**: Real-time service health and status tracking\n- **🔄 Retry Mechanisms**: Robust error handling with configurable retry policies\n- **🎯 Metadata Management**: Comprehensive service metadata and tagging system\n- **🔄 Auto-scaling**: Dynamic service instance management with load balancing\n\n### Development Experience\n\n- **🔧 TypeScript First**: Full TypeScript support with strict typing\n- **📦 Modular Design**: Clean separation of concerns with reusable libraries\n- **🧪 Testing Ready**: Built-in testing infrastructure with Jest\n- **📝 Code Quality**: ESLint and Prettier integration for consistent code style\n- **🚀 Hot Reload**: Development server with automatic reloading\n- **🛠️ Management Scripts**: Automated scripts for service lifecycle management\n\n## 🏗️ Architecture Overview\n\nThis project follows a modular microservice architecture with the following key components:\n\n```\n├── apps/                    # Application services\n│   ├── service-1/          # Example microservice 1 (port 3333)\n│   └── service-2/          # Example microservice 2 (port 3334)\n├── libs/                   # Shared libraries\n│   ├── bootstrap/          # Configuration management\n│   ├── client/             # HTTP client framework\n│   ├── cloud/              # Cloud-native abstractions\n│   ├── common/             # Shared utilities and interfaces\n│   ├── consul/             # Service discovery and registry\n│   ├── loadbalancer/       # Load balancing strategies\n│   └── zookeeper/          # ZooKeeper service discovery and registry\n├── scripts/                # Service management scripts\n│   ├── start-service.sh    # Dynamic service startup\n│   ├── stop-service.sh     # Service shutdown\n│   ├── status.sh           # Service status monitoring\n│   └── test-loadbalancer.sh # Load balancing tests\n```\n\n### Key Libraries\n\n- **`@nexuskit/bootstrap`**: Configuration management with file-based loading\n- **`@nexuskit/client`**: Declarative HTTP service clients with service discovery\n- **`@nexuskit/cloud`**: Cloud-native service abstractions and registry management\n- **`@nexuskit/common`**: Shared utilities, interfaces, and common functionality\n- **`@nexuskit/consul`**: Consul integration for service discovery and health checks\n- **`@nexuskit/loadbalancer`**: Configurable load balancing with multiple strategies\n- **`@nexuskit/zookeeper`**: ZooKeeper integration for service discovery and registry\n\n## 🛠️ Technology Stack\n\n| Component            | Technology       | Version    |\n| -------------------- | ---------------- | ---------- |\n| **Runtime**          | Node.js          | 18+        |\n| **Framework**        | NestJS           | 10.0+      |\n| **Language**         | TypeScript       | 5.0+       |\n| **Build System**     | Nx               | 17.0+      |\n| **Service Registry** | Consul/ZooKeeper | 1.21+/3.8+ |\n| **HTTP Client**      | Got              | 11.8.2     |\n| **Testing**          | Jest             | 29.0+      |\n| **Linting**          | ESLint           | 8.0+       |\n| **Formatting**       | Prettier         | 3.0+       |\n\n## 📦 Installation\n\n### Prerequisites\n\n- Node.js 18 or higher\n- npm or yarn package manager\n- Docker (for Consul)\n\n### Quick Start\n\n1. **Clone the repository**\n\n   ```bash\n   git clone https://github.com/your-username/mt-microservices-arch.git\n   cd mt-microservices-arch\n   ```\n\n2. **Install dependencies**\n\n   ```bash\n   npm install\n   # or\n   yarn install\n   ```\n\n3. **Start Service Registry (required for service discovery)**\n\n   ```bash\n   # Using Consul (recommended)\n   docker run -d --name consul -p 8500:8500 hashicorp/consul:latest\n\n   # Or using ZooKeeper\n   docker run -d --name zookeeper -p 2181:2181 zookeeper:3.8\n\n   # Or install locally\n   # Follow instructions at https://www.consul.io/docs/install or https://zookeeper.apache.org/doc/current/zookeeperStarted.html\n   ```\n\n4. **Start the development servers**\n\n   ```bash\n   # Start all services\n   npm run start\n\n   # Start specific service\n   npm run start service-1\n   npm run start service-2\n   ```\n\n## 🚀 Usage\n\n### Dynamic Service Management\n\nThe project includes powerful scripts for managing multiple service instances:\n\n#### Start Multiple Service Instances\n\n```bash\n# Start 3 instances of service-2 starting from port 3334\n./scripts/start-service.sh service-2 3 3334\n\n# Start 2 instances of service-1 starting from port 3333\n./scripts/start-service.sh service-1 2 3333\n\n# Start 1 instance of service-2 on default port 3334\n./scripts/start-service.sh service-2\n```\n\n#### Monitor Service Status\n\n```bash\n# Check all services\n./scripts/status.sh\n\n# Check specific service\n./scripts/status.sh service-2\n```\n\n#### Test Load Balancing\n\n```bash\n# Test load balancing for service-2 with 10 requests\n./scripts/test-loadbalancer.sh service-2 10\n\n# Test load balancing for service-1 with 5 requests\n./scripts/test-loadbalancer.sh service-1 5\n```\n\n#### Test ZooKeeper Integration\n\n```bash\n# Test ZooKeeper service discovery and registration\n./scripts/test-zookeeper.sh\n```\n\n#### Stop Services\n\n```bash\n# Stop all service-2 instances\n./scripts/stop-service.sh service-2\n\n# Stop all service-1 instances\n./scripts/stop-service.sh service-1\n```\n\n### Creating a New Service\n\n1. **Generate a new service using Nx**\n\n   ```bash\n   npx nx generate @nx/nest:application my-service\n   ```\n\n2. **Configure the service module**\n\n   ```typescript\n   import { Module } from '@nestjs/common';\n   import { BootstrapModule } from '@nexuskit/bootstrap';\n   import { ClientModule } from '@nexuskit/client';\n   import { CloudModule } from '@nexuskit/cloud';\n   import { ConsulModule } from '@nexuskit/consul';\n   import { ZookeeperModule } from '@nexuskit/zookeeper';\n   import { LoadBalancerModule } from '@nexuskit/loadbalancer';\n\n   @Module({\n     imports: [\n       BootstrapModule.forRoot(),\n       // Using Consul\n       ConsulModule.forRoot({\n         host: 'localhost',\n         port: '8500',\n         promisify: true,\n         secure: false,\n       }),\n       // Or using ZooKeeper\n       ZookeeperModule.forRoot({\n         host: 'localhost:2181',\n         retryAttempts: 6000,\n       }),\n       CloudModule.forRoot({\n         registry: {\n           discoverer: 'consul', // or 'zookeeper'\n           service: {\n             name: 'my-service',\n             address: 'localhost',\n             port: parseInt(process.env.PORT) || 3000,\n           },\n           discovery: {\n             type: 'http',\n             http: `http://192.168.1.201:${process.env.PORT || 3000}/api/health`,\n             interval: 10,\n             timeout: '5s',\n             failFast: false,\n             scheme: 'http',\n           },\n           heartbeat: {\n             enabled: false,\n             ttlInSeconds: 30,\n           },\n         },\n       }),\n       ClientModule.forRoot(),\n       LoadBalancerModule.forRoot(),\n     ],\n   })\n   export class AppModule {}\n   ```\n\n### Using HTTP Service Clients\n\n```typescript\nimport { Controller, Get } from '@nestjs/common';\nimport { HttpClient, HttpServiceClient } from '@nexuskit/client';\n\n@Controller()\nexport class AppController {\n  @HttpServiceClient('service-2', {\n    timeout: 5000, // 5 second timeout\n    retry: 2, // retry 2 times\n  })\n  serviceInstance: HttpClient;\n\n  @Get('/service-2')\n  async getServiceData() {\n    try {\n      const svcData = await this.serviceInstance.get('api/');\n      return svcData.body;\n    } catch (error) {\n      return {\n        error: 'Service-2 is not available',\n        message: error.message,\n        timestamp: new Date().toISOString(),\n      };\n    }\n  }\n}\n```\n\n### Configuration Management\n\nCreate a `bootstrap.yaml` file in your service directory:\n\n```yaml\nconfig:\n  service:\n    name: 'My Service'\n```\n\n## 🔧 Configuration\n\n### Environment Variables\n\n| Variable         | Description    | Default     |\n| ---------------- | -------------- | ----------- |\n| `PORT`           | Service port   | 3333        |\n| `NODE_ENV`       | Environment    | development |\n| `CONSUL_HOST`    | Consul host    | localhost   |\n| `CONSUL_PORT`    | Consul port    | 8500        |\n| `ZOOKEEPER_HOST` | ZooKeeper host | localhost   |\n| `ZOOKEEPER_PORT` | ZooKeeper port | 2181        |\n\n### Service Configuration\n\nEach service can be configured through:\n\n- Environment variables\n- Bootstrap configuration files (`bootstrap.yaml`, `bootstrap.json`)\n- Runtime configuration injection\n\n### Health Check Configuration\n\n```typescript\ndiscovery: {\n  type: 'http',\n  http: `http://192.168.1.201:${process.env.PORT || 3333}/api/health`,\n  interval: 10,        // Check every 10 seconds\n  timeout: '5s',       // 5 second timeout\n  failFast: false,     // Don't fail fast on health check failure\n  scheme: 'http',\n}\n```\n\n## 🧪 Testing\n\n### Unit Tests\n\n```bash\n# Run all tests\nnpm run test\n\n# Run tests for specific service\nnpm run test service-1\n\n# Run e2e tests\nnpm run e2e\n\n# Run affected tests\nnpm run affected:test\n```\n\n### Load Balancing Tests\n\n```bash\n# Test load balancing with multiple instances\n./scripts/test-loadbalancer.sh service-2 20\n\n# Expected output shows requests distributed across instances:\n# Request 1: abc123 (port 3334)\n# Request 2: def456 (port 3335)\n# Request 3: abc123 (port 3334)\n# ...\n```\n\n## 📊 Monitoring and Health Checks\n\nThe framework provides comprehensive health monitoring:\n\n- **Service Health**: Automatic health check registration with Consul\n- **Dynamic Timeouts**: Configurable health check timeouts (5s default)\n- **Service Discovery**: Real-time service availability tracking\n- **Load Balancer Health**: Health-aware load balancing across instances\n- **Instance Monitoring**: Individual instance health tracking\n\n### Health Check Endpoints\n\nEach service automatically exposes a health endpoint:\n\n```bash\n# Check service health\ncurl http://localhost:3333/api/health\n# Response: {\"status\":\"ok\",\"timestamp\":\"2025-07-05T00:30:00.000Z\"}\n\n# Check service-2 health\ncurl http://localhost:3334/api/health\n# Response: {\"status\":\"ok\",\"timestamp\":\"2025-07-05T00:30:00.000Z\"}\n```\n\n### Service Registry Health Monitoring\n\n#### Consul Health Monitoring\n\n```bash\n# View all services in Consul\ncurl http://localhost:8500/v1/agent/services | jq\n\n# View health checks\ncurl http://localhost:8500/v1/agent/checks | jq\n\n# View healthy service instances\ncurl \"http://localhost:8500/v1/health/service/service-2?passing=true\" | jq\n```\n\n#### ZooKeeper Health Monitoring\n\n```bash\n# View all services in ZooKeeper\ndocker exec zookeeper zkCli.sh -server localhost:2181 ls /swft-mt-service\n\n# View service details\ndocker exec zookeeper zkCli.sh -server localhost:2181 get /swft-mt-service/service__service-2__1.0.0-\u003cuuid\u003e\n\n# View service instances\ndocker exec zookeeper zkCli.sh -server localhost:2181 ls /swft-mt-service/service__service-2__1.0.0-\u003cuuid\u003e\n```\n\n## 🔒 Security\n\n- **Graceful Shutdown**: Proper signal handling and cleanup\n- **Error Handling**: Comprehensive error handling with retry mechanisms\n- **Service Isolation**: Service-level isolation and security boundaries\n- **Configuration Security**: Secure configuration management\n- **Health Check Security**: Configurable health check endpoints\n\n## 🚀 Production Deployment\n\n### Docker Deployment\n\n```bash\n# Build services\nnpx nx build service-1\nnpx nx build service-2\n\n# Run with Docker Compose\ndocker-compose up -d\n```\n\n### Kubernetes Deployment\n\n```yaml\napiVersion: apps/v1\nkind: Deployment\nmetadata:\n  name: service-1\nspec:\n  replicas: 3\n  selector:\n    matchLabels:\n      app: service-1\n  template:\n    metadata:\n      labels:\n        app: service-1\n    spec:\n      containers:\n        - name: service-1\n          image: your-registry/service-1:latest\n          ports:\n            - containerPort: 3333\n          env:\n            - name: PORT\n              value: '3333'\n```\n\n## 🤝 Contributing\n\nWe welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.\n\n### Development Setup\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Add tests for new functionality\n5. Ensure all tests pass\n6. Submit a pull request\n\n### Code Style\n\nThis project uses:\n\n- ESLint for code linting\n- Prettier for code formatting\n- TypeScript strict mode\n- Conventional commit messages\n\n## 📄 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## 🆘 Support\n\n- **Documentation**: [Wiki](https://github.com/your-username/mt-microservices-arch/wiki)\n- **Issues**: [GitHub Issues](https://github.com/your-username/mt-microservices-arch/issues)\n- **Discussions**: [GitHub Discussions](https://github.com/your-username/mt-microservices-arch/discussions)\n\n## 🙏 Acknowledgments\n\n- [NestJS](https://nestjs.com/) - Progressive Node.js framework\n- [Nx](https://nx.dev/) - Build system with first-class support for many frontend and backend technologies\n- [Consul](https://www.consul.io/) - Service mesh solution providing a full featured control plane\n- [ZooKeeper](https://zookeeper.apache.org/) - Distributed coordination service for distributed applications\n- [TypeScript](https://www.typescriptlang.org/) - Typed JavaScript at scale\n\n---\n\n**Built with ❤️ for the microservices community**\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpuneetkakkar%2Fnexuskit","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpuneetkakkar%2Fnexuskit","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpuneetkakkar%2Fnexuskit/lists"}