Adding a new microservice

Workflow

Copy this checklist and track your progress:

Creating a new microservice:
- [ ] Step 1: Create a Directory for the New Microservice
- [ ] Step 2: Create `doc.go` with Code Generation Directive
- [ ] Step 3: Generate Initial `service.yaml`
- [ ] Step 4: Fill in `service.yaml`
- [ ] Step 5: Generate Microservice File Structure
- [ ] Step 6: Add the Microservice to the Main Application
- [ ] Step 7: Propose Features

Step 1: Create a Directory for the New Microservice

Each microservice is kept in a separate directory. Create a new directory for the new microservice.

mkdir -p myservice
cd myservice

Step 2: Create doc.go with Code Generation Directive

Create doc.go with the directive to trigger the code generator.

package myservice

//go:generate go run github.com/microbus-io/fabric/codegen

Step 3: Generate Initial service.yaml

Run go generate to create the initial service.yaml file.

Important Do not attempt to create service.yaml yourself from scratch. Always let the code generator initialize it.

Step 4: Fill in service.yaml

The service.yaml file is the blueprint of your microservice. Fill in the general section:

• The host defines the host name under which this microservice will be addressable. It must be unique across the application. Use reverse domain notation, e.g. myservice.myproject.mycompany.
• The description should explain what this microservice is about.

general:
  host: myservice.myproject.mycompany
  description: My microservice does X, Y, and Z

Important: Do not fill in any other section of service.yaml unless explicitly asked to do so by the user.

Step 5: Generate Microservice File Structure

Run go generate again to generate the file structure of the microservice.

Step 6: Add the Microservice to the Main Application

Add the new microservice to the app in main.go, if not already added. Note that main.go is typically located in the main directory of the project, not inside the directory of the microservice. The order is important: add the new microservice after the core infrastructure microservices are added, and before the HTTP ingress proxy is added.

func main() {
	app := application.New()

	// The configurator must be first
	app.Add(
		configurator.NewService(),
	)

	// Infrastructure services
	app.Add(
		httpegress.NewService(),
		openapiportal.NewService(),
		metrics.NewService(),
	)

	// Add your solution microservices here
	app.Add(
		myservice.NewService(),
	)

	// HTTP ingress proxy is last
	app.Add(
		httpingress.NewService(),
	)

	err := app.Run()
	if err != nil {
		fmt.Fprintf(os.Stderr, "%+v", err)
		os.Exit(19)
	}
}

Step 7: Propose Features

If you have an idea for what the microservice should include, prepare a proposal categorizing them by feature:

• Configuration properties
• Functional endpoints (RPCs)
• Outbound events
• Inbound event sinks
• Web handler endpoints
• Tickers (recurring operations)
• Metrics

Save the proposal in AGENTS.md, then show it to the user and seek additional instructions.