{"id":31737887,"url":"https://github.com/osamikoyo/leviathan","last_synced_at":"2025-10-09T09:46:42.028Z","repository":{"id":309147368,"uuid":"1033582532","full_name":"osamikoyo/leviathan","owner":"osamikoyo","description":"distributed database system with sqlite","archived":false,"fork":false,"pushed_at":"2025-08-21T04:24:54.000Z","size":84,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-08-21T06:48:46.549Z","etag":null,"topics":["distributed","distributed-systems","go","golang","grpc","rabbitmq","sqlite3"],"latest_commit_sha":null,"homepage":"","language":"Go","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/osamikoyo.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":"2025-08-07T03:38:59.000Z","updated_at":"2025-08-21T04:24:58.000Z","dependencies_parsed_at":"2025-08-10T07:05:36.179Z","dependency_job_id":"9d2e597e-ee20-4734-867f-85c6f92b73f2","html_url":"https://github.com/osamikoyo/leviathan","commit_stats":null,"previous_names":["osamikoyo/leviathan"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/osamikoyo/leviathan","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/osamikoyo%2Fleviathan","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/osamikoyo%2Fleviathan/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/osamikoyo%2Fleviathan/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/osamikoyo%2Fleviathan/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/osamikoyo","download_url":"https://codeload.github.com/osamikoyo/leviathan/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/osamikoyo%2Fleviathan/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279001115,"owners_count":26083022,"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-10-09T02:00:07.460Z","response_time":59,"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":["distributed","distributed-systems","go","golang","grpc","rabbitmq","sqlite3"],"created_at":"2025-10-09T09:46:40.686Z","updated_at":"2025-10-09T09:46:42.022Z","avatar_url":"https://github.com/osamikoyo.png","language":"Go","readme":"# Leviathan\n\n[![Go Report Card](https://goreportcard.com/badge/github.com/osamikoyo/leviathan)](https://goreportcard.com/report/github.com/osamikoyo/leviathan)\n[![Go Version](https://img.shields.io/badge/go-1.25+-00ADD8?style=flat\u0026logo=go)](https://golang.org)\n[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)\n\nLeviathan is a distributed database system built on top of SQLite, designed for high availability and horizontal scaling. It uses a heart-node architecture where the heart service acts as a coordinator and load balancer, while node services handle the actual database operations.\n\n## 🏗️ Architecture\n\n```\n┌─────────────────┐    ┌──────────────┐    ┌─────────────────┐\n│   Client App    │───▶│ Heart Service │───▶│   RabbitMQ      │\n│                 │    │ (Coordinator) │    │ (Write Queue)   │\n└─────────────────┘    └──────────────┘    └─────────────────┘\n                               │                       │\n                               ▼                       ▼\n                    ┌─────────────────┐    ┌─────────────────┐\n                    │   Node 1        │    │   Consumer      │\n                    │   (SQLite)      │    │   Services      │\n                    └─────────────────┘    └─────────────────┘\n                    ┌─────────────────┐\n                    │   Node 2        │\n                    │   (SQLite)      │\n                    └─────────────────┘\n                    ┌─────────────────┐\n                    │   Node 3        │\n                    │   (SQLite)      │\n                    └─────────────────┘\n```\n\n## ✨ Features\n\n- **High Availability**: Multiple node instances with health checking\n- **Load Balancing**: Intelligent request routing based on node load\n- **Async Writes**: Write operations are queued through RabbitMQ for consistency\n- **Sync Reads**: Read operations are load-balanced across healthy nodes\n- **gRPC Communication**: High-performance inter-service communication\n- **Prometheus Metrics**: Built-in monitoring and observability\n- **Graceful Shutdown**: Proper resource cleanup and connection handling\n- **Configuration Management**: YAML-based configuration with validation\n\n## 🚀 Quick Start\n\n### Prerequisites\n\n- Go 1.25+\n- [Task](https://taskfile.dev/) (task runner)\n- RabbitMQ\n- Protocol Buffers compiler (`protoc`)\n- Docker (optional, for containerized deployment)\n\n### Installation\n\n```bash\ngit clone https://github.com/osamikoyo/leviathan.git\ncd leviathan\ntask setup\n```\n\n### Configuration\n\nCopy and modify the example configurations:\n\n```bash\ncp configs/examples/heart.yaml heart_config.yaml\ncp configs/examples/node1.yaml node_config.yaml\n```\n\n### Running Services\n\n1. **Start RabbitMQ**:\n   ```bash\n   docker run -d --name rabbitmq -p 5672:5672 -p 15672:15672 rabbitmq:3-management\n   ```\n\n2. **Start Heart Service**:\n   ```bash\n   task run-heart\n   ```\n\n3. **Start Node Services**:\n   ```bash\n   task run-node\n   ```\n\n## 🛠️ Development\n\n### Available Task Commands\n\n```bash\ntask                     # Show all available tasks\ntask build              # Build both services\ntask test               # Run tests\ntask test-coverage      # Run tests with coverage\ntask lint               # Run linter\ntask fmt                # Format code\ntask proto              # Generate protobuf code\ntask clean              # Clean build artifacts\ntask ci                 # Full CI pipeline\ntask all                # Complete development pipeline\n\n# Infrastructure tasks\ntask start-rabbitmq     # Start RabbitMQ container\ntask stop-rabbitmq      # Stop RabbitMQ container\n```\n\n### Project Structure\n\n```\n.\n├── cmd/                 # Application entry points\n│   ├── heart/          # Heart service main\n│   └── node/           # Node service main\n├── config/             # Configuration handling\n├── configs/            # Configuration examples\n├── errors/             # Common error definitions\n├── health/             # Health checking system\n├── heart/              # Heart service implementation\n├── heartcore/          # Heart business logic\n├── heartserver/        # Heart gRPC server\n├── logger/             # Logging utilities\n├── metrics/            # Prometheus metrics\n├── models/             # Data models\n├── producer/           # RabbitMQ producer\n├── proto/              # Protocol buffer definitions\n├── retrier/            # Retry logic utilities\n└── taskfile.yml       # Task runner configuration\n```\n\n## 📊 Monitoring\n\nLeviathan exposes Prometheus metrics on the following endpoints:\n\n- `leviathan_requests_total` - Total number of requests\n- `leviathan_request_duration_seconds` - Request processing time\n- `leviathan_active_connections` - Current active connections\n- `leviathan_request_errors_total` - Total number of errors\n- `leviathan_node_health_status` - Node health status (1=healthy, 0=unhealthy)\n\n## 🔧 Configuration\n\n### Heart Service Configuration\n\n```yaml\n# Heart service configuration\naddr: \"localhost:8080\"                    # Listen address\nrabbitmq_url: \"amqp://guest:guest@localhost:5672/\"\nexchange: \"leviathan_writes\"               # RabbitMQ exchange\nqueue_name: \"write_requests\"              # Queue name\n\n# Node addresses for load balancing\nnodes:\n  - \"localhost:9001\"\n  - \"localhost:9002\"\n  - \"localhost:9003\"\n\n# Health checking configuration\nhealth_check_interval: \"30s\"             # Health check frequency\nhealth_check_timeout: \"5s\"               # Health check timeout\n\n# Request handling configuration\nmax_retries: 3                           # Maximum retry attempts\nrequest_timeout: \"30s\"                   # Request timeout\n```\n\n## 🤝 Contributing\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add some amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\n### Code Standards\n\n- Follow Go conventions and best practices\n- Write tests for new functionality\n- Run `task ci` before submitting PRs\n- Keep functions under 100 lines\n- Use meaningful variable and function names\n\n## 📝 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## 🙏 Acknowledgments\n\n- SQLite team for the awesome embedded database\n- gRPC team for high-performance RPC framework\n- RabbitMQ team for reliable messaging\n- Prometheus team for monitoring solution\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fosamikoyo%2Fleviathan","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fosamikoyo%2Fleviathan","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fosamikoyo%2Fleviathan/lists"}