forge

README

🔨 Forge

Forge™ is a backend framework, and Forge Cloud™ is its AI cloud offering, maintained by XRAPH™.

Enterprise-Grade Web Framework for Go

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.

---

🚀 Quick Start

Installation

# Install the Forge CLI
go install github.com/xraph/forge/cmd/forge@latest

# Verify installation
forge --version

Forge Your First App

# Initialize a new project
forge init my-app

# Start the development server
forge dev

Minimal Example

package main

import "github.com/xraph/forge"

func main() {
    // Create app with default configuration
    app := forge.NewApp(forge.AppConfig{
        Name:        "my-app",
        Version:     "1.0.0",
        Environment: "development",
        HTTPAddress: ":8080",
    })

    // Register routes
    router := app.Router()
    router.GET("/", func(ctx forge.Context) error {
        return ctx.JSON(200, map[string]string{
            "message": "Hello, Forge v2!",
        })
    })

    // Run the application (blocks until SIGINT/SIGTERM)
    app.Run()
}

Built-in endpoints:

• /_/info - Application information
• /_/metrics - Prometheus metrics
• /_/health - Health checks

---

✨ Key Features

🏗️ Core Framework

• ✅ Dependency Injection - Type-safe container with service lifecycle
• ✅ HTTP Router - Fast, lightweight routing with middleware support
• ✅ Middleware - Auth, CORS, logging, rate limiting, and more
• ✅ Configuration - YAML/JSON/TOML support with environment variable override
• ✅ Observability - Structured logging, metrics, distributed tracing
• ✅ Health Checks - Automatic discovery and reporting
• ✅ Lifecycle Management - Graceful startup and shutdown

🔌 Extensions

Extension	Description	Status
AI	LLM integration, agents, inference engine	✅
Auth	Multi-provider authentication (OAuth, JWT, SAML)	✅
Cache	Multi-backend caching (Redis, Memcached, In-Memory)	✅
Consensus	Raft consensus for distributed systems	✅
Database	SQL (Postgres, MySQL, SQLite) + MongoDB support	✅
Events	Event bus and event sourcing	✅
GraphQL	GraphQL server with schema generation	✅
gRPC	gRPC server with reflection	✅
HLS	HTTP Live Streaming	✅
Kafka	Apache Kafka integration	✅
MCP	Model Context Protocol	✅
MQTT	MQTT broker and client	✅
orpc	ORPC transport protocol	✅
Queue	Message queue management	✅
Search	Full-text search (Elasticsearch, Typesense)	✅
Storage	Multi-backend storage (S3, GCS, Local)	✅
Streaming	WebSocket, SSE, WebRTC	✅
WebRTC	Real-time peer-to-peer communication	✅

🛠️ CLI Tools

• ✅ Project Scaffolding - Initialize new projects with templates
• ✅ Code Generation - Generate handlers, controllers, and services
• ✅ Database Migrations - Schema management with versioning
• ✅ Interactive Prompts - Arrow-key navigation, multi-select
• ✅ Server Management - Development server with hot reload
• ✅ Testing - Built-in test runner and coverage reports

---

📖 Documentation

Getting Started

• Installation Guide
• Quick Start
• Architecture
• Examples

Core Concepts

• Application Lifecycle
• Dependency Injection
• Routing
• Middleware
• Configuration
• Observability

Extensions

• AI Extension - LLM integration and AI agents
• Auth Extension - Authentication providers
• Database Extension - SQL and NoSQL databases
• GraphQL Extension - GraphQL server
• gRPC Extension - gRPC services
• Streaming Extension - WebSocket and SSE

CLI Reference

• CLI Documentation
• Commands Reference

---

🌟 Why Forge?

Production-Ready

Forge is built for production from day one:

• ✅ Graceful Shutdown - Proper resource cleanup on SIGTERM
• ✅ Health Monitoring - Automatic discovery and reporting
• ✅ Observability - Metrics, logging, and distributed tracing
• ✅ Error Handling - Comprehensive error management
• ✅ Security - Built-in security best practices

Developer Experience

• ✅ Type Safety - Generics and compile-time guarantees
• ✅ Zero Config - Sensible defaults with full customization
• ✅ Hot Reload - Instant feedback during development
• ✅ CLI Tools - Fast project scaffolding and generation
• ✅ Rich Docs - Comprehensive documentation and examples

Performance

• ✅ Low Latency - Optimized HTTP router and middleware
• ✅ Efficient Routing - Trie-based path matching
• ✅ Concurrent Safe - Thread-safe components
• ✅ Memory Efficient - Minimal allocations

Extensible

• ✅ Extension System - Modular, composable extensions
• ✅ Plugin Architecture - Easy to add custom functionality
• ✅ Multi-Backend - Switch implementations without code changes
• ✅ Middleware Chain - Powerful middleware composition

---

🏛️ Architecture

// Application Structure
app := forge.NewApp(forge.AppConfig{
    Name:        "my-service",
    Version:     "1.0.0",
    Environment: "production",
    
    // Extensions
    Extensions: []forge.Extension{
        database.NewExtension(database.Config{
            Databases: []database.DatabaseConfig{
                {
                    Name: "primary",
                    Type: database.TypePostgres,
                    DSN:  "postgres://localhost/mydb",
                },
            },
        }),
        
        auth.NewExtension(auth.Config{
            Provider: "oauth2",
            // ... auth configuration
        }),
    },
})

// Dependency Injection
forge.RegisterSingleton(app.Container(), "userService", func(c forge.Container) (*UserService, error) {
    db, err := database.GetSQL(c)
    if err != nil {
        return nil, err
    }
    logger := forge.Must[forge.Logger](c, "logger")
    return NewUserService(db, logger), nil
})

// Routing
router := app.Router()
router.GET("/users/:id", getUserHandler)
router.POST("/users", createUserHandler)

// Run
app.Run()

---

🧩 Extension Example

Using the AI Extension

package main

import (
    "github.com/xraph/forge"
    "github.com/xraph/forge/extensions/ai"
)

func main() {
    app := forge.NewApp(forge.AppConfig{
        Extensions: []forge.Extension{
            ai.NewExtension(ai.Config{
                LLMProviders: map[string]ai.LLMProviderConfig{
                    "openai": {
                        APIKey: os.Getenv("OPENAI_API_KEY"),
                        Model:  "gpt-4",
                    },
                },
            }),
        },
    })

    // Access AI service via DI using helper function
    aiService, err := ai.GetAIService(app.Container())
    if err != nil {
        log.Fatal(err)
    }

    // Use in your handlers
    router := app.Router()
    router.POST("/chat", func(ctx forge.Context) error {
        result, err := aiService.Chat(ctx, ai.ChatRequest{
            Messages: []ai.Message{
                {Role: "user", Content: "Hello!"},
            },
        })
        if err != nil {
            return err
        }
        return ctx.JSON(200, result)
    })

    app.Run()
}

---

🛠️ Development

Prerequisites

• Go 1.24+ - Latest Go compiler
• Make - Build tool (optional but recommended)

Build

# Build the CLI
make build

# Build with debug symbols
make build-debug

# Build for all platforms
make release

Run Tests

# Run all tests
make test

# Run with coverage
make test-coverage

# Run specific package
go test ./extensions/ai/...

Code Quality

# Format code
make fmt

# Run linter
make lint

# Fix linting issues
make lint-fix

# Run security scan
make security-scan

# Check vulnerabilities
make vuln-check

Development Server

# Start development server
forge dev

# Start with hot reload
forge dev --watch

# Start on custom port
forge dev --port 3000

---

📊 Project Status

Core Framework

• ✅ Dependency Injection - Production ready
• ✅ HTTP Router - Fast, lightweight
• ✅ Middleware System - Comprehensive
• ✅ Configuration - Multi-format support
• ✅ Observability - Metrics, logging, tracing
• ✅ Health Checks - Automatic discovery
• ✅ CLI Tools - Full-featured CLI

Extensions (17 total)

Production Ready (14):

• ✅ AI - LLM integration and agents
• ✅ Auth - Multi-provider authentication
• ✅ Cache - Multi-backend caching
• ✅ Consensus - Raft consensus
• ✅ Database - SQL and NoSQL
• ✅ Events - Event bus and sourcing
• ✅ GraphQL - GraphQL server
• ✅ gRPC - gRPC services
• ✅ HLS - HTTP Live Streaming
• ✅ Kafka - Apache Kafka
• ✅ MCP - Model Context Protocol
• ✅ MQTT - MQTT broker
• ✅ Storage - Multi-backend storage
• ✅ Streaming - WebSocket, SSE, WebRTC

In Progress (3):

• 🔄 Queue - Message queue management
• 🔄 Search - Full-text search
• 🔄 orpc - ORPC transport protocol

---

🧪 Examples

The examples/ directory contains production-ready examples:

• Minimal App - Hello World
• Configuration - Config management
• Database - Database integration
• Auth - Authentication
• GraphQL - GraphQL server
• gRPC - gRPC services
• WebRTC - Real-time communication
• MCP - Model Context Protocol
• AI Agents - AI agent system

---

🤝 Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

Development Workflow

# Fork and clone
git clone https://github.com/your-username/forge.git
cd forge

# Install tools
make install-tools

# Make changes
# ...

# Run tests
make test

# Check code quality
make ci

# Commit with conventional commits
git commit -m "feat: add new feature"

Conventional Commits

feat: add new feature
fix: fix bug in router
docs: update documentation
style: format code
refactor: refactor DI container
perf: optimize routing performance
test: add tests for middleware
chore: update dependencies

---

📄 License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

---

🙏 Acknowledgments

Built with ❤️ by Rex Raphael

Special thanks to:

• Bun - SQL ORM
• Uptrace - Observability platform
• Chi - Router inspiration
• All contributors and maintainers

---

🔗 Links

• Documentation - Comprehensive docs
• GitHub - Source code
• Issues - Bug reports
• Discussions - Questions and ideas
• Examples - Code examples
• CLI Reference - CLI documentation

---

📜 License

Forge uses a dual-licensing approach:

Forge Core & Most Extensions: MIT License

The core framework and most extensions are licensed under the MIT License - one of the most permissive open source licenses.

✅ Use freely for:

• Commercial products and services
• Personal projects
• Closed-source applications
• Modifications and distributions

See the LICENSE file for full terms.

AI Extension: Commercial Source-Available License

The AI Extension (extensions/ai/) uses a more restrictive Commercial Source-Available License.

✅ Free for:

• Personal projects
• Educational purposes
• Research and academic use
• Internal evaluation (90 days)

❌ Commercial license required for:

• Production deployments
• Commercial products/services
• Revenue-generating applications

See extensions/ai/LICENSE for full terms or LICENSING.md for the complete licensing guide.

Need a commercial license? Contact: licensing@xraph.com

---

📈 Roadmap

v2.1 (Q1 2025)

• Complete remaining extensions (Queue, Search, orpc)
• Enhanced AI agent orchestration
• Real-time collaboration features
• Advanced monitoring dashboard

v2.2 (Q2 2025)

• Kubernetes operator
• Helm charts and deployment automation
• Advanced caching strategies
• Performance optimization pass

v3.0 (Q3 2025)

• TypeScript/Node.js runtime
• Multi-language code generation
• Enhanced observability platform
• Enterprise features (SLA, auditing, compliance)

---

Ready to build? Get Started →