aether/.product-strategy/DOMAIN_MODEL_INDEX.md

Aether Domain Models: Complete Index

Overview

This directory contains tactical Domain-Driven Design (DDD) models for Aether, a distributed actor system with event sourcing for Go powered by NATS. Each bounded context has its own domain model capturing invariants, aggregates, commands, events, policies, and read models.

Start here: NAMESPACE_ISOLATION_SUMMARY.md for a quick overview of the context assigned to you.

---

Bounded Contexts

Namespace Isolation Bounded Context

Responsibility: Provide logical boundaries for event visibility and storage; prevent data cross-contamination between different scopes (tenants, domains, environments).

Core Invariant: Events published to namespace X must be invisible to queries from namespace Y (except via explicit wildcard subscriptions by trusted components).

Documents:

1. DOMAIN_MODEL_NAMESPACE_ISOLATION.md (37 KB)

   • Complete domain model: invariants, aggregates, commands, events, policies, read models
   • Code analysis comparing intended design with actual implementation
   • Refactoring backlog with 6 prioritized issues
   • Safety documentation for wildcard subscriptions
   • Testing strategy with unit and integration test recommendations
   • Design decisions explaining key choices (namespace as string, per-namespace streams, etc.)

2. NAMESPACE_ISOLATION_SUMMARY.md (15 KB)

   • Executive summary of implementation status
   • Alignment matrix: which invariants are enforced, where
   • Refactoring priorities ranked by impact (P1-P5)
   • Implementation checklist with effort estimates
   • Security considerations and risk assessment

3. NAMESPACE_ISOLATION_ARCHITECTURE.md (18 KB)

   • Visual system architecture and data flow diagrams
   • Invariant enforcement across three layers (memory, storage, network)
   • Event flow scenarios: exact isolation, wildcard bypass, cross-node publishing
   • Pattern matching rules and sanitization process
   • Value objects, commands, policies reference
   • Failure scenarios and testing matrix

Key Files in Codebase:

• /Users/hugo.nijhuis/src/github/flowmade-one/aether/eventbus.go (268 lines) - Local pub/sub with exact and wildcard routing
• /Users/hugo.nijhuis/src/github/flowmade-one/aether/nats_eventbus.go (231 lines) - Cross-node pub/sub via NATS
• /Users/hugo.nijhuis/src/github/flowmade-one/aether/pattern.go (197 lines) - NATS-native pattern matching
• /Users/hugo.nijhuis/src/github/flowmade-one/aether/store/jetstream.go (382 lines) - Storage-layer namespace isolation
• /Users/hugo.nijhuis/src/github/flowmade-one/aether/store/namespace_test.go (125 lines) - Existing tests

Status: Implementation is 85% complete. Core invariants are enforced. Main gaps are metadata tracking (namespace field in Event) and explicit application-layer validation.

---

How to Read the Domain Models

For Architects / Decision-Makers

Start with: NAMESPACE_ISOLATION_SUMMARY.md

• 2-minute read: executive status
• Understand alignment of code with intended model
• See refactoring priorities and effort estimates

Then: NAMESPACE_ISOLATION_ARCHITECTURE.md

• Visual understanding of how isolation works
• See where invariants are enforced
• Understand failure scenarios and mitigations

For Developers Implementing Changes

Start with: DOMAIN_MODEL_NAMESPACE_ISOLATION.md

• Complete reference: invariants, commands, events, policies
• Code analysis showing gaps between design and implementation
• Refactoring backlog with clear acceptance criteria

Reference: NAMESPACE_ISOLATION_ARCHITECTURE.md

• Understand event flow and routing logic
• See pattern matching rules and sanitization
• Use as guide when modifying EventBus or storage layer

For Code Reviewers / Security Auditors

Start with: NAMESPACE_ISOLATION_SUMMARY.md (Security Considerations section)

• Understand wildcard subscription risks
• See documented mitigations
• Review recommended controls

Deep dive: DOMAIN_MODEL_NAMESPACE_ISOLATION.md (Safety Documentation section)

• Security design decisions
• Code locations of warnings
• Examples of safe vs. dangerous patterns

---

Other Bounded Contexts

While your focus is Namespace Isolation, Aether has other contexts worth understanding:

Event Sourcing Bounded Context

DOMAIN_MODEL_EVENT_SOURCING.md (37 KB)

Responsibility: Provide event persistence, replay, and snapshot capabilities as the source of truth.

Key Concepts:

• Event: Immutable fact that happened
• EventStore: Interface for persistence (InMemoryEventStore, JetStreamEventStore)
• Snapshot: Point-in-time state to avoid full replay
• ActorID: Logical entity identifier

Invariants:

• Events are immutable after creation
• Event stream per actor
• Snapshots are optional optimization

Integration with Namespace Isolation:

• Events are persisted in namespace-scoped stores
• Replay respects namespace boundaries
• Snapshot storage is also per-namespace

Optimistic Concurrency Control (OCC) Bounded Context

DOMAIN_MODEL_OCC.md (29 KB)

Responsibility: Prevent concurrent modification conflicts while maintaining high throughput.

Key Concepts:

• Version: Monotonically increasing per actor
• VersionConflictError: Raised when write conflicts with current state
• OptimisticLocking: Read version, attempt write, retry on conflict

Invariants:

• Versions must be strictly monotonic per actor
• Conflicts are detected and reported
• Retries are application responsibility

Integration with Namespace Isolation:

• Version tracking is per-namespace store
• GetLatestVersion() queries only the namespace's stream
• Conflicts can only occur within a namespace

Integration with Event Sourcing:

• Events carry version numbers
• Replay rebuilds version sequence
• Snapshots preserve version for fast forward

Supporting Bounded Contexts (Not Yet Modeled)

• Cluster Management - Node discovery, leader election, shard distribution
• Metrics and Monitoring - Observability for pub/sub, storage, clustering
• Distributed Tracing - Event causality, correlation IDs, trace propagation

---

Design Principles (From Vision)

All domain models align with Aether's core principles:

Primitives Over Frameworks

• Namespace is a value object, not an aggregate
• No opinionated namespace framework
• Application defines meaning (tenant, domain, environment)

NATS-Native

• Subject patterns use NATS "*" and ">" wildcards
• Separate JetStream stream per namespace (not stream-per-tenant layer)
• Cross-node pub/sub leverages NATS directly

Resource Conscious

• Minimal overhead for namespace isolation
• No namespace registry needed
• Optional: backward compatible without namespace

Events as Complete History

• All events persisted per namespace
• No deletion, only retention policy
• Replay rebuilds complete state within namespace

---

Key Concepts Glossary

Term	Definition	Example
Namespace	Logical boundary for event visibility	"tenant-abc", "prod.orders", "staging.users"
Pattern	NATS-style wildcard for matching namespaces	"" (single token), "prod." (multi), ">" (all)
Exact Subscription	Subscribe to specific namespace, isolation enforced	Subscribe("tenant-abc")
Wildcard Subscription	Subscribe to pattern matching multiple namespaces, isolation bypassed	Subscribe("prod.*") (only for trusted code)
EventBus	In-memory pub/sub with local subscriptions	Delivers to exact and wildcard subscribers
NATSEventBus	Cross-node pub/sub via NATS	Replicates events across cluster
JetStreamEventStore	Persistent event storage per namespace	Separate streams: "tenant-a_events", "tenant-b_events"
SubscriptionFilter	Optional event filtering by type and actor pattern	&SubscriptionFilter{EventTypes: ["OrderPlaced"]}
Subject	NATS address for routing	"aether.events.tenant-abc"
Invariant	Business rule that must never be broken	"Events in namespace X invisible to namespace Y"
Aggregate	Cluster of entities enforcing an invariant	None in Namespace Isolation (no lifecycle/rules)
Value Object	Immutable object defined by attributes	Namespace, SubjectPattern, SubscriptionFilter
Command	Intent to change state	DefineNamespace, PublishToNamespace, SubscribeToNamespace
Event	Fact that happened (immutable)	EventPublished (system fact, not currently modeled)
Policy	Automated reaction to events	Namespace routing, subject formatting, stream isolation
Read Model	Optimized query view (no invariants)	GetEventsInNamespace, SubscriberCountPerNamespace

---

Architecture Layers

Application Layer

• Defines namespace meaning
• Validates namespace format
• Controls access to wildcard subscriptions
• Orchestrates event flow

Domain Layer (Namespace Isolation Context)

• Value objects: Namespace, SubjectPattern, SubscriptionFilter
• Commands: DefineNamespace, PublishToNamespace, SubscribeToNamespace
• Policies: namespace routing, subject formatting, storage isolation
• Read models: GetEventsInNamespace, SubscriberCount
• No aggregates (primitives, not domain entities)

Infrastructure Layer

• EventBus (local pub/sub): exactSubscribers + wildcardSubscribers
• NATSEventBus (cross-node): NATS subject routing
• JetStreamEventStore (persistence): per-namespace streams
• Pattern Matching (routing): token-based NATS matching
• Subject Sanitization (safety): prevent injection

---

Quick Start: Using These Documents

I want to understand how namespace isolation works

→ Read: NAMESPACE_ISOLATION_ARCHITECTURE.md (15 min)

I need to implement a refactoring from the backlog

→ Read: DOMAIN_MODEL_NAMESPACE_ISOLATION.md (Refactoring Backlog section) (30 min)

I'm reviewing a PR that changes EventBus or storage

→ Read: NAMESPACE_ISOLATION_SUMMARY.md (Implementation Alignment section) (15 min)

I'm adding a new feature that uses namespaces

→ Read: DOMAIN_MODEL_NAMESPACE_ISOLATION.md (Invariants, Commands, Policies) (45 min)

I'm auditing security

→ Read: NAMESPACE_ISOLATION_SUMMARY.md (Security Considerations section) + DOMAIN_MODEL_NAMESPACE_ISOLATION.md (Safety Documentation section) (30 min)

I'm integrating Namespace Isolation with another context (e.g., Event Sourcing)

→ Read: All three NAMESPACE_ISOLATION docs + relevant context from DOMAIN_MODEL_EVENT_SOURCING.md

---

Refactoring Priorities at a Glance

Priority	Issue	Effort	Status
P1	Add Namespace to Event metadata	2-3 days	Pending
P2	Add explicit namespace validation	1 day	Pending
P3	Create NamespacedEventBus wrapper	2-3 days	Pending
P4	Cross-namespace integration tests	1-2 days	Pending
P5	Document namespace hierarchies	1 day	Pending

Total effort for all refactoring: ~8-10 days Can be done incrementally; no blocking dependencies

---

Files Created

All documents are in /Users/hugo.nijhuis/src/github/flowmade-one/aether/:

• ✓ DOMAIN_MODEL_NAMESPACE_ISOLATION.md (37 KB) - Complete model
• ✓ NAMESPACE_ISOLATION_SUMMARY.md (15 KB) - Quick reference
• ✓ NAMESPACE_ISOLATION_ARCHITECTURE.md (18 KB) - Visual architecture
• ✓ DOMAIN_MODEL_INDEX.md (this file) - Navigation guide

Also available in this directory:

• DOMAIN_MODEL_EVENT_SOURCING.md - Event persistence context
• DOMAIN_MODEL_OCC.md - Optimistic concurrency context
• DOMAIN_MODEL_SUMMARY.md - High-level overview of all contexts

---

Next Steps

For Immediate Use

1. Review NAMESPACE_ISOLATION_SUMMARY.md (5 min)

   • Understand current implementation status
   • See what's working and what's not

2. Choose a refactoring from P1-P3 (most impactful)

   • P1 (Event metadata) enables better tracing
   • P2 (Validation) prevents silent behavior changes
   • P3 (Wrapper) improves API safety

3. Read the relevant section in DOMAIN_MODEL_NAMESPACE_ISOLATION.md

   • Understand the invariants and policies involved
   • See implementation guidance and acceptance criteria

For Long-Term Development

1. Integrate this model into your backlog system

   • Use refactoring issues as work items
   • Reference domain concepts in commit messages
   • Update domain model as understanding evolves

2. Keep domain model and code synchronized

   • When adding features, update the model
   • When encountering gaps, document them in the backlog
   • Use domain language in code reviews

3. Build related contexts incrementally

   • Cluster Management (node discovery, leader election)
   • Metrics and Monitoring (observability)
   • Distributed Tracing (event causality)

---

References

• Aether Vision: /Users/hugo.nijhuis/src/github/flowmade-one/aether/vision.md
• Organization Manifesto: https://git.flowmade.one/flowmade-one/architecture
• DDD Guidelines: See ddd skill in Claude Code
• Product Strategy Framework: See product-strategy skill in Claude Code

---

Questions?

These domain models are designed to be:

• Complete: All aspects of the context are documented
• Actionable: Every issue has clear acceptance criteria
• Evolvable: Easy to update as understanding improves
• Aligned: With organization vision and Aether principles

If something is unclear or missing, it's a documentation gap. File an issue or update the model as you discover new information.

---

Last Updated: 2026-01-12 Context Modeled By: Domain-Driven Design skill (Claude Haiku 4.5) Status: Ready for implementation