Add service

Add a service (or topic) to the Cosmos

Use this skill when the user says "add X to the cosmos", "wire service X into the map", or "add a topic node for Y". This covers adding a standalone capsule — it does not add scenario steps (use the add-scenario skill for that).

---

What you'll touch

File	Why
src/scenarios/services.ts	Add entries to SERVICES
src/scenarios/topics.ts	Add entries to TOPICS (only for topics used in scenario steps)
src/scenarios/owners.ts	Team ownership mapping
src/scenarios/types.ts	Only if you need a new Tech variant
src/components/TechIcon.tsx	Only if you added a new Tech variant
src/styles/tokens.css	Only if you need a new --svc-* color hue
src/map/UICluster.tsx	Only if the new service is a browser-facing UI surface

---

Step 1 — Research the service

Before touching any file, grep and read the service's source code (use an Explore agent for repos not in the workspace). You need:

• What does this service do? (one sentence role)
• What stack does it run on? (framework, language)
• What databases / infra does it use? (Kafka, Redis, Postgres, object storage…)
• What Kafka topics does it produce / consume?
• What HTTP endpoints does it expose or call?
• What other services call it? What does it call?
• What WebSocket connections does it open or accept?
• What is its repository name in your GitHub org?

Only proceed once you can answer all of these from source — never guess.

---

Step 2 — Map all connections

Before writing any entry, build a connection table. This is the most important step — it determines what goes into desc, what Kafka topics to add, which existing service descriptions to update, and what to flag as missing.

For every connection the new service has, fill in this table:

Direction	Protocol	Counterpart	Counterpart in cosmos?	Topic in cosmos?
→ outbound	HTTP	payments	✅ payments	n/a
← inbound	Kafka (consume)	orders	✅ orders	orders.created ❌ missing

Rules:

• Counterpart in cosmos? — grep -n "id: 'svc-id'" src/scenarios/services.ts for each one
• Topic in cosmos? — grep -n "id: 'topic-name'" src/scenarios/topics.ts for Kafka hops
• For anything ❌: either add it now (if it's a known service) or flag it in the Connection summary below

After filling the table, for each ❌:

• Missing service → add it using this skill, OR note it as "not yet in cosmos" in desc
• Missing topic → add a TOPICS entry if it will be used in a scenario step via:; otherwise just document it in the desc of both producer and consumer
• Existing service whose desc is now stale → update its desc to mention the new connection

---

Step 3 — Decide what to add

• Service = a deployed process (backend service, browser app, binary). Gets a capsule.
• Topic = a Kafka topic used as an intermediary between two services. Gets a small orbital node. Add a topic entry only if it is referenced via the via: field in an existing or planned scenario step.

Check it doesn't already exist first:

grep -n "id: 'your-service-id'" src/scenarios/services.ts src/scenarios/topics.ts

If it exists — stop, inform the user, and suggest updating the existing entry instead.

---

Step 4 — Add the Service entry

Append to the SERVICES array in src/scenarios/services.ts, near logically related services:

{
  id: 'my-service',               // kebab-case repo name — must be unique
  x: 1300, y: 600,                // see positioning rules below
  width: 230, height: 66,         // 200–250 width; height always 66
  color: 'var(--svc-blue)',       // CSS token from tokens.css
  hex: '#4f8ff7',                 // MUST match the token's hue — used in SVG gradients
  name: 'my-service',
  sub: 'NestJS · Postgres',       // short stack line
  code: 'MYS-19',                 // arbitrary display code
  lang: 'TypeScript',
  role: 'One-line role label',
  desc: `Full description. Cover: what it owns, what triggers it,
  what it produces, AND which other services it connects to (with protocol).
  Call out any connections to services not yet in the cosmos explicitly.
  2–5 sentences.`,
  tech: ['typescript', 'nestjs', 'postgres', 'kafka'],
  repo: 'my-service',             // repo name in your org; omit for non-repo nodes (object storage etc.)
},

The desc field must include all connections. Pattern:

• "Receives checkout requests from api-gateway over HTTP"
• "Produces orders.created (consumed by shipping, inventory)"
• "Pushes live updates to storefront via realtime-hub"

Positioning rules

The world is 2400 × 1400.

• Read existing x/y positions before placing. Don't overlap (capsules are width × 66; keep ≥150px center-to-center).
• Group with logically related services — look at where the service's main callers/callees sit and join that neighborhood.
• Browser-facing UI surfaces live in the left band by convention.
• If the user gives you coordinates, use them directly.

Colors

Pick the --svc-* token (see src/styles/tokens.css) that is least used nearby OR best matches the service's family. hex must visually match the token's hue — it's used in SVG gradients where CSS vars don't work. Topics always use TOPIC_COLOR / TOPIC_HEX (orange) — never change that.

If you need a truly new hue, add it to every theme block in tokens.css.

Tech tags

Valid values are the Tech union in src/scenarios/types.ts. If you need a new tech tag:

1. Add it to the Tech union in types.ts
2. Add a { label, color, monogram } entry to TECH_META in src/components/TechIcon.tsx

Service ecosystems (sub-services)

If the service is an umbrella over several deployed processes (like the demo's realtime-hub = ingest + router + presence + push), use subServices: SubService[] instead of adding N separate capsules. The parent capsule renders a + expand button and explodes into a mini solar system. Slot order matters: slot 0 (NE) = intake, slot 3 (NW) = output.

If you add a new expandable ecosystem, also extend legsForStep() in src/map/edge-resolver.ts and the internal-edges block in src/map/Map.tsx (both currently handle realtime-hub).

UI cluster

If the new service is a standalone browser-facing UI, add its id to UI_SERVICE_IDS in src/map/UICluster.tsx. Don't add embedded overlays or in-app views — standalone web surfaces only.

---

Step 5 — Add Topic entries (if needed)

{
  id: 'my-service.event-name',   // exact Kafka topic name
  x: 1450, y: 820,               // between producer and consumer
  name: 'my-service.event-name',
  color: TOPIC_COLOR, hex: TOPIC_HEX,
  desc: `Producer: X. Consumer: Y. What it carries and when it fires.`,
},

---

Step 6 — Update affected service descriptions

Go back to the connection table from Step 2. For every ✅ counterpart whose desc doesn't already mention the new service, update it so the relationship is visible from both sides.

---

Step 7 — Connection summary (always output this)

### Connections wired into cosmos
- my-service ←HTTP— api-gateway  (api-gateway.desc updated)
- my-service —Kafka→ orders  (orders.created topic added)

### Connections NOT yet in cosmos
- my-service —HTTP→ legacy-billing  (service not in cosmos — noted in desc)

---

Step 8 — Verify

npx tsc -b --noEmit    # must pass
npm run build          # must pass

Hard rules:

• ❌ Never run tsc without --noEmit/-b — stray .js files shadow .tsx in Vite and silently break the app.
• ❌ Never duplicate an id — ids must be unique across both SERVICES and TOPICS.
• ❌ Never place a service that overlaps an existing node.
• ❌ Never invent a hex that doesn't match the CSS-var hue.

---

Quick checklist

• Researched from source (not guessed)
• Connection table filled — every counterpart checked
• id unique — confirmed with grep
• Position doesn't overlap
• color/hex consistent
• All tech values exist in the Tech union
• Team added/updated in owners.ts
• Topic nodes added for topics used in via: steps
• Counterpart desc fields updated
• Connection summary printed
• npx tsc -b --noEmit and npm run build pass