{"id":25833057,"url":"https://github.com/kenzycodex/distributed-storage","last_synced_at":"2026-05-09T23:08:01.270Z","repository":{"id":279736587,"uuid":"939735434","full_name":"kenzycodex/distributed-storage","owner":"kenzycodex","description":"DistributedStorage - A robust and scalable distributed storage system with intelligent load balancing capabilities built with Java.","archived":false,"fork":false,"pushed_at":"2025-02-27T06:12:48.000Z","size":245,"stargazers_count":0,"open_issues_count":6,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-02-27T06:19:07.464Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kenzycodex.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":"ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2025-02-27T02:48:01.000Z","updated_at":"2025-02-27T06:11:55.000Z","dependencies_parsed_at":"2025-02-27T06:19:15.092Z","dependency_job_id":"3d2b641c-b9c9-480a-a438-f636b11c7ccb","html_url":"https://github.com/kenzycodex/distributed-storage","commit_stats":null,"previous_names":["kenzycodex/distributed-storage"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kenzycodex%2Fdistributed-storage","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kenzycodex%2Fdistributed-storage/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kenzycodex%2Fdistributed-storage/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kenzycodex%2Fdistributed-storage/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kenzycodex","download_url":"https://codeload.github.com/kenzycodex/distributed-storage/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":241261474,"owners_count":19936037,"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","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":[],"created_at":"2025-02-28T22:39:51.550Z","updated_at":"2026-05-09T23:08:01.262Z","avatar_url":"https://github.com/kenzycodex.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# DistributedStorage\n\n![License](https://img.shields.io/badge/license-MIT-blue.svg)\n![Spring Boot](https://img.shields.io/badge/Spring%20Boot-3.1.0-green.svg)\n![Java](https://img.shields.io/badge/Java-17-orange.svg)\n![Build Status](https://img.shields.io/github/workflow/status/kenzycodex/distributed-storage/Java%20CI%20with%20Maven/main)\n![Issues](https://img.shields.io/github/issues/kenzycodex/distributed-storage)\n![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)\n\nA robust and scalable Java distributed storage system with an intelligent load balancer for managing file storage across multiple nodes.\n\n## Overview\n\nDistributedStorage is a high-performance distributed file storage system designed for reliability, scalability, and fault tolerance. The system dynamically distributes files across multiple storage nodes using advanced load balancing strategies while providing a unified API for file operations.\n\n### Key Features\n\n- **Dynamic Load Balancing**: Multiple algorithms including round-robin, least-connection, and weighted strategies\n- **Automatic Health Monitoring**: Continuous health checks with automatic failover\n- **Real-time Metrics**: Comprehensive performance tracking for system and nodes\n- **Horizontal Scalability**: Seamlessly add or remove storage nodes without downtime\n- **File Redundancy**: Optional file replication for enhanced data durability\n- **RESTful API**: Simple yet powerful API for file operations\n- **Containerization Support**: Designed for Docker/Kubernetes environments\n\n## Architecture\n\nDistributedStorage consists of three main components:\n\n1. **Load Balancer**: Receives client requests and intelligently routes them to appropriate storage nodes\n2. **Storage Nodes**: Independent servers that store and manage files\n3. **Metadata Service**: Tracks file locations and system configuration\n\n\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"docs/images/architecture-diagram.png\" alt=\"Architecture Diagram\" width=\"700\"/\u003e\n\u003c/div\u003e\n\n## 🚀 Quick Start\n\n### Prerequisites\n\n- **Java 17+**\n- **Docker \u0026 Docker Compose**\n- **Maven 3.6+**\n\n### Option 1: Docker (Recommended)\n\n```bash\n# Clone the repository\ngit clone https://github.com/kenzycodex/distributed-storage.git\ncd distributed-storage\n\n# Start all services\ndocker-compose up -d\n\n# Check service status\ndocker-compose ps\n```\n\n**Services Available:**\n- Load Balancer: http://localhost:8080\n- Storage Nodes: http://localhost:8081, :8082, :8083\n- Grafana Dashboard: http://localhost:3000 (admin/admin)\n- Prometheus: http://localhost:9090\n\n### Option 2: Manual Setup\n\n```bash\n# 1. Clone and build\ngit clone https://github.com/kenzycodex/distributed-storage.git\ncd distributed-storage\nmvn clean package\ncd storage-node \u0026\u0026 mvn clean package \u0026\u0026 cd ..\n\n# 2. Setup MySQL\nmysql -u root -p\nCREATE DATABASE loadbalancer;\nCREATE USER 'loadbalancer'@'localhost' IDENTIFIED BY 'loadbalancer';\nGRANT ALL PRIVILEGES ON loadbalancer.* TO 'loadbalancer'@'localhost';\n\n# 3. Start Load Balancer\njava -jar target/load-balancer-1.0-SNAPSHOT.jar\n\n# 4. Start Storage Nodes (in separate terminals)\ncd storage-node\njava -jar target/storage-node-1.0-SNAPSHOT.jar --server.port=8081 --storage.node.name=node-1\njava -jar target/storage-node-1.0-SNAPSHOT.jar --server.port=8082 --storage.node.name=node-2\njava -jar target/storage-node-1.0-SNAPSHOT.jar --server.port=8083 --storage.node.name=node-3\n```\n\n## 📝 Usage Examples\n\n```bash\n# Upload a file\ncurl -X POST -H \"X-User-ID: 1\" -F \"file=@test.txt\" http://localhost:8080/api/v1/files/upload\n\n# Download a file (replace 123 with actual file ID from upload response)\ncurl -X GET -H \"X-User-ID: 1\" http://localhost:8080/api/v1/files/123 --output downloaded.txt\n\n# Delete a file\ncurl -X DELETE -H \"X-User-ID: 1\" http://localhost:8080/api/v1/files/123\n\n# Check system health\ncurl http://localhost:8080/actuator/health\n\n# View metrics\ncurl http://localhost:8080/api/v1/metrics/stats\n```\n\n## 📚 Documentation\n\n| Document | Description |\n|----------|-------------|\n| [**Developer Setup**](DEVELOPER_SETUP.md) | Complete setup, testing, and development guide |\n| [**API Reference**](docs/api.md) | Comprehensive API documentation |\n| [**Configuration**](docs/configuration.md) | Configuration options and environment variables |\n| [**Load Balancing**](docs/load-balancing-strategies.md) | Available load balancing algorithms |\n| [**Implementation Phases**](docs/IMPLEMENTATION_PHASES.md) | Development roadmap and phases |\n| [**Contributing**](CONTRIBUTING.md) | How to contribute to the project |\n\n## ⚡ Current Status\n\n✅ **Phase 1 Complete**: Core storage node implementation\n🔄 **Phase 2 In Progress**: File metadata persistence\n📋 **Next**: Enhanced node management and comprehensive testing\n\n**What's Working:**\n- ✅ Complete load balancer with 5 strategies\n- ✅ Storage nodes with file operations\n- ✅ Automatic node registration and heartbeat\n- ✅ Health monitoring and metrics\n- ✅ Docker deployment\n- ✅ RESTful API\n\n**Production Ready Features:**\n- Load balancing across multiple storage nodes\n- File upload, download, and deletion\n- System monitoring and health checks\n- Containerized deployment\n\n## Monitoring \u0026 Metrics\n\nThe system collects comprehensive metrics including:\n\n- Request counts (total, successful, failed)\n- Response times (average, 95th percentile, 99th percentile)\n- Node-specific statistics\n- Connection counts per node\n- Storage utilization\n\nMetrics are accessible via REST endpoints and can be integrated with Prometheus and Grafana using the provided configurations.\n\n## Development\n\n### Project Structure\n\n```\ndistributed-storage/\n├── src/\n│   ├── main/\n│   │   ├── java/com/loadbalancer/\n│   │   │   ├── config/           # Configuration classes\n│   │   │   ├── controller/       # REST controllers\n│   │   │   ├── exception/        # Custom exceptions\n│   │   │   ├── model/            # Data models\n│   │   │   ├── repository/       # Data access layer\n│   │   │   ├── service/          # Business logic\n│   │   │   ├── strategy/         # Load balancing algorithms\n│   │   │   └── LoadBalancerApplication.java\n│   │   └── resources/            # Configuration files\n│   └── test/                     # Test classes\n├── .github/                      # GitHub integration\n│   ├── ISSUE_TEMPLATE/           # Issue templates\n│   └── workflows/                # CI/CD workflows\n├── docker/                       # Docker configurations\n├── docs/                         # Documentation\n└── scripts/                      # Utility scripts\n```\n\n### Building from Source\n\n```bash\n# Clone the repository\ngit clone https://github.com/kenzycodex/distributed-storage.git\ncd distributed-storage\n\n# Build with Maven\nmvn clean package\n\n# Run tests\nmvn test\n```\n\n## Contributing\n\nWe welcome contributions from the community! Please check our [Contributing Guidelines](CONTRIBUTING.md) before submitting issues or pull requests.\n\n### How to Contribute\n\n1. Fork the repository\n2. Create a feature branch\n3. Commit your changes\n4. Push to your branch\n5. Create a pull request\n\nFor more details, please read our [Contributing Guidelines](CONTRIBUTING.md).\n\n### Code of Conduct\n\nPlease note that this project adheres to a [Code of Conduct](CODE_OF_CONDUCT.md). By participating, you are expected to uphold this code.\n\n## Community\n\nWe use GitHub Discussions to connect with our users and contributors. Check out our [Discussions page](https://github.com/kenzycodex/distributed-storage/discussions) to ask questions, share ideas, or get help. See our [discussion guidelines](DISCUSSIONS.md) for more information.\n\n### Reporting Security Issues\n\nFor security-related issues, please refer to our [Security Policy](SECURITY.md) instead of filing a public issue.\n\n## Versioning \u0026 Changelog\n\nThis project follows [Semantic Versioning](https://semver.org/).\n\nSee our [Changelog](CHANGELOG.md) for a detailed history of changes.\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Acknowledgments\n\nWe're grateful to all [contributors](ACKNOWLEDGEMENTS.md) who have helped shape this project.\n\n## Contact \u0026 Support\n\n- **Issues**: For bugs and feature requests, please [create an issue](https://github.com/kenzycodex/distributed-storage/issues/new/choose)\n- **Discussions**: For questions and general discussion, use [GitHub Discussions](https://github.com/kenzycodex/distributed-storage/discussions)\n\nFor other inquiries, please open an issue on the GitHub repository.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkenzycodex%2Fdistributed-storage","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkenzycodex%2Fdistributed-storage","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkenzycodex%2Fdistributed-storage/lists"}