dhurandhar 1.0.0

package/docs/module-development.md

@@ -0,0 +1,323 @@
+# Module Development Guide
+
+Learn how to create custom design modules for Dhurandhar.
+
+## Overview
+
+Modules are the building blocks of Dhurandhar designs. Each module encapsulates:
+
+- System components (applications, services, datastores)
+- Relationships between components
+- Build and deployment processes
+- Configuration schemas
+- Validation rules
+
+## Module Structure
+
+A typical module directory structure:
+
+```
+my-module/
+├── module.yaml          # Module definition (required)
+├── README.md           # Documentation (recommended)
+├── templates/          # Template files (optional)
+├── utilities/          # Helper scripts (optional)
+└── schemas/            # Validation schemas (optional)
+```
+
+## Creating a Module
+
+### Step 1: Define module.yaml
+
+Create `src/modules/my-module/module.yaml`:
+
+```yaml
+code: my-module
+name: "My Custom Module"
+version: "1.0.0"
+description: "A brief description of what this module does"
+
+# Metadata
+author: "Dhurandhar Contributors"
+license: "MIT"
+tags:
+  - custom
+  - example
+
+# Dependencies (other modules this depends on)
+dependencies:
+  - core
+
+# Configuration schema
+config_schema:
+  my_setting:
+    type: string
+    default: "default_value"
+    description: "Description of this setting"
+
+# Design components
+design_components:
+  - name: component-1
+    type: application
+    description: "First component"
+    properties:
+      framework: "React"
+  
+  - name: component-2
+    type: service
+    description: "Second component"
+    properties:
+      framework: "Node.js"
+
+# Relationships
+relationships:
+  - from: component-1
+    to: component-2
+    type: http_client
+    description: "Component 1 calls Component 2"
+
+# Build processes
+build_processes:
+  - name: setup
+    description: "Initial setup"
+    steps:
+      - "Install dependencies"
+      - "Configure environment"
+  
+  - name: development
+    description: "Development workflow"
+    steps:
+      - "Start services"
+      - "Run in dev mode"
+
+# Exports
+exports:
+  templates:
+    - my-template
+  utilities:
+    - my-utility
+```
+
+### Step 2: Add Documentation
+
+Create `src/modules/my-module/README.md`:
+
+```markdown
+# My Custom Module
+
+Brief overview of the module.
+
+## Components
+
+Describe each component.
+
+## Usage
+
+How to use this module.
+
+## Configuration
+
+Configuration options.
+
+## Dependencies
+
+List dependencies.
+```
+
+### Step 3: Install the Module
+
+```bash
+node tools/cli/dhurandhar.js module --add my-module
+```
+
+## Module Fields Reference
+
+### Required Fields
+
+- **code**: Unique module identifier (lowercase, alphanumeric, hyphens)
+- **name**: Human-readable module name
+- **version**: Semantic version (e.g., "1.0.0")
+- **description**: Brief description (10-500 characters)
+
+### Optional Fields
+
+- **author**: Module author or organization
+- **license**: License identifier (default: "MIT")
+- **tags**: Array of tags for categorization
+- **dependencies**: Array of required module codes
+- **config_schema**: Configuration schema definition
+- **design_components**: System components
+- **relationships**: Component relationships
+- **build_processes**: Build and deployment workflows
+- **validation**: Validation rules
+- **exports**: Exported templates, utilities, schemas
+
+## Component Types
+
+Dhurandhar supports these component types:
+
+- **application**: User-facing applications (web, mobile, desktop)
+- **service**: Backend services (APIs, microservices)
+- **datastore**: Databases and data storage
+- **infrastructure**: Infrastructure components (load balancers, caches)
+- **external**: External systems and third-party services
+
+Example:
+
+```yaml
+design_components:
+  - name: web-app
+    type: application
+    description: "Web application"
+    properties:
+      framework: "React"
+      language: "TypeScript"
+```
+
+## Relationships
+
+Define how components interact:
+
+```yaml
+relationships:
+  - from: component-source
+    to: component-target
+    type: relationship-type
+    description: "How they relate"
+```
+
+Common relationship types:
+
+- **http_client**: HTTP/REST API calls
+- **data_access**: Database queries
+- **messaging**: Message queue communication
+- **event_stream**: Event streaming
+- **file_storage**: File system access
+
+## Build Processes
+
+Define workflows for different stages:
+
+```yaml
+build_processes:
+  - name: setup
+    description: "One-time setup"
+    steps:
+      - "Clone repository"
+      - "Install dependencies"
+  
+  - name: development
+    description: "Local development"
+    steps:
+      - "Start dev server"
+      - "Watch for changes"
+  
+  - name: test
+    description: "Run tests"
+    steps:
+      - "Unit tests"
+      - "Integration tests"
+  
+  - name: production
+    description: "Production deployment"
+    steps:
+      - "Build artifacts"
+      - "Deploy to production"
+```
+
+## Validation Rules
+
+Enforce design constraints:
+
+```yaml
+validation:
+  required_components:
+    - component-1
+    - component-2
+  
+  allowed_relationships:
+    - type: http_client
+      from_types: [application]
+      to_types: [service]
+```
+
+## Best Practices
+
+1. **Clear Naming**: Use descriptive, consistent names
+2. **Complete Documentation**: Include README with usage examples
+3. **Version Properly**: Follow semantic versioning
+4. **Declare Dependencies**: List all module dependencies
+5. **Validate**: Test your module with strict validation
+6. **Minimal Exports**: Only export what's necessary
+
+## Testing Your Module
+
+```bash
+# Install your module
+node tools/cli/dhurandhar.js module --add my-module
+
+# Validate
+node tools/cli/dhurandhar.js validate --strict
+
+# Check module info
+node tools/cli/dhurandhar.js module --info my-module
+```
+
+## Advanced Features
+
+### Configuration Schema
+
+Define typed configuration:
+
+```yaml
+config_schema:
+  api_endpoint:
+    type: string
+    default: "http://localhost:8080"
+    description: "API endpoint URL"
+  
+  max_connections:
+    type: number
+    default: 10
+    description: "Maximum connections"
+  
+  enable_ssl:
+    type: boolean
+    default: true
+    description: "Enable SSL"
+```
+
+### Module Dependencies
+
+Modules can depend on other modules:
+
+```yaml
+dependencies:
+  - core
+  - common-utilities
+```
+
+Dependencies are automatically installed.
+
+## Publishing Modules
+
+To share your module:
+
+1. Ensure complete documentation
+2. Test thoroughly with validation
+3. Follow semantic versioning
+4. Include LICENSE file
+5. Add to module registry (when available)
+
+## Example Modules
+
+Study these examples:
+
+- **core**: Framework fundamentals
+- **example**: Three-tier web app
+
+## Next Steps
+
+- [Configuration Guide](configuration.md)
+- [CLI Reference](cli-reference.md)
+- [Schema Reference](../src/core/schemas/design-module-schema.yaml)

package/docs/strategy-example.md

@@ -0,0 +1,299 @@
+# Pluggable Strategies - Complete Example
+
+## Scenario: Building Event-Driven E-Commerce Platform
+
+Let's build a complete e-commerce platform using pluggable strategies.
+
+## Step 1: Initialize Framework
+
+```bash
+dhurandhar install
+
+? Project identifier: ecommerce-platform
+? Architecture type: microservices
+? Primary language: go
+
+✓ Framework installed
+```
+
+## Step 2: Set Architectural Strategies (5 Minutes)
+
+### Persistence Strategy: Database-per-Service
+
+```bash
+dhurandhar strategy --set persistence
+
+? Persistence model:
+  ❯ Database-per-Service
+
+✓ persistence strategy set
+```
+
+### Communication Strategy: Event-Driven (Kafka)
+
+```bash
+dhurandhar strategy --set communication
+
+? Primary communication pattern:
+  ❯ Asynchronous Events
+
+? Event bus technology:
+  ❯ Apache Kafka
+
+✓ communication strategy set
+```
+
+### State Management: Distributed Redis
+
+```bash
+dhurandhar strategy --set state
+
+? Caching layer:
+  ❯ Distributed Redis
+
+✓ state strategy set
+```
+
+### Security: JWT Centralized
+
+```bash
+dhurandhar strategy --set security
+
+? Authentication strategy:
+  ❯ JWT Centralized
+
+✓ security strategy set
+```
+
+### Resilience: Circuit Breaker Enabled
+
+```bash
+dhurandhar strategy --set resilience
+
+? Enable circuit breaker pattern? Yes
+
+✓ resilience strategy set
+```
+
+## Step 3: View Active Strategies
+
+```bash
+dhurandhar strategy --show
+
+📐 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
+
+Resilience:
+  Circuit Breaker: enabled
+  Retry: exponential_backoff
+  Timeout: moderate_30s
+```
+
+## Step 4: Add Services (Strategy Auto-Injection)
+
+### Service 1: Auth Service
+
+```bash
+dhurandhar service add "auth: JWT authentication and session management"
+
+✓ auth-service added: Go/Echo/PostgreSQL
+  - Dedicated database: auth_db (db-per-service strategy)
+  - Events: produces[user.authenticated], consumes[]
+  - Auth: Self (auth service)
+  - Resilience: Circuit breaker enabled
+  - Cache: Redis dependency added
+```
+
+### Service 2: User Service
+
+```bash
+dhurandhar service add "user: User profile CRUD operations"
+
+✓ user-service added: Go/Echo/PostgreSQL
+  - Dedicated database: user_db (db-per-service strategy)
+  - Events: produces[user.created, user.updated], consumes[user.authenticated]
+  - Auth: JWT validation via auth-service
+  - Resilience: Circuit breaker enabled
+  - Cache: Redis dependency added
+```
+
+### Service 3: Order Service
+
+```bash
+dhurandhar service add "order: Process customer orders"
+
+✓ order-service added: Go/Echo/PostgreSQL
+  - Dedicated database: order_db (db-per-service strategy)
+  - Events: produces[order.created, order.completed], consumes[payment.completed, inventory.reserved]
+  - Auth: JWT validation via auth-service
+  - Resilience: Circuit breaker enabled
+  - Cache: Redis dependency added
+```
+
+### Service 4: Payment Service
+
+```bash
+dhurandhar service add "payment: Process payments via Stripe"
+
+✓ payment-service added: Go/Echo/PostgreSQL
+  - Dedicated database: payment_db (db-per-service strategy)
+  - Events: produces[payment.completed, payment.failed], consumes[order.created]
+  - Auth: JWT validation via auth-service
+  - Resilience: Circuit breaker enabled
+  - Cache: Redis dependency added
+```
+
+### Service 5: Inventory Service
+
+```bash
+dhurandhar service add "inventory: Manage product stock"
+
+✓ inventory-service added: Go/Echo/PostgreSQL
+  - Dedicated database: inventory_db (db-per-service strategy)
+  - Events: produces[inventory.reserved, inventory.released], consumes[order.created]
+  - Auth: JWT validation via auth-service
+  - Resilience: Circuit breaker enabled
+  - Cache: Redis dependency added
+```
+
+## Step 5: View Complete Architecture
+
+```bash
+dhurandhar context --full
+
+🏗️  System Architecture Context
+
+Project Metadata
+Name: ecommerce-platform
+Architecture: microservices
+
+Active Architectural Strategies
+  Persistence: database_per_service
+  Communication: asynchronous_events
+    Event Bus: kafka
+  Caching: distributed_redis
+  Auth: jwt_centralized
+  Resilience: Circuit Breaker enabled
+
+Services (5)
+  auth-service
+    JWT authentication and session management
+    Stack: Go/Echo/PostgreSQL
+    Dedicated DB: auth_db
+    Events: produces[user.authenticated]
+    
+  user-service
+    User profile CRUD operations
+    Stack: Go/Echo/PostgreSQL
+    Dedicated DB: user_db
+    Events: produces[user.created, user.updated] | consumes[user.authenticated]
+    
+  order-service
+    Process customer orders
+    Stack: Go/Echo/PostgreSQL
+    Dedicated DB: order_db
+    Events: produces[order.created, order.completed] | consumes[payment.completed, inventory.reserved]
+    
+  payment-service
+    Process payments via Stripe
+    Stack: Go/Echo/PostgreSQL
+    Dedicated DB: payment_db
+    Events: produces[payment.completed, payment.failed] | consumes[order.created]
+    
+  inventory-service
+    Manage product stock
+    Stack: Go/Echo/PostgreSQL
+    Dedicated DB: inventory_db
+    Events: produces[inventory.reserved, inventory.released] | consumes[order.created]
+```
+
+## Step 6: Strategy Pivot Example
+
+### Scenario: Switch from Kafka to RabbitMQ
+
+```bash
+dhurandhar strategy --pivot communication
+
+⚡ Pivot communication Strategy
+
+Current strategy:
+{
+  "primary_pattern": "asynchronous_events",
+  "event_bus": {
+    "technology": "kafka"
+  }
+}
+
+? This will update all services. Continue? Yes
+
+? Event bus technology:
+  Apache Kafka
+  ❯ RabbitMQ
+  AWS SNS/SQS
+  Redis Streams
+
+✓ communication strategy set
+
+Realigning 5 services...
+✓ All services updated to use RabbitMQ
+
+Changes:
+  - auth-service: Event bus → RabbitMQ
+  - user-service: Event bus → RabbitMQ
+  - order-service: Event bus → RabbitMQ
+  - payment-service: Event bus → RabbitMQ
+  - inventory-service: Event bus → RabbitMQ
+```
+
+**Result**: All 5 services updated in seconds. No manual edits needed.
+
+## Benefits Demonstrated
+
+### 1. Time Savings
+
+**Without Strategies**:
+- 5 services × 10 questions each = 50 questions
+- Time: 30-60 minutes
+
+**With Strategies**:
+- 1 strategy setup (7 categories) = 5 minutes
+- 5 services × 1 question each = 5 questions
+- Time: 10 minutes total
+
+**Savings**: 4-6x faster
+
+### 2. Consistency
+
+All services follow the same patterns:
+- Database-per-service (no cross-service queries)
+- Event-driven communication (Kafka)
+- JWT authentication (centralized)
+- Circuit breaker enabled
+- Redis caching
+
+### 3. Easy Pivots
+
+Changed Kafka → RabbitMQ in seconds, all services updated.
+
+### 4. Zero Cognitive Fatigue
+
+No repeated questions about database isolation, event bus, auth, etc.
+
+---
+
+**Result**: Complete event-driven e-commerce platform with 5 microservices, defined in 15 minutes with full architectural consistency.