{"id":34046182,"url":"https://github.com/xraph/forge","last_synced_at":"2026-06-16T03:00:49.994Z","repository":{"id":318376339,"uuid":"1017605283","full_name":"xraph/forge","owner":"xraph","description":"A very opionated distributed backend framework with everything in between.","archived":false,"fork":false,"pushed_at":"2026-06-04T02:34:53.000Z","size":230954,"stargazers_count":7,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-05T23:02:47.139Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://forge.xraph.com","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/xraph.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","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,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-07-10T19:52:24.000Z","updated_at":"2026-06-04T02:34:56.000Z","dependencies_parsed_at":"2025-10-06T21:22:21.281Z","dependency_job_id":"67bea82f-f7bf-46c3-8c42-22f33017a250","html_url":"https://github.com/xraph/forge","commit_stats":null,"previous_names":["xraph/forge"],"tags_count":688,"template":false,"template_full_name":null,"purl":"pkg:github/xraph/forge","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xraph%2Fforge","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xraph%2Fforge/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xraph%2Fforge/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xraph%2Fforge/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/xraph","download_url":"https://codeload.github.com/xraph/forge/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xraph%2Fforge/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34388669,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-16T02:00:06.860Z","response_time":126,"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":[],"created_at":"2025-12-13T23:39:07.139Z","updated_at":"2026-06-16T03:00:49.964Z","avatar_url":"https://github.com/xraph.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🔨 Forge\n\nForge™ is a backend framework, and Forge Cloud™ is its AI cloud offering, maintained by XRAPH™.\n\n**Enterprise-Grade Web Framework for Go**\n\n\u003e Build scalable, maintainable, and observable Go applications with Forge—the modern framework that brings clean architecture, dependency injection, and powerful extensions to your production services.\n\n[![Go Version](https://img.shields.io/badge/Go-1.24+-00ADD8?style=flat\u0026logo=go)](https://golang.org/)\n[![Go Report Card](https://goreportcard.com/badge/github.com/xraph/forge)](https://goreportcard.com/report/github.com/xraph/forge)\n[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)\n[![GitHub Stars](https://img.shields.io/github/stars/xraph/forge)](https://github.com/xraph/forge)\n[![CI](https://github.com/xraph/forge/actions/workflows/go.yml/badge.svg)](https://github.com/xraph/forge/actions/workflows/go.yml)\n\n---\n\n\n## 🚀 Quick Start\n\n### Installation\n\n```bash\n# Install the Forge CLI\ngo install github.com/xraph/forge/cmd/forge@latest\n\n# Verify installation\nforge --version\n```\n\n### Forge Your First App\n\n```bash\n# Initialize a new project\nforge init my-app\n\n# Start the development server\nforge dev\n```\n\n### Minimal Example\n\n```go\npackage main\n\nimport \"github.com/xraph/forge\"\n\nfunc main() {\n    // Create app with default configuration\n    app := forge.NewApp(forge.AppConfig{\n        Name:        \"my-app\",\n        Version:     \"1.0.0\",\n        Environment: \"development\",\n        HTTPAddress: \":8080\",\n    })\n\n    // Register routes\n    router := app.Router()\n    router.GET(\"/\", func(ctx forge.Context) error {\n        return ctx.JSON(200, map[string]string{\n            \"message\": \"Hello, Forge!\",\n        })\n    })\n\n    // Run the application (blocks until SIGINT/SIGTERM)\n    app.Run()\n}\n```\n\n**Built-in endpoints:**\n- `/_/info` - Application information\n- `/_/metrics` - Prometheus metrics\n- `/_/health` - Health checks\n\n---\n\n## ✨ Key Features\n\n### 🏗️ Core Framework\n\n- **✅ Dependency Injection** - Type-safe container with service lifecycle\n- **✅ HTTP Router** - Fast, lightweight routing with middleware support\n- **✅ Middleware** - Auth, CORS, logging, rate limiting, and more\n- **✅ Configuration** - YAML/JSON/TOML support with environment variable override\n- **✅ Observability** - Structured logging, metrics, distributed tracing\n- **✅ Health Checks** - Automatic discovery and reporting\n- **✅ Lifecycle Management** - Graceful startup and shutdown\n\n### 🔌 Extensions\n\n| Extension | Description | Status |\n|-----------|-------------|--------|\n| **AI** | LLM integration, agents, inference engine | ✅ |\n| **Auth** | Multi-provider authentication (OAuth, JWT, SAML) | ✅ |\n| **Cache** | Multi-backend caching (Redis, Memcached, In-Memory) | ✅ |\n| **Consensus** | Raft consensus for distributed systems | ✅ |\n| **Database** | SQL (Postgres, MySQL, SQLite) + MongoDB support | ✅ |\n| **Events** | Event bus and event sourcing | ✅ |\n| **GraphQL** | GraphQL server with schema generation | ✅ |\n| **gRPC** | gRPC server with reflection | ✅ |\n| **HLS** | HTTP Live Streaming | ✅ |\n| **Kafka** | Apache Kafka integration | ✅ |\n| **MCP** | Model Context Protocol | ✅ |\n| **MQTT** | MQTT broker and client | ✅ |\n| **orpc** | ORPC transport protocol | ✅ |\n| **Queue** | Message queue management | ✅ |\n| **Search** | Full-text search (Elasticsearch, Typesense) | ✅ |\n| **Storage** | Multi-backend storage (S3, GCS, Local) | ✅ |\n| **Streaming** | WebSocket, SSE, WebRTC | ✅ |\n| **WebRTC** | Real-time peer-to-peer communication | ✅ |\n\n### 🛠️ CLI Tools\n\n- **✅ Project Scaffolding** - Initialize new projects with templates\n- **✅ Code Generation** - Generate handlers, controllers, and services\n- **✅ Database Migrations** - Schema management with versioning\n- **✅ Interactive Prompts** - Arrow-key navigation, multi-select\n- **✅ Server Management** - Development server with hot reload\n- **✅ Testing** - Built-in test runner and coverage reports\n\n---\n\n## 📖 Documentation\n\n### Getting Started\n\n- [**Installation Guide**](docs/content/docs/getting-started/installation.mdx)\n- [**Quick Start**](docs/content/docs/getting-started/quick-start.mdx)\n- [**Architecture**](docs/content/docs/architecture/index.mdx)\n- [**Examples**](examples/)\n\n### Core Concepts\n\n- [**Application Lifecycle**](docs/content/docs/core/lifecycle.mdx)\n- [**Dependency Injection**](docs/content/docs/core/dependency-injection.mdx)\n- [**Routing**](docs/content/docs/core/routing.mdx)\n- [**Middleware**](docs/content/docs/core/middleware.mdx)\n- [**Configuration**](docs/content/docs/core/configuration.mdx)\n- [**Observability**](docs/content/docs/core/observability.mdx)\n\n### Extensions\n\n- [**AI Extension**](extensions/ai/README.md) - LLM integration and AI agents\n- [**Auth Extension**](extensions/auth/README.md) - Authentication providers\n- [**Database Extension**](extensions/database/) - SQL and NoSQL databases\n- [**GraphQL Extension**](extensions/graphql/README.md) - GraphQL server\n- [**gRPC Extension**](extensions/grpc/README.md) - gRPC services\n- [**Streaming Extension**](extensions/streaming/) - WebSocket and SSE\n\n### CLI Reference\n\n- [**CLI Documentation**](cli/README.md)\n- [**Commands Reference**](cmd/forge/COMMANDS.md)\n\n---\n\n## 🌟 Why Forge?\n\n### Production-Ready\n\nForge is built for production from day one:\n\n- **✅ Graceful Shutdown** - Proper resource cleanup on SIGTERM\n- **✅ Health Monitoring** - Automatic discovery and reporting\n- **✅ Observability** - Metrics, logging, and distributed tracing\n- **✅ Error Handling** - Comprehensive error management\n- **✅ Security** - Built-in security best practices\n\n### Developer Experience\n\n- **✅ Type Safety** - Generics and compile-time guarantees\n- **✅ Zero Config** - Sensible defaults with full customization\n- **✅ Hot Reload** - Instant feedback during development\n- **✅ CLI Tools** - Fast project scaffolding and generation\n- **✅ Rich Docs** - Comprehensive documentation and examples\n\n### Performance\n\n- **✅ Low Latency** - Optimized HTTP router and middleware\n- **✅ Efficient Routing** - Trie-based path matching\n- **✅ Concurrent Safe** - Thread-safe components\n- **✅ Memory Efficient** - Minimal allocations\n\n### Extensible\n\n- **✅ Extension System** - Modular, composable extensions\n- **✅ Plugin Architecture** - Easy to add custom functionality\n- **✅ Multi-Backend** - Switch implementations without code changes\n- **✅ Middleware Chain** - Powerful middleware composition\n\n---\n\n## 🏛️ Architecture\n\n```go\n// Application Structure\napp := forge.NewApp(forge.AppConfig{\n    Name:        \"my-service\",\n    Version:     \"1.0.0\",\n    Environment: \"production\",\n    \n    // Extensions\n    Extensions: []forge.Extension{\n        database.NewExtension(database.Config{\n            Databases: []database.DatabaseConfig{\n                {\n                    Name: \"primary\",\n                    Type: database.TypePostgres,\n                    DSN:  \"postgres://localhost/mydb\",\n                },\n            },\n        }),\n        \n        auth.NewExtension(auth.Config{\n            Provider: \"oauth2\",\n            // ... auth configuration\n        }),\n    },\n})\n\n// Dependency Injection\nforge.RegisterSingleton(app.Container(), \"userService\", func(c forge.Container) (*UserService, error) {\n    db, err := database.GetSQL(c)\n    if err != nil {\n        return nil, err\n    }\n    logger := forge.Must[forge.Logger](c, \"logger\")\n    return NewUserService(db, logger), nil\n})\n\n// Routing\nrouter := app.Router()\nrouter.GET(\"/users/:id\", getUserHandler)\nrouter.POST(\"/users\", createUserHandler)\n\n// Run\napp.Run()\n```\n\n---\n\n## 🧩 Extension Example\n\n### Using the AI Extension\n\n```go\npackage main\n\nimport (\n    \"github.com/xraph/forge\"\n    \"github.com/xraph/forge/extensions/ai\"\n)\n\nfunc main() {\n    app := forge.NewApp(forge.AppConfig{\n        Extensions: []forge.Extension{\n            ai.NewExtension(ai.Config{\n                LLMProviders: map[string]ai.LLMProviderConfig{\n                    \"openai\": {\n                        APIKey: os.Getenv(\"OPENAI_API_KEY\"),\n                        Model:  \"gpt-4\",\n                    },\n                },\n            }),\n        },\n    })\n\n    // Access AI service via DI using helper function\n    aiService, err := ai.GetAIService(app.Container())\n    if err != nil {\n        log.Fatal(err)\n    }\n\n    // Use in your handlers\n    router := app.Router()\n    router.POST(\"/chat\", func(ctx forge.Context) error {\n        result, err := aiService.Chat(ctx, ai.ChatRequest{\n            Messages: []ai.Message{\n                {Role: \"user\", Content: \"Hello!\"},\n            },\n        })\n        if err != nil {\n            return err\n        }\n        return ctx.JSON(200, result)\n    })\n\n    app.Run()\n}\n```\n\n---\n\n## 🛠️ Development\n\n### Prerequisites\n\n- **Go 1.24+** - Latest Go compiler\n- **Make** - Build tool (optional but recommended)\n\n### Build\n\n```bash\n# Build the CLI\nmake build\n\n# Build with debug symbols\nmake build-debug\n\n# Build for all platforms\nmake release\n```\n\n### Run Tests\n\n```bash\n# Run all tests\nmake test\n\n# Run with coverage\nmake test-coverage\n\n# Run specific package\ngo test ./extensions/ai/...\n```\n\n### Code Quality\n\n```bash\n# Format code\nmake fmt\n\n# Run linter\nmake lint\n\n# Fix linting issues\nmake lint-fix\n\n# Run security scan\nmake security-scan\n\n# Check vulnerabilities\nmake vuln-check\n```\n\n### Development Server\n\n```bash\n# Start development server\nforge dev\n\n# Start with hot reload\nforge dev --watch\n\n# Start on custom port\nforge dev --port 3000\n```\n\n---\n\n## 📊 Project Status\n\n### Core Framework\n\n- **✅ Dependency Injection** - Production ready\n- **✅ HTTP Router** - Fast, lightweight\n- **✅ Middleware System** - Comprehensive\n- **✅ Configuration** - Multi-format support\n- **✅ Observability** - Metrics, logging, tracing\n- **✅ Health Checks** - Automatic discovery\n- **✅ CLI Tools** - Full-featured CLI\n\n### Extensions (17 total)\n\n**Production Ready (14):**\n- ✅ AI - LLM integration and agents\n- ✅ Auth - Multi-provider authentication\n- ✅ Cache - Multi-backend caching\n- ✅ Consensus - Raft consensus\n- ✅ Database - SQL and NoSQL\n- ✅ Events - Event bus and sourcing\n- ✅ GraphQL - GraphQL server\n- ✅ gRPC - gRPC services\n- ✅ HLS - HTTP Live Streaming\n- ✅ Kafka - Apache Kafka\n- ✅ MCP - Model Context Protocol\n- ✅ MQTT - MQTT broker\n- ✅ Storage - Multi-backend storage\n- ✅ Streaming - WebSocket, SSE, WebRTC\n\n**In Progress (3):**\n- 🔄 Queue - Message queue management\n- 🔄 Search - Full-text search\n- 🔄 orpc - ORPC transport protocol\n\n---\n\n## 🧪 Examples\n\nThe `examples/` directory contains production-ready examples:\n\n- **[Minimal App](examples/minimal-app/)** - Hello World\n- **[Configuration](examples/config-example/)** - Config management\n- **[Database](examples/database-demo/)** - Database integration\n- **[Auth](extensions/auth/examples/auth_example/)** - Authentication\n- **[GraphQL](extensions/graphql/examples/graphql-basic/)** - GraphQL server\n- **[gRPC](examples/grpc-basic/)** - gRPC services\n- **[WebRTC](examples/webrtc/)** - Real-time communication\n- **[MCP](examples/mcp-basic/)** - Model Context Protocol\n- **[AI Agents](examples/ai-agents-demo/)** - AI agent system\n\n---\n\n## 🤝 Contributing\n\nWe welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.\n\n### Development Workflow\n\n```bash\n# Fork and clone\ngit clone https://github.com/your-username/forge.git\ncd forge\n\n# Install tools\nmake install-tools\n\n# Make changes\n# ...\n\n# Run tests\nmake test\n\n# Check code quality\nmake ci\n\n# Commit with conventional commits\ngit commit -m \"feat: add new feature\"\n```\n\n### Conventional Commits\n\n```bash\nfeat: add new feature\nfix: fix bug in router\ndocs: update documentation\nstyle: format code\nrefactor: refactor DI container\nperf: optimize routing performance\ntest: add tests for middleware\nchore: update dependencies\n```\n\n### Releasing\n\nReleases are managed by [Release Please](https://github.com/googleapis/release-please) and a unified GitHub Actions workflow.\n\n**Automated releases** — Push to `main` with conventional commits. Release Please opens a PR with version bumps and changelogs. Merging the PR creates a tag, which triggers the release pipeline.\n\n**Manual releases** — Go to [Actions \u003e Release](../../actions/workflows/release.yml), click **Run workflow**, select the module and version, and optionally enable dry-run mode.\n\nThe release workflow supports:\n- **Main module + CLI**: Builds cross-platform binaries, Docker images, and publishes to Homebrew/Scoop/NFPM via GoReleaser.\n- **Extension modules**: Creates a GitHub release and notifies the Go module proxy.\n- **Dry run**: Validates the full pipeline without publishing.\n- **Skip tests**: For hotfixes when tests have already passed on CI.\n\n---\n\n## 📄 License\nThis project is licensed under the Apache License 2.0 - see the [LICENSE](LICENSE) file for details.\n\n---\n\n## 🙏 Acknowledgments\n\nBuilt with ❤️ by [Rex Raphael](https://github.com/juicycleff)\n\n**Special thanks to:**\n- [Bun](https://github.com/uptrace/bun) - SQL ORM\n- [Uptrace](https://github.com/uptrace/uptrace) - Observability platform\n- [Chi](https://github.com/go-chi/chi) - Router inspiration\n- All contributors and maintainers\n\n---\n\n## 🔗 Links\n\n- **[Documentation](https://forge.dev)** - Comprehensive docs\n- **[GitHub](https://github.com/xraph/forge)** - Source code\n- **[Issues](https://github.com/xraph/forge/issues)** - Bug reports\n- **[Discussions](https://github.com/xraph/forge/discussions)** - Questions and ideas\n- **[Examples](examples/)** - Code examples\n- **[CLI Reference](cli/README.md)** - CLI documentation\n\n---\n\n## 📜 License\n\nForge uses a **dual-licensing approach**:\n\n### Forge Core \u0026 Most Extensions: MIT License\n\nThe core framework and most extensions are licensed under the **MIT License** - one of the most permissive open source licenses.\n\n✅ **Use freely for:**\n- Commercial products and services\n- Personal projects\n- Closed-source applications\n- Modifications and distributions\n\nSee the [LICENSE](LICENSE) file for full terms.\n\n### AI Extension: Commercial Source-Available License\n\nThe AI Extension (`extensions/ai/`) uses a more restrictive **Commercial Source-Available License**.\n\n✅ **Free for:**\n- Personal projects\n- Educational purposes\n- Research and academic use\n- Internal evaluation (90 days)\n\n❌ **Commercial license required for:**\n- Production deployments\n- Commercial products/services\n- Revenue-generating applications\n\nSee [extensions/ai/LICENSE](extensions/ai/LICENSE) for full terms or [LICENSING.md](LICENSING.md) for the complete licensing guide.\n\n**Need a commercial license?** Contact: licensing@xraph.com\n\n---\n\n## 📈 Roadmap\n\n### v2.1 (Q1 2025)\n- [ ] Complete remaining extensions (Queue, Search, orpc)\n- [ ] Enhanced AI agent orchestration\n- [ ] Real-time collaboration features\n- [ ] Advanced monitoring dashboard\n\n### v2.2 (Q2 2025)\n- [ ] Kubernetes operator\n- [ ] Helm charts and deployment automation\n- [ ] Advanced caching strategies\n- [ ] Performance optimization pass\n\n### v3.0 (Q3 2025)\n- [ ] TypeScript/Node.js runtime\n- [ ] Multi-language code generation\n- [ ] Enhanced observability platform\n- [ ] Enterprise features (SLA, auditing, compliance)\n\n---\n\n**Ready to build?** [Get Started →](docs/content/docs/getting-started/quick-start.mdx)\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxraph%2Fforge","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fxraph%2Fforge","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxraph%2Fforge/lists"}