Hugo Nijhuis
271f5db444
Organize all product strategy and domain modeling documentation into a dedicated .product-strategy directory for better separation from code. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
177 lines
6.0 KiB
Markdown
177 lines
6.0 KiB
Markdown
# 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](./NAMESPACE_ISOLATION_QUICK_REFERENCE.md) (5 min read)
|
|
|
|
**Planning refactoring work?**
|
|
→ Read [NAMESPACE_ISOLATION_SUMMARY.md](./NAMESPACE_ISOLATION_SUMMARY.md) (15 min)
|
|
|
|
**Need complete reference for implementation?**
|
|
→ Review [DOMAIN_MODEL_NAMESPACE_ISOLATION.md](./DOMAIN_MODEL_NAMESPACE_ISOLATION.md) (45 min)
|
|
|
|
**Want visual architecture and diagrams?**
|
|
→ Check [NAMESPACE_ISOLATION_ARCHITECTURE.md](./NAMESPACE_ISOLATION_ARCHITECTURE.md) (20 min)
|
|
|
|
**Integrating multiple contexts?**
|
|
→ See [DOMAIN_MODEL_INDEX.md](./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](./NAMESPACE_ISOLATION_QUICK_REFERENCE.md) | 12 KB | 5 min | Checklists, code examples, quick lookups |
|
|
| [NAMESPACE_ISOLATION_SUMMARY.md](./NAMESPACE_ISOLATION_SUMMARY.md) | 16 KB | 15 min | Status, gaps, priorities, security |
|
|
| [NAMESPACE_ISOLATION_ARCHITECTURE.md](./NAMESPACE_ISOLATION_ARCHITECTURE.md) | 20 KB | 20 min | Diagrams, flows, visual explanations |
|
|
| [DOMAIN_MODEL_NAMESPACE_ISOLATION.md](./DOMAIN_MODEL_NAMESPACE_ISOLATION.md) | 40 KB | 45 min | Complete domain model, all aspects |
|
|
| [NAMESPACE_ISOLATION_DELIVERY.md](./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](./DOMAIN_MODEL_EVENT_SOURCING.md) (37 KB) - Event persistence and replay
|
|
- [DOMAIN_MODEL_OCC.md](./DOMAIN_MODEL_OCC.md) (29 KB) - Optimistic concurrency control
|
|
- [DOMAIN_MODEL_INDEX.md](./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)
|