Uniform Code Structure

Coding agents are instructed to create numerous files and subdirectories in the directory of a microservice.

myservice/                  # Each microservice has its own directory
├── myserviceapi/           # The public interface of this microservice
│   ├── definition.go       # Hand-written single source of truth for the API
│   ├── client.go           # Generated client API
│   └── [type].go           # Hand-written definition for each complex type used in the API
├── resources/              # Embedded resource files
│   ├── embed.go            # go:embed directive
│   └── [your files]        # Static files, configs, etc.
├── CLAUDE.md               # Local instructions for Claude
├── intermediate.go         # Generated service infrastructure
├── manifest.yaml           # Generated manifest of [features](/microservice-substrate/connector/_index.md)
├── mock.go                 # Generated mock for testing purposes
├── mock_test.go            # Generated mock smoke test
├── PROMPTS.md              # Audit trail of prompts
├── service_test.go         # Integration tests
└── service.go              # Implementation

The *api directory (and package) is the public-facing API of the microservice to upstream microservices. Two of its files are hand-written: definition.go, the single source of truth that declares the Hostname, the service metadata, and one typed define.* var per feature alongside its input/output structs; and one file per complex type (struct) the API uses. From definition.go the genservice tool generates client.go — the Client, MulticastClient, MulticastTrigger, Hook, Executor, and (for services that declare workflows) Subgraph stubs — along with intermediate.go, mock.go, mock_test.go, and manifest.yaml. The name of the API directory is derived from that of the microservice in order to make it easily distinguishable in code completion tools.

The resources directory is a place to put static files to be embedded into the executable of the microservice. Templates, images and scripts are some examples of what can potentially be embedded.

CLAUDE.md allows setting instructions to coding agents that should be respected in the context of this microservice only. PROMPTS.md keeps an audit trail of the prompts that affected this microservice.

intermediate.go defines the Intermediate that serves as the base of the microservice via anonymous inclusion, in turn extending the Connector.

The Mock is a mockable stub of the microservice that can be used in integration testing when a live version of the microservice cannot. It is defined in mock.go.

A test is created in service_test.go for each testable web handler, functional endpoint, event, event sink, ticker, config callback and metric callback of the microservice.

service.go is where the business logic of the microservice lives. service.go implements Service, which extends Intermediate as mentioned earlier. Most of the tools that a microservice needs are available through the receiver (svc *Service) which points to the Intermediate and by extension the Connector. It includes the methods of the Connector as well as type-specific methods defined in the Intermediate.

type Intermediate struct {
	*connector.Connector
}

type Service struct {
	*intermediate.Intermediate
}

func (svc *Service) DoSomething(ctx context.Context) (err error) {
	// svc points to the Intermediate and by extension the Connector
}