nats-design-subject

Design NATS Subject Hierarchy

Design a subject architecture that subscribers can efficiently navigate using wildcards, with proper segment ordering, account-aware tenant isolation, and growth path.

Interview Phase

Skip interview if ALL of these are already specified:

• Messaging patterns (pub/sub, request/reply, streaming)
• Multi-tenancy needs (single/multi-tenant, scale requirements)
• Security requirements (authorization, tenant isolation)
• Persistence needs (JetStream vs core NATS)

Always interview if: Migrating existing subjects (needs anti-pattern audit first)

Questions

1. Scope — "Is this greenfield design or migrating existing subjects?"

   • Impact: Migration needs anti-pattern audit first (see references/anti-patterns.md)

2. Multi-Tenancy & Scale — "Do you need: (A) Single tenant, (B) Account-per-tenant isolation, (C) Shared account with subject prefixes, (D) Massive scale with regions/shards?"

   • Impact: Determines whether tenant identity belongs in the NATS account boundary, the subject, or both

3. Messaging Patterns — "Which patterns do you use? (A) Pub/Sub only, (B) Request/Reply, (C) Streaming/JetStream, (D) All/mix?"

   • Impact: JetStream needs stream-aware subject design; request/reply has its own conventions

4. Security — "Do you need account-level isolation, subject-based authorization, or both?"

   • Impact: Determines account boundaries, exports/imports, tenant prefixes, and permission boundaries

5. Persistence — "Do you need JetStream persistence or core NATS only?"

   • Impact: Determines stream/consumer subject design and retention considerations

---

When to Use

• Designing a new NATS messaging system
• Planning account-aware multi-tenant subject isolation
• Organizing device telemetry or event streams
• Setting up request/reply patterns across microservices
• Defining event subject structure for event-sourced systems
• Building agentic AI platforms with inter-agent messaging

When NOT to Use

• Configuring NATS server or cluster settings (infrastructure, not subject design)
• Writing NATS client code or connection logic (implementation, not architecture)
• Choosing between NATS and other messaging systems (technology evaluation)
• Debugging existing NATS connectivity or performance issues

---

Workflow

1. Identify Domain Boundaries

List all NATS account boundaries and business domains involved. For strict multi-tenancy, use one account per tenant first; then design short, domain-first subjects inside each account.

Use subject tenant prefixes only when accounts are intentionally unavailable or when designing a shared/platform surface that must carry tenant provenance.

2. Choose a Pattern

Match the user's scenario to a pattern:

Use Case	Pattern	Example
Simple Domain	{domain}.{action}.{scope}	orders.created.us-west
Multi-Region	{domain}.{action}.{region}.{id}	devices.telemetry.us-east.sensor-456
Multi-Tenant SaaS	Account per tenant, subjects: {domain}.{action}.{id}	analytics.processed.report-123 in account acme-corp
Shared Account Fallback	{tenant}.{domain}.{action}.{id}	acme-corp.analytics.processed.report-123
Multi-Tenant AI	Account per tenant, subjects: agents.{action}.{agent-id}.{task-id}	agents.task-assigned.agent-xyz.task-123 in account tenant-abc
Request/Reply	{service}.request / {service}.reply	orders.request / orders.reply
Event Sourcing	{aggregate}.{action}.v{version}.{id}	orders.order.created.v1.order-123

For full pattern details with subscriber paths and scaling guidance, read references/patterns.md.

3. Order Segments Strategically

Apply these rules when ordering subject segments left-to-right inside the selected account:

• Broad to specific: Domain → Action → Scope → Identifier
• Low-cardinality left, high-cardinality right: Regions (few values) before IDs (millions of values)
• Never put IDs or UUIDs before actions

✓ GOOD: orders.created.us-west.order-123
                            ↑          ↑
                       low-card    high-card

✗ BAD:  orders.order-123.us-west.created
                ↑
           high-card early (kills wildcard filtering)

Why this matters: NATS wildcard matching scans left-to-right. High-cardinality values on the left force subscribers into inefficient orders.*.us-west.created patterns that must match thousands of IDs.

For common ordering mistakes and migration strategies, read references/anti-patterns.md.

4. Plan Subscriber Paths

For each domain, document how subscribers will filter:

orders.>                    → All order events
orders.created.>            → All order creation events
orders.created.us-west.>    → Orders created in US West
orders.created.us-west.order-123 → Specific order

Design subjects for subscribers, not publishers. Subscribers determine how you organize — a good hierarchy lets them efficiently filter with wildcards.

5. Design Security Model (if multi-tenant)

If the user needs tenant isolation or role-based access:

• Prefer NATS Accounts for tenant isolation; each tenant gets its own subject namespace
• Use exports/imports for cross-account federation instead of assuming cross-tenant visibility
• Use tenant IDs in subjects only for shared-account fallbacks or platform aggregation surfaces
• Separate admin/platform subjects from user operations (_admin.> or platform account subjects)
• Apply least-privilege permissions per service

For account-based tenancy, authorization patterns, and tenant isolation examples, read references/security.md.

6. Design JetStream Streams (if persistence needed)

If the user needs JetStream:

• Treat JetStream streams, consumers, and KV buckets as account-scoped resources
• Reuse stream/KV names across tenant accounts when the topology is identical
• Use one stream per domain inside each tenant account
• Use per-tenant streams in one shared account only as a fallback
• Consumer filters for fine-grained routing
• Account and domain retention limits (financial: years, telemetry: days)
• Keep to 4-6 subject segments — use consumer filters instead of deeper hierarchies

For stream design, consumer patterns, and migration from core NATS, read references/jetstream.md.

7. Validate and Write Output

Present the design using this template:

# NATS Subject Architecture: [System Name]

## Domain Overview
[Describe the domains and their interactions]

## Subject Hierarchy

### Domain: [Name]
- `domain.action.{scope}.{id}`
- `domain.action.{scope}.{id}`

Subscriber paths:
- `domain.>` — All events
- `domain.action.>` — Specific action

[Repeat for each domain]

## Multi-Tenancy Model
[NATS Accounts, exports/imports, or shared-account subject prefixes]

## Security Model
[Authorization rules per role/service, if applicable]

## JetStream Streams
[Account-scoped stream definitions and consumer filters, if applicable]

## Quality Validation
[Run checklist below]

Example Output

# NATS Subject Architecture: IoT Smart Building Platform

## Domain Overview

Smart building system with 10,000+ sensors across multiple regions sending temperature, humidity, and occupancy data. Needs real-time monitoring, regional aggregation, and alerting.

## Subject Hierarchy

### Domain: Devices
- `devices.telemetry.{region}.{device-id}.{metric}`
- `devices.telemetry.us-west.sensor-456.temperature`
- `devices.telemetry.us-west.sensor-456.humidity`
- `devices.telemetry.eu-central.sensor-789.occupancy`

Subscriber paths:
- `devices.telemetry.>` — All telemetry (global monitoring)
- `devices.telemetry.us-west.>` — Regional dashboard (US West)
- `devices.telemetry.>.>.temperature` — All temperature readings

### Domain: Alerts
- `alerts.triggered.{severity}.{region}.{device-id}`
- `alerts.triggered.critical.us-west.sensor-456`

Subscriber paths:
- `alerts.triggered.critical.>` — Critical alerts only
- `alerts.triggered.>.us-west.>` — Regional alert dashboard

## Multi-Tenancy Model

Not applicable (single organization)

## Security Model

- Building operators: `devices.telemetry.>`, `alerts.>` (subscribe only)
- Alert service: `alerts.>` (publish + subscribe)
- Admin: `>` (full access)

## JetStream Streams

Stream: `telemetry-us-west`
  Subjects: `devices.telemetry.us-west.>`
  Retention: 24h (high volume)
  
Stream: `alerts`
  Subjects: `alerts.>`
  Retention: 30d

## Quality Validation

✓ All segments follow broad-to-specific order
✓ Device IDs at rightmost position
✓ Naming consistent (lowercase, hyphens)
✓ Regional filtering efficient
✓ 4 segments (within 4-6 limit)

For complete real-world examples across microservices, IoT, SaaS, event sourcing, and agentic AI platforms, read references/use-cases.md.

---

Quick Start (Simple Cases)

If you're designing a simple single-domain system without multi-tenancy:

1. Use Pattern 1 (Simple Domain): {domain}.{action}.{id}
2. Skip references — follow the workflow above
3. Example: orders.created.order-123, payments.authorized.payment-456

For multi-region, multi-tenant, or event-sourcing needs, continue with full workflow and read references as needed.

---

Reference Navigation

The skill includes 5 detailed reference documents — read them as needed during workflow steps:

• patterns.md: Read when choosing initial pattern (step 2)
• anti-patterns.md: Read when migrating or auditing existing subjects
• security.md: Read when multi-tenancy/authorization needed (step 5)
• jetstream.md: Read when persistence needed (step 6)
• use-cases.md: Read for complete worked examples per domain

Don't read all references upfront — use them progressively as the workflow requires.

---

Naming Rules

• All lowercase with hyphens: orders.created ✓
• Never underscores: orders_created ✗
• Never mixed case: Orders.Created ✗
• Keep to 4-6 segments maximum

---

Quality Checklist

• All segments follow broad-to-specific order ({domain}.{action}.{scope}.{id})
• No UUID/ID fields appear before action/scope segments
• Naming consistent (all lowercase, hyphens, no underscores)
• Documented subscriber wildcard paths for each domain
• No subjects deeper than 6 segments
• Multi-tenancy boundary is clear (account-per-tenant, shared-account prefix fallback, or both)
• Security subjects defined for admin/monitoring access
• No conflicting patterns (e.g., orders.created.123 vs orders.123.created)
• High-cardinality decision documented (why ID placement chosen)

Testing Your Design

Validate your subject hierarchy before deployment:

# Start local NATS server
nats-server -D

# Test subscriber wildcards
nats sub "orders.>"                    # Should match all order subjects
nats sub "orders.created.>"            # Should match only creations
nats sub "orders.created.us-west.>"    # Should match region-specific

# Test publishing
nats pub "orders.created.us-west.order-123" "test message"

# Verify JetStream streams (if applicable)
nats stream info orders-stream
nats consumer info orders-stream order-consumer

For existing deployments, audit current subjects:

# List active subjects (requires monitoring enabled)
nats server report jetstream

# Check subject permissions
nats server check connection --account <account-name>

Reference Documentation

• Patterns: 6 hierarchy patterns with subscriber paths and scaling guidance
• Anti-Patterns: common mistakes with detection, fixes, and migration strategies
• Security & Multi-Tenancy: Authorization patterns and tenant isolation
• JetStream Design: Stream filters, consumer subjects, and retention policies
• Use Cases: Complete examples for microservices, IoT, SaaS, event sourcing, agentic AI