Go Service Example

This example is useful when you need a concrete reference for a service repo that owns runtime entrypoints, transport integrations, and operator-facing runbooks. It shows how to capture the repo facts a teammate or agent needs before they touch a delivery path, and it keeps that context in the same shape the generator expects.

Why this profile is a good starting point

• It models a service with executable entrypoints, local stack commands, and production-facing dependencies instead of a generic library skeleton.
• It highlights the operational surface area that matters for service work: transports, handlers, delivery channels, and focused verification.
• It demonstrates how draft profiles can still be useful even when ownership details remain unresolved in the source repo snapshot.

Profile at a glance

• Repo: Notify
• Repo path: {profile.facts.repo.path}
• Repo kind: {profile.facts.repo.kind}
• Language: {profile.facts.repo.language}
• Draft status: {profile.facts.meta.draftStatus}
• Summary: Go notification delivery service centered on notify-sender over triggers-v2.

Provenance

• Source repo path: {profile.provenance.sourceRepoPath}
• Snapshot date: {profile.provenance.snapshotDate}
• Owner or steward: {profile.provenance.ownerOrSteward}
• Provenance note: Derived from the repo README, Makefile, and docs paths present in the repo snapshot.

What the facts emphasize

Entry points and runtime shape

The profile points straight at the executables and runtime-bearing directories a service maintainer would inspect first:

- cmd/notify-sender/main.go

- cmd/notify/main.go

- internal/handlers

- internal/channel/inapp

- notify-sender HTTP on :8181

- metrics on :9191

Commands and verification cues

These commands tell the generator what a minimal service workflow looks like:

• Setup: {profile.facts.commands.setup.join(" | ")}
• Dev: {profile.facts.commands.dev.join(" | ")}
• Test: {profile.facts.commands.test.join(" | ")}
• Build: {profile.facts.commands.build.join(" | ")}

The verification guidance stays close to real service risk:

- Use the repo's focused checks before claiming success.

Integration surface and source docs

The integrationSurface block captures the service boundary that downstream artifacts should preserve:

• Inputs: NATS, Kafka, HTTP
• Outputs: In-app websocket delivery, template-driven notifications
• Dependencies: MongoDB, NATS, Redis

The profile also anchors the example in repo-native docs instead of inventing a parallel narrative:

- Doc: docs/notify-sender.md (notify-sender architecture)

- Runbook: docs/runbooks/adding_a_channel.md (Adding a channel)

Generated artifact preview

ExampleArtifactShowcase runs the shared renderer path against the shipped example id. That matters because the output below is not hand-written docs content; it is the same artifact pack shape the generator produces from REPO_FACTS.json plus provenance.

Notify example artifacts

Generated from the shared renderer path for momentum-online/notify.

Canonical repo facts

REPO_FACTS.json

json via generic-v1

{
  "meta": {
    "schemaVersion": "1",
    "artifactVersion": "1",
    "generatorVersion": "integrations-v1",
    "draftStatus": "draft",
    "unknowns": [
      "ownerOrSteward: unknown (not explicitly stated in repo docs)",
      "ownership ownerOrSteward is unknown",
      "lifecycle.lastReviewed"
    ]
  },
  "repo": {
    "key": "notify",
    "name": "Notify",
    "path": "momentum-online/notify",
    "language": "go",
    "kind": "service",
    "summary": "Go notification delivery service centered on notify-sender over triggers-v2."
  },
  "entryPoints": {
    "files": [
      "cmd/notify-sender/main.go",
      "cmd/notify/main.go"
    ],
    "directories": [
      "internal/handlers",
      "internal/channel/inapp"
    ],
    "runtime": [
      "notify-sender HTTP on :8181",
      "metrics on :9191"
    ]
  },
  "commands": {
    "setup": [
      "make install"
    ],
    "dev": [
      "make local-up"
    ],
    "test": [
      "make test",
      "make test-integration"
    ],
    "build": [
      "make build-sender"
    ]
  },
  "integrationSurface": {
    "inputs": [
      "NATS",
      "Kafka",
      "HTTP"
    ],
    "outputs": [
      "In-app websocket delivery",
      "template-driven notifications"
    ],
    "dependencies": [
      "MongoDB",
      "NATS",
      "Redis"
    ]
  },
  "sourceDocs": {
    "docs": [
      {
        "title": "notify-sender architecture",
        "path": "docs/notify-sender.md"
      }
    ],
    "runbooks": [
      {
        "title": "Adding a channel",
        "path": "docs/runbooks/adding_a_channel.md"
      }
    ]
  },
  "lifecycle": {
    "stage": "active",
    "ownerOrSteward": "unknown",
    "lastReviewed": "unknown"
  },
  "ownership": {
    "stopAndAsk": [
      "Before changing external contracts or transport semantics."
    ],
    "verification": [
      "Run repo tests and the relevant local integration flow."
    ],
    "riskyAreas": [
      "Transport boundaries and production-facing handlers."
    ],
    "safeEditZones": [
      "Docs, examples, and additive non-contract helpers."
    ]
  },
  "agentBehavior": {
    "stopAndAsk": [
      "Pause before changing repo policy, contracts, or runbooks."
    ],
    "verification": [
      "Use the repo's focused checks before claiming success."
    ],
    "riskyAreas": [
      "Wire contracts, delivery paths, and migration-sensitive code."
    ],
    "safeEditZones": [
      "Documentation, fixtures, and narrow refactors."
    ]
  }
}