dhurandhar 1.0.0

package/docs/PLUGGABLE_STRATEGIES.md

@@ -0,0 +1,439 @@
+# Pluggable Architectural Strategies
+
+## Overview
+
+Dhurandhar v2.2 introduces **Pluggable Architectural Strategies** - a system for injecting complex architectural patterns as modular constraints that automatically propagate to all services.
+
+## Philosophy
+
+### Traditional Approach (Anti-Pattern)
+
+```
+Developer: "Add payment service"
+System: "What database?"
+Developer: "PostgreSQL"
+System: "Should it have its own database?"
+Developer: "Yes, we're doing database-per-service"
+
+[Next service]
+
+Developer: "Add user service"
+System: "What database?"
+Developer: "PostgreSQL"
+System: "Should it have its own database?"
+Developer: "YES! I told you we're doing database-per-service!"
+
+[Cognitive fatigue from repeated decisions]
+```
+
+### Dhurandhar Approach
+
+```
+Developer: "Set persistence strategy to database-per-service"
+System: "✓ Strategy set. All new services will have dedicated databases."
+
+Developer: "Add payment service"
+System: "✓ payment-service added with dedicated payment_db"
+
+Developer: "Add user service"
+System: "✓ user-service added with dedicated user_db"
+
+[Zero repeated questions. Strategy enforced automatically.]
+```
+
+## Strategy Categories
+
+### 1. Persistence Strategy
+
+**Controls**: Data isolation model
+
+**Options**:
+- `database_per_service` - Full isolation, eventual consistency
+- `shared_database` - Monolith pattern, ACID transactions
+- `hybrid` - Mix of both approaches
+- `event_sourcing` - Event log as source of truth
+
+**Auto-Applied Constraints**:
+- `database_per_service`:
+  - Each service gets dedicated database
+  - Constraint: `no_cross_service_queries`
+  - Constraint: `eventual_consistency`
+- `shared_database`:
+  - All services share one database
+  - ACID transactions allowed
+  - Tighter coupling
+
+### 2. Communication Pattern
+
+**Controls**: Service-to-service interaction model
+
+**Options**:
+- `synchronous_rest` - Request/response, immediate
+- `asynchronous_events` - Event-driven, decoupled
+- `hybrid` - Both REST and events
+- `grpc_streaming` - High performance, bidirectional
+- `graphql_federation` - Federated GraphQL gateway
+
+**Auto-Applied Constraints**:
+- `asynchronous_events`:
+  - Services MUST define `event_boundaries` (produces/consumes)
+  - Event bus technology injected (Kafka, RabbitMQ, etc.)
+  - Message format specified (JSON, Avro, Protobuf)
+- `synchronous_rest`:
+  - Services define REST API contracts
+  - No event boundaries required
+
+### 3. State Management
+
+**Controls**: Caching and session distribution
+
+**Options**:
+- `distributed_redis` - Shared cache across services
+- `local_in_memory` - Per-service cache
+- `sidecar_cache` - Service mesh pattern
+- `cdn_edge` - Edge caching for static content
+- `none` - No caching
+
+**Auto-Applied Constraints**:
+- `distributed_redis`:
+  - Redis dependency added to services
+  - Cache config injected
+  - Invalidation strategy set (TTL, event-driven, etc.)
+
+### 4. Security Strategy
+
+**Controls**: Authentication and authorization patterns
+
+**Options**:
+- `jwt_centralized` - Auth service validates all tokens
+- `oauth2_delegated` - External OAuth provider
+- `mtls` - Certificate-based, service-to-service
+- `api_keys` - Simple key-based auth
+- `hybrid` - Multiple mechanisms
+
+**Auto-Applied Constraints**:
+- `jwt_centralized`:
+  - Services depend on `auth-service`
+  - JWT validation endpoint configured
+  - Token refresh flow defined
+
+### 5. Resilience Strategy
+
+**Controls**: Fault tolerance patterns
+
+**Options**:
+- `circuit_breaker: true/false`
+- `retry_strategy: exponential_backoff | fixed_delay | none`
+- `timeout_policy: aggressive_5s | moderate_30s | lenient_60s`
+- `bulkhead_isolation: true/false`
+
+**Auto-Applied Constraints**:
+- `circuit_breaker: true`:
+  - Circuit breaker config added to all services
+  - Failure threshold: 5
+  - Timeout: 30s
+
+### 6. Deployment Strategy
+
+**Controls**: Orchestration and scaling
+
+**Options**:
+- `orchestration: kubernetes | docker_swarm | ecs | serverless`
+- `scaling_strategy: horizontal_pod_autoscaling | vertical_scaling | manual`
+- `service_mesh: istio | linkerd | consul | none`
+
+### 7. Observability Strategy
+
+**Controls**: Monitoring, logging, tracing
+
+**Options**:
+- `logging: centralized_elk | cloudwatch | datadog | loki`
+- `metrics: prometheus | datadog | cloudwatch`
+- `tracing: jaeger | zipkin | aws_xray | datadog_apm`
+- `distributed_tracing: true/false`
+
+## CLI Commands
+
+### Show Active Strategies
+
+```bash
+dhurandhar strategy --show
+```
+
+**Output**:
+```
+📐 Active Architectural Strategies
+
+Persistence Strategy:
+  Model: database_per_service
+  Constraints: no_cross_service_queries, eventual_consistency
+
+Communication Pattern:
+  Primary: asynchronous_events
+  Event Bus: kafka
+
+State Management:
+  Caching: distributed_redis
+  Sessions: redis_distributed
+
+Security:
+  Authentication: jwt_centralized
+  Authorization: rbac
+```
+
+### Set Strategy
+
+```bash
+dhurandhar strategy --set persistence
+```
+
+**Interactive**:
+```
+? Persistence model:
+  ❯ Database-per-Service (Full isolation, eventual consistency)
+    Shared Database (Monolith pattern, ACID transactions)
+    Hybrid (Mix of both)
+    Event Sourcing (Event log as source of truth)
+
+✓ persistence strategy set
+
+⚠ 3 services need alignment:
+  auth-service: Missing dedicated database
+  user-service: Missing dedicated database
+  payment-service: Missing dedicated database
+
+Run to auto-align:
+  dhurandhar strategy --align
+```
+
+### Pivot Strategy
+
+Change an existing strategy:
+
+```bash
+dhurandhar strategy --pivot communication
+```
+
+**Direct action**:
+```
+⚡ Pivot communication Strategy
+
+Current strategy:
+{
+  "primary_pattern": "synchronous_rest"
+}
+
+? This will update all services. Continue? Yes
+
+? Primary communication pattern:
+  Synchronous REST
+  ❯ Asynchronous Events
+  Hybrid
+  gRPC Streaming
+
+? Event bus technology:
+  ❯ Apache Kafka
+    RabbitMQ
+    AWS SNS/SQS
+    Redis Streams
+
+✓ communication strategy set
+✓ 3 services flagged for alignment
+```
+
+### Align Services
+
+Apply strategies to all existing services:
+
+```bash
+dhurandhar strategy --align
+```
+
+**Output**:
+```
+🔄 Align Services to Strategies
+
+✓ All services now match active strategies
+
+Check results:
+  dhurandhar service --list
+```
+
+## Global Strategy Injection
+
+### How It Works
+
+When you add a new service, strategies are automatically applied:
+
+```bash
+# Set strategies first
+dhurandhar strategy --set persistence
+  → database_per_service
+
+dhurandhar strategy --set communication
+  → asynchronous_events (Kafka)
+
+dhurandhar strategy --set security
+  → jwt_centralized
+
+# Add service
+dhurandhar service add "order-service: Process orders"
+```
+
+**Auto-Generated Service Definition**:
+```yaml
+services:
+  - name: order-service
+    scope: "Process orders"
+    tech_stack:
+      language: Go
+      framework: Echo
+      database: PostgreSQL
+    
+    # AUTO-INJECTED by persistence strategy
+    dedicated_database:
+      name: order_db
+      type: PostgreSQL
+      isolation: full
+    constraints:
+      - no_cross_service_queries
+      - eventual_consistency
+    
+    # AUTO-INJECTED by communication strategy
+    event_boundaries:
+      produces:
+        - order.created
+        - order.completed
+      consumes:
+        - payment.completed
+        - inventory.reserved
+      event_bus: kafka
+    
+    # AUTO-INJECTED by security strategy
+    dependencies:
+      - auth-service
+    authentication:
+      type: jwt
+      validation: centralized
+      token_endpoint: /api/v1/auth/validate
+```
+
+**Result**: Developer only specified service name and scope. Framework applied all architectural constraints automatically.
+
+## Extensibility Over Redesign
+
+### Pattern: Extend Existing Architecture
+
+When introducing new technical concepts (JWT rotation, Circuit Breakers, Event Sourcing):
+
+**❌ Old Way** (Redesign):
+```
+User: "Add JWT rotation"
+System: "Let's redesign the authentication system..."
+[Hours of discussion]
+```
+
+**✅ New Way** (Extension):
+```
+User: "Add JWT rotation"
+Agent: [Checks SDM: security.authentication = jwt_centralized ✓]
+Agent: "Extension of existing auth strategy"
+Agent: "Adding rotation endpoint to auth-service"
+✓ Story STORY-004: JWT Token Rotation
+✓ Added to auth-service (no redesign)
+```
+
+### Pattern: Strategy Pivot
+
+When fundamentally changing architecture:
+
+```bash
+# Current: Monolith with shared database
+dhurandhar strategy --pivot persistence
+
+? Persistence model:
+  ❯ Database-per-Service
+
+? This will update all services. Continue? Yes
+
+✓ Strategy pivoted
+✓ 5 services realigned
+✓ Each service now has dedicated database
+```
+
+**No justification loop. Direct pivot with impact analysis.**
+
+## Strategy Rehydration
+
+### Context Loading
+
+When starting a new session:
+
+```
+Agent loads SYSTEM_DESIGN_MAP.yaml:
+
+1. Metadata (project, architecture type)
+2. Tech Stack (languages, frameworks)
+3. **Technical Strategies** ← NEW
+4. Services, Entities
+5. Agile Blueprint
+6. Test Coverage
+
+Agent recognizes:
+"We are in a Database-per-Service + Event-Driven + JWT-Centralized context"
+
+All subsequent operations respect these constraints.
+```
+
+### Strategy-Aware Code Generation
+
+Test generation, code generation, and task creation all respect active strategies:
+
+```
+# With communication.primary_pattern: asynchronous_events
+
+dhurandhar test --generate
+
+Generated tests include:
+- Event producer tests (Kafka publish)
+- Event consumer tests (Kafka consume)
+- Message schema validation
+- Idempotency tests
+
+# With resilience.circuit_breaker: true
+
+Tests include:
+- Circuit breaker trigger tests
+- Fallback logic tests
+- Circuit recovery tests
+```
+
+## Benefits
+
+### 1. Zero Repeated Decisions
+
+Set once, apply everywhere:
+```
+Before: 5 services × 10 questions = 50 questions
+After: 1 strategy setup × 7 categories = 7 questions total
+```
+
+### 2. Architectural Consistency
+
+All services follow the same patterns automatically.
+
+### 3. Easy Pivots
+
+Change your mind? Pivot the strategy. All services update.
+
+### 4. Extensibility-First
+
+New features plug into existing strategies without redesign.
+
+### 5. Strategy Rehydration
+
+New sessions immediately understand architectural constraints.
+
+---
+
+**Dhurandhar v2.2: Engineering-First + Test-First + Strategy-Driven**