Sphere

Sphere is a Protobuf-first Go service framework for definition-driven development. Start modular monolithic, scale to microservices. Define once, generate everything with rapid tooling.

Sphere comes with powerful code generation tools to create proto files, Swagger documents, TypeScript clients, and more, speeding up your development workflow.

Features

• Protocol-First Design

  Define once in Protobuf, generate everywhere. Get Go handlers, HTTP routing, client SDKs, and OpenAPI docs from a single source of truth.

• Pragmatic Monolith Template

  Start simple with Gin + Wire + Ent in a single binary. Clean architecture that scales from MVP to microservices when needed.

• Complete Code Generation

  Automated toolchain with protoc-gen-sphere ecosystem: server stubs, HTTP routing, field binding, typed errors, and validation.

• Structured Error Handling

  Define error enums in protobuf with automatic HTTP status mapping. Get consistent JSON responses with code, reason, and message.

• Full-Stack Development

  Generate Swagger documentation, TypeScript SDKs, and validation schemas. Bridge backend and frontend with type safety.

• Developer Experience

  sphere-cli for project scaffolding, Makefile workflows, and clean project structure. Focus on business logic, not boilerplate.

Command line Tool

• sphere-cli : A command-line tool for sphere project management.
• protoc-gen-route : A plugin for generating routing code from .proto files.
• protoc-gen-sphere : A plugin for generating HTTP server code from .proto files.
• protoc-gen-sphere-binding : A plugin for replacing go struct binding tags with proto field options.
• protoc-gen-sphere-errors : A plugin for generating error handling code from .proto files.

Layout template

• sphere-layout : Default sphere project layout template.
• sphere-simple-layout : A simplified version of the Sphere project layout template.

Documentation

• Quick Start Guide : A step-by-step guide to setting up a new Sphere project.
• API Definitions : Guidelines for writing API definitions .proto files in Sphere.
• Error Handling : Guidelines for error handling in Sphere applications.
• Logging : How to set up and use logging in Sphere applications.

Core Dependencies

• Web Framework: gin
• Dependency Injection: wire
• ORM: ent
• Docs Generation: swag
• Protobuf management: buf
• Build Tool: make

License

Sphere is released under the MIT license. See LICENSE for details.