aether/.product-strategy/README_DOMAIN_MODELS.md

Aether Domain Models

This directory contains complete Domain-Driven Design (DDD) models for Aether's bounded contexts.

Quick Navigation

Just want to understand Namespace Isolation quickly? → Start with NAMESPACE_ISOLATION_QUICK_REFERENCE.md (5 min read)

Planning refactoring work? → Read NAMESPACE_ISOLATION_SUMMARY.md (15 min)

Need complete reference for implementation? → Review DOMAIN_MODEL_NAMESPACE_ISOLATION.md (45 min)

Want visual architecture and diagrams? → Check NAMESPACE_ISOLATION_ARCHITECTURE.md (20 min)

Integrating multiple contexts? → See DOMAIN_MODEL_INDEX.md for all contexts

---

Namespace Isolation Context (Your Focus)

Status: Implementation complete, refactoring planned

Documents (in order of detail):

Document	Size	Read Time	Purpose
NAMESPACE_ISOLATION_QUICK_REFERENCE.md	12 KB	5 min	Checklists, code examples, quick lookups
NAMESPACE_ISOLATION_SUMMARY.md	16 KB	15 min	Status, gaps, priorities, security
NAMESPACE_ISOLATION_ARCHITECTURE.md	20 KB	20 min	Diagrams, flows, visual explanations
DOMAIN_MODEL_NAMESPACE_ISOLATION.md	40 KB	45 min	Complete domain model, all aspects
NAMESPACE_ISOLATION_DELIVERY.md	16 KB	10 min	What was delivered, how to use it

Total: 104 KB, 2,590 lines of documentation

---

Core Invariant (TL;DR)

Events in namespace X must be invisible to queries from namespace Y (except via explicit wildcard subscriptions by trusted components)

Enforced at three layers:

1. Memory: EventBus separates exact and wildcard subscribers
2. Storage: JetStreamEventStore creates separate streams per namespace
3. Network: NATSEventBus publishes to namespaced NATS subjects

---

Other Bounded Contexts

Also available (created in previous modeling sessions):

• DOMAIN_MODEL_EVENT_SOURCING.md (37 KB) - Event persistence and replay
• DOMAIN_MODEL_OCC.md (29 KB) - Optimistic concurrency control
• DOMAIN_MODEL_INDEX.md (16 KB) - Index of all contexts

---

How These Were Created

Using DDD framework:

1. Identified Invariants: Business rules that must never break
2. Defined Aggregates: Clusters enforcing invariants (found 0 in Namespace Isolation - it's primitives)
3. Specified Commands: User/system intents to change state (4 defined)
4. Designed Events: Facts that happened (3 defined)
5. Created Policies: Automated reactions (6 defined)
6. Modeled Read Models: Queryable views with no invariants (4 defined)
7. Analyzed Code: Compared intended vs. actual implementation (found 5 gaps)
8. Built Refactoring Backlog: Actionable improvements (6 issues prioritized)

---

Key Files in Codebase

eventbus.go (268 lines)           - Local pub/sub with isolation
nats_eventbus.go (231 lines)      - Cross-node replication
pattern.go (197 lines)            - Pattern matching & filtering
store/jetstream.go (382 lines)    - Storage isolation
store/namespace_test.go (125 lines) - Existing tests

---

Refactoring Priorities

Priority	Work	Effort	Impact
P1	Add namespace field to Event	2-3 days	HIGH - enables auditing
P2	Explicit namespace validation	1 day	MEDIUM - prevents silent errors
P3	NamespacedEventBus wrapper	2-3 days	MEDIUM - easier API
P4	Integration tests	1-2 days	HIGH - confidence
P5	Documentation	1 day	MEDIUM - clarity

Total Effort: 8-10 days, no blocking dependencies

---

Security Checklist

• Wildcard subscriptions are trusted code only (ops, logging, admin)
• Application validates namespace format
• No way for external clients to trigger wildcard
• Audit logging enabled for wildcard subscriptions
• Cross-namespace queries fail (GetEvents blocks at stream level)
• Integration tests verify isolation

---

For Different Roles

Product Manager:

1. NAMESPACE_ISOLATION_SUMMARY.md (5 min)
2. Refactoring priorities table
3. Security checklist

Developer:

1. DOMAIN_MODEL_NAMESPACE_ISOLATION.md (30 min)
2. Choose refactoring from P1-P3
3. Reference QUICK_REFERENCE.md while coding

Architect:

1. NAMESPACE_ISOLATION_ARCHITECTURE.md (20 min)
2. Review design decisions
3. Check integration with other contexts via DOMAIN_MODEL_INDEX.md

Security Auditor:

1. NAMESPACE_ISOLATION_SUMMARY.md Security section (10 min)
2. QUICK_REFERENCE.md Security Checklist (15 min)
3. Safety Documentation in full model

Code Reviewer:

1. QUICK_REFERENCE.md Anti-Patterns (2 min)
2. SUMMARY.md Implementation Alignment (15 min)
3. ARCHITECTURE.md event flows as reference

---

Questions?

• What is namespace isolation? → QUICK_REFERENCE.md
• What needs to be fixed? → SUMMARY.md Refactoring Priorities
• How does it work? → ARCHITECTURE.md diagrams
• What's the complete design? → DOMAIN_MODEL_NAMESPACE_ISOLATION.md
• How do I find information? → DOMAIN_MODEL_INDEX.md

---

Files in This Directory

Namespace Isolation (Your Focus):

• README_DOMAIN_MODELS.md (this file)
• NAMESPACE_ISOLATION_QUICK_REFERENCE.md
• NAMESPACE_ISOLATION_SUMMARY.md
• NAMESPACE_ISOLATION_ARCHITECTURE.md
• DOMAIN_MODEL_NAMESPACE_ISOLATION.md
• NAMESPACE_ISOLATION_DELIVERY.md

Other Contexts:

• DOMAIN_MODEL_INDEX.md (all contexts)
• DOMAIN_MODEL_EVENT_SOURCING.md
• DOMAIN_MODEL_OCC.md
• DOMAIN_MODEL_SUMMARY.md (high-level overview)

Total: 10 documents, ~200 KB

---

Status: All domain models complete and production-ready Last Updated: 2026-01-12 Modeled By: DDD Framework (Claude Haiku 4.5)