Sphere Standard Layout

sphere-layout is the default project template for Sphere. It is a practical, replaceable starter layout that combines mature Go tools instead of hiding them behind a large framework.

The default stack is:

• Protobuf and Buf for API contracts and code generation.
• Gin-compatible HTTP handlers generated by Sphere protoc plugins.
• Ent for database schema and persistence code.
• Wire for dependency injection.
• Swagger/OpenAPI and TypeScript client generation.
• Makefile targets as the day-to-day workflow contract.

These choices are defaults, not hard framework requirements. The layout is intended to show a complete integration path while keeping each third-party tool visible and replaceable.

Workflow Contract

Use make as the primary entrypoint after project creation.

Sphere build tool. Usage: make [target]

  init                 Install tools, download modules, and generate initial artifacts
  install              Install local development tools
  gen/conf             Generate example config
  gen/db               Generate Ent code
  gen/proto            Generate Protobuf, handlers, binding tags, and related glue
  gen/docs             Generate Swagger/OpenAPI documentation
  gen/wire             Generate Wire dependency injection code
  gen/all              Clean and regenerate all generated artifacts
  gen/dts              Generate TypeScript clients from Swagger
  run                  Run the application locally
  run/swag             Run the Swagger UI server
  lint                 Run Go, Buf, and golangci-lint checks
  fmt                  Format Go modules, Go source, Buf files, and imports
  build                Build a binary for the current platform
  build/all            Build binaries for configured platforms
  build/docker         Build a Docker image
  build/multi-docker   Build and push multi-arch Docker images
  deploy               Run the project deploy script
  clean                Remove generated code and build artifacts

The template should remain usable with standard commands as well. make is a convenience layer over Go, Buf, Wire, Swag, Docker, and shell scripts.

Project Structure

├── api                 # Go files generated from Protobuf definitions
├── assets              # Static assets and generated frontend bundles
├── cmd                 # Application and developer-tool entry points
│   ├── app             # Main application
│   └── tools           # Project-local generators and utilities
├── devops              # Deployment scripts and infrastructure examples
├── internal            # Private application code
│   ├── biz             # Business logic and use cases
│   ├── config          # Configuration loading and generated examples
│   ├── pkg             # Shared internal adapters and infrastructure
│   │   ├── database    # Ent schema, generated Ent client, and database setup
│   │   └── ...         # Other shared utilities
│   ├── server          # HTTP, docs, bot, and other transport wiring
│   └── service         # Implementations of generated service interfaces
├── proto               # Protobuf source files and API contracts
├── scripts             # Helper scripts, including client generation helpers
└── swagger             # Generated Swagger/OpenAPI documentation

Generated Code Boundaries

The following paths are generated or regenerated by make gen/* targets:

• api/**
• swagger/**
• internal/pkg/database/ent/**
• Wire output under cmd/app
• generated binding, conversion, mapping, and CRUD helper files

Application code should live outside those generated outputs whenever possible:

• service implementations in internal/service/**;
• domain logic in internal/biz/**;
• infrastructure composition in internal/pkg/**;
• API contracts in proto/**;
• project commands and local tooling in cmd/tools/**.

This boundary keeps regeneration safe and makes it clear which files are owned by tools.

Replaceable Defaults

The template uses Ent, Gin-style handlers, Wire, Swagger, and TypeScript generation because they provide a complete default path. Replacing one part should not require replacing Sphere itself.

Common replacement points:

• ORM: replace Ent-specific schema and gen/db flow with another persistence layer.
• HTTP router: use httpx adapters and generator options to target another supported router.
• Dependency injection: replace Wire with manual constructors or another DI approach.
• API documentation: keep Swagger generation, or add a separate OpenAPI pipeline.
• Deployment: use the provided Docker targets or wire the project into your existing CI/CD platform.

First Run

make init
make run

During normal development:

make gen/all
make run

Use make help to inspect the exact targets available in the checked-out template.