Move product strategy documentation to .product-strategy directory
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>
This commit is contained in:
176
.product-strategy/README_DOMAIN_MODELS.md
Normal file
176
.product-strategy/README_DOMAIN_MODELS.md
Normal file
@@ -0,0 +1,176 @@
|
||||
# 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)
|
||||
Reference in New Issue
Block a user