Add a Service

Goal

Scaffold a new backend service that conforms to our platform conventions — hexagonal structure, OTel instrumentation, standard CI pipeline, ./dev integration — from day one.

Prerequisites

• An accepted ADR justifying the new service. "We could just add this to wordloop-core" is often the right answer; the ADR documents why it is not.
• Familiarity with Hexagonal Architecture, the Platform stance, and Go Services or ML Systems depending on the language.

Steps

1. Use the scaffolding template

Our platform ships a bootstrapping template per supported language. It produces:

• The hexagonal directory layout (domain/, ports/, adapters/, application/).
• A stub HTTP server with OTel instrumentation configured.
• A standard CI pipeline definition.
• Dockerfile and Cloud Run deployment config.
• ./dev integration (start, stop, logs, test, lint).

2. Register the service with the platform

Add the service to the platform's service registry so that shared tooling — observability, feature flags, secrets — knows it exists. This is the step that makes the service "real" to the rest of the platform.

3. Write the first ADR

A new service is a decision. Capture its purpose, its expected ownership, and the debt it carries (runtime cost, operational surface, coordination overhead) as an ADR.

4. Define the service's first SLO

Before the service receives traffic, define the user-facing SLO it will live inside (Reliability). An SLO-less service is a service that nobody can defend.

5. Write the service handbook

Create content/docs/learn/services/<name>/ with index.mdx, architecture.mdx, and implementation.mdx. The handbook explains the "why" that the code cannot.

Verification

• ./dev start <name> starts the service cleanly.
• ./dev test <name> passes.
• The service is visible on the platform observability dashboard.
• A fresh engineer can open the service handbook and understand the shape.

Troubleshooting

• OTel not exporting. Check that the service registered its collector endpoint; the template defaults should work but custom configuration may override.
• CI failing on the first push. The template ships a minimal CI pipeline; extend it with service-specific tests as needed.

See Platform for the broader stance on service scaffolding.