dhurandhar 1.0.0

package/src/core/schemas/system-design-map-schema.yaml

@@ -0,0 +1,324 @@
+# System Design Map (SDM) Schema
+# Cross-session persistence format for architectural state
+# Purpose: Enable instant context rehydration without re-discovery
+
+schema_version: "1.0"
+name: "system-design-map"
+description: "Persistent architectural state for context rehydration"
+
+# The SDM is stored at project root as SYSTEM_DESIGN_MAP.yaml
+# Agents read this first to understand current architecture
+
+structure:
+  # Metadata
+  metadata:
+    project_name: string
+    version: string
+    last_updated: timestamp
+    architecture_type: string  # monolith, microservices, serverless, hybrid
+    
+  # Tech Stack Summary
+  tech_stack:
+    languages: [string]
+    frameworks: [string]
+    databases: [string]
+    infrastructure: [string]
+    
+  # User Types (who uses the system)
+  user_types:
+    - role: string
+      permissions: [string]
+      authentication: string
+      
+  # Entities (data model)
+  entities:
+    - name: string
+      attributes:
+        - name: string
+          type: string
+          constraints: [string]
+      relationships:
+        - type: one_to_one | one_to_many | many_to_one | many_to_many
+          target: string
+          foreign_key: string
+          
+  # Services (microservices or modules)
+  services:
+    - name: string
+      scope: string  # what it does
+      tech_stack:
+        language: string
+        framework: string
+        database: string
+      api:
+        type: rest | grpc | graphql
+        base_path: string
+        port: integer
+      dependencies: [string]  # other services
+      data_access: [string]   # entities
+      
+  # Service Communication (how services talk)
+  communication:
+    - from: string  # service name
+      to: string    # service name
+      protocol: string  # http, grpc, message_queue, event_bus
+      pattern: string   # sync, async, pub_sub
+      
+  # Infrastructure (deployment & ops)
+  infrastructure:
+    deployment_target: string  # docker, kubernetes, aws_lambda, etc.
+    components:
+      - type: string  # load_balancer, cache, message_queue, etc.
+        name: string
+        technology: string  # nginx, redis, rabbitmq, etc.
+        
+  # Build & Deployment
+  build_config:
+    - service: string
+      build_tool: string  # make, npm, cargo, gradle, etc.
+      dockerfile: boolean
+      ci_cd: string      # github_actions, gitlab_ci, etc.
+
+  # Technical Decision Registry - Centralized "Stock of Decisions"
+  decision_registry:
+    naming_conventions:
+      case_styles:
+        classes: PascalCase | camelCase | snake_case
+        functions: PascalCase | camelCase | snake_case
+        variables: PascalCase | camelCase | snake_case
+        constants: SCREAMING_SNAKE_CASE | PascalCase
+        database_tables: snake_case | PascalCase
+        database_columns: snake_case | camelCase
+        api_endpoints: kebab-case | snake_case
+
+      file_patterns:
+        components: string
+        services: string
+        models: string
+        tests: string
+
+      prefixes_suffixes:
+        interfaces: string
+        abstract_classes: string
+        test_functions: string
+        private_methods: string
+
+    design_patterns:
+      data_access: repository_pattern | active_record | data_mapper
+      service_layer: service_classes | function_modules | handlers_only
+      dependency_injection: constructor_injection | property_injection | none
+      validation: dto_validation | middleware_validation | domain_validation
+      cqrs: boolean
+      event_sourcing: boolean
+      domain_driven_design: boolean
+      service_specific_patterns:
+        - service: string
+          pattern: string
+          rationale: string
+
+    error_response_standards:
+      error_code_mapping:
+        validation_error: integer (HTTP status)
+        authentication_error: integer
+        authorization_error: integer
+        not_found_error: integer
+        conflict_error: integer
+        internal_error: integer
+
+      response_envelope:
+        success_format: string (JSON template)
+        error_format: string (JSON template)
+        include_request_id: boolean
+        include_timestamp: boolean
+
+      error_detail_level: minimal | standard | verbose | debug_only
+
+    observability_standards:
+      logging:
+        levels: [string] (e.g., DEBUG, INFO, WARN, ERROR)
+        structured_logging: boolean
+        mandatory_fields: [string] (e.g., trace_id, service_name)
+        sensitive_data_masking: boolean
+
+      tracing:
+        trace_id_header: string (e.g., X-Trace-ID)
+        correlation_id_header: string (e.g., X-Correlation-ID)
+        span_naming_format: string
+
+      metrics:
+        naming_format: string (e.g., service_metric_unit)
+        mandatory_labels: [string] (e.g., service, environment)
+        latency_buckets: [number]
+
+    api_standards:
+      versioning_strategy: url_path | header | query_param
+      version_format: string (e.g., v1, 1.0)
+      pagination:
+        style: offset_limit | cursor | page_number
+        default_page_size: integer
+        max_page_size: integer
+      rate_limiting:
+        enabled: boolean
+        default_limit: integer
+        window: string
+
+    code_quality_standards:
+      test_coverage_minimum: integer (percentage)
+      documentation_required: boolean
+      linting_rules: string
+      code_review_required: boolean
+
+  # Technical Strategies - Pluggable Architectural Patterns
+  technical_strategies:
+    persistence:
+      model: database_per_service | shared_database | hybrid | event_sourcing
+      constraints: [string]
+      database_assignments:
+        service-name: database-instance
+
+    state_management:
+      caching_layer: distributed_redis | local_in_memory | sidecar_cache | cdn_edge | none
+      session_storage: redis_distributed | database | jwt_stateless | sticky_sessions
+      cache_invalidation: ttl_based | event_driven | manual | write_through
+
+    communication:
+      primary_pattern: synchronous_rest | asynchronous_events | hybrid | grpc_streaming
+      event_bus:
+        technology: kafka | rabbitmq | aws_sns_sqs | redis_streams | nats
+        topics_or_queues: [string]
+        message_format: json | avro | protobuf
+      api_gateway:
+        technology: nginx | kong | aws_api_gateway | envoy
+        features: [string]
+
+    deployment:
+      orchestration: kubernetes | docker_swarm | ecs | serverless
+      scaling_strategy: horizontal_pod_autoscaling | vertical_scaling | manual
+      service_mesh:
+        enabled: boolean
+        technology: istio | linkerd | consul | none
+
+    observability:
+      logging: centralized_elk | cloudwatch | datadog | loki
+      metrics: prometheus | datadog | cloudwatch
+      tracing: jaeger | zipkin | aws_xray | datadog_apm
+      distributed_tracing: boolean
+
+    security:
+      authentication: jwt_centralized | oauth2_delegated | mtls | api_keys
+      authorization: rbac | abac | policy_engine_opa | service_level
+      secrets_management: vault | aws_secrets_manager | kubernetes_secrets
+
+    resilience:
+      circuit_breaker: boolean
+      retry_strategy: exponential_backoff | fixed_delay | none
+      timeout_policy: aggressive_5s | moderate_30s | lenient_60s
+      bulkhead_isolation: boolean
+
+  # Agile Blueprint - Test-First Decomposition
+  agile_blueprint:
+    epics:
+      - id: string       # EPIC-001
+        name: string     # "User Authentication & Authorization"
+        description: string
+        stories:
+          - id: string   # STORY-001
+            name: string # "OAuth2 Social Login Flow"
+            interaction_boundary:
+              service: string
+              api_endpoint: string
+              method: string
+              request_contract: object
+              response_contract: object
+              error_states: [integer]
+            technical_acceptance: [string]
+            tasks:
+              - id: string  # TASK-001
+                description: string
+                type: test | implementation | infrastructure | migration
+                linked_to:
+                  type: service | entity | infrastructure
+                  name: string
+                status: not_started | in_progress | complete | blocked
+                test_coverage:
+                  test_file: string
+                  standard_flows: boolean
+                  error_states: boolean
+                  edge_cases: boolean
+
+    test_suite_status:
+      total_stories: integer
+      tested_stories: integer
+      coverage_percentage: number
+      last_test_run: timestamp
+
+# Example SDM
+example:
+  metadata:
+    project_name: "example-saas"
+    version: "1.0.0"
+    last_updated: "2024-03-27T10:00:00Z"
+    architecture_type: "microservices"
+    
+  tech_stack:
+    languages: ["Go", "TypeScript"]
+    frameworks: ["Echo", "React"]
+    databases: ["PostgreSQL", "Redis"]
+    infrastructure: ["Docker", "Kubernetes"]
+    
+  user_types:
+    - role: "admin"
+      permissions: ["read:*", "write:*", "delete:*"]
+      authentication: "jwt"
+    - role: "user"
+      permissions: ["read:own", "write:own"]
+      authentication: "jwt"
+      
+  entities:
+    - name: "User"
+      attributes:
+        - name: "id"
+          type: "uuid"
+          constraints: ["primary_key"]
+        - name: "email"
+          type: "varchar"
+          constraints: ["unique", "not_null"]
+      relationships:
+        - type: "one_to_many"
+          target: "Post"
+          foreign_key: "user_id"
+          
+  services:
+    - name: "auth-service"
+      scope: "JWT authentication and session management"
+      tech_stack:
+        language: "Go"
+        framework: "Echo"
+        database: "PostgreSQL"
+      api:
+        type: "rest"
+        base_path: "/api/v1/auth"
+        port: 8080
+      data_access: ["User"]
+      
+  communication:
+    - from: "web-frontend"
+      to: "auth-service"
+      protocol: "http"
+      pattern: "sync"
+      
+  infrastructure:
+    deployment_target: "kubernetes"
+    components:
+      - type: "load_balancer"
+        name: "nginx-ingress"
+        technology: "nginx"
+      - type: "cache"
+        name: "redis-cache"
+        technology: "redis"
+        
+  build_config:
+    - service: "auth-service"
+      build_tool: "make"
+      dockerfile: true
+      ci_cd: "github_actions"

package/src/modules/example/README.md

@@ -0,0 +1,130 @@
+# Example Design Module
+
+A sample module demonstrating how to create design modules in Dhurandhar.
+
+## Overview
+
+This module showcases:
+
+- **Component Definition**: How to define system components (applications, services, datastores)
+- **Relationships**: How to express dependencies between components
+- **Build Processes**: How to define setup, development, and deployment workflows
+- **Validation**: How to enforce design constraints and rules
+
+## Architecture
+
+This example implements a three-tier web application:
+
+```
+┌─────────────────┐
+│  Web Frontend   │ (React + TypeScript)
+│   Port: 3000    │
+└────────┬────────┘
+         │ HTTP
+         ▼
+┌─────────────────┐
+│  API Service    │ (Node.js + TypeScript)
+│   Port: 8080    │
+└────────┬────────┘
+         │ SQL
+         ▼
+┌─────────────────┐
+│   PostgreSQL    │
+│   Version: 15   │
+└─────────────────┘
+```
+
+## Components
+
+### Web Frontend
+- **Type**: Application
+- **Framework**: React
+- **Language**: TypeScript
+- **Port**: 3000
+
+### API Service
+- **Type**: Service
+- **Framework**: Node.js
+- **Language**: TypeScript
+- **Port**: 8080
+
+### Database
+- **Type**: Datastore
+- **Engine**: PostgreSQL
+- **Version**: 15
+
+## Build Processes
+
+### Setup
+Initial project setup including:
+1. Install dependencies
+2. Configure environment
+3. Initialize database
+
+### Development
+Local development workflow:
+1. Start database container
+2. Run API in dev mode
+3. Run frontend in dev mode
+
+### Production
+Production deployment:
+1. Build frontend assets
+2. Build API container
+3. Deploy database migrations
+4. Deploy containers
+
+## Usage
+
+Install this module:
+
+```bash
+dhurandhar module --add example
+```
+
+View module information:
+
+```bash
+dhurandhar module --info example
+```
+
+## Customization
+
+You can use this module as a template for your own designs:
+
+1. Copy the module structure
+2. Modify `module.yaml` with your components
+3. Define your relationships
+4. Specify your build processes
+5. Add validation rules
+
+## Configuration
+
+Configure the example module in `.dhurandhar/config.yaml`:
+
+```yaml
+modules:
+  example:
+    example_setting: "my_value"
+    enable_feature: true
+```
+
+## Validation Rules
+
+This module enforces:
+
+- Required components must exist
+- Only allowed relationship types between component types
+- Component type constraints
+
+## Dependencies
+
+- **core**: Dhurandhar Core Module (required)
+
+## Version
+
+0.1.0
+
+## License
+
+MIT

package/src/modules/example/module.yaml

@@ -0,0 +1,252 @@
+code: example
+name: "Example SaaS Platform - Engineering Blueprint"
+version: "2.0.0"
+description: "Technical blueprint for a multi-tenant SaaS platform with microservices"
+
+# Module metadata
+author: "Dhurandhar Project"
+license: "MIT"
+tags:
+  - saas
+  - microservices
+  - example
+
+# Dependencies
+dependencies:
+  - core
+
+# Tech Stack
+tech_stack:
+  primary_language: "Go"
+  frameworks: ["Echo", "GORM"]
+  databases: ["PostgreSQL", "Redis"]
+  infrastructure: ["Docker", "Kubernetes", "Nginx"]
+
+# User Types - Technical definition
+user_types:
+  - role: "admin"
+    permissions: ["read:*", "write:*", "delete:*"]
+    authentication: "jwt"
+    attributes:
+      is_superuser: true
+
+  - role: "tenant_admin"
+    permissions: ["read:tenant", "write:tenant", "manage:users"]
+    authentication: "jwt"
+    attributes:
+      tenant_id: "required"
+
+  - role: "user"
+    permissions: ["read:own", "write:own"]
+    authentication: "jwt"
+    attributes:
+      tenant_id: "required"
+
+  - role: "api_client"
+    permissions: ["read:api", "write:api"]
+    authentication: "api_key"
+
+# Entities - ERD-like data model
+entities:
+  - name: "Tenant"
+    table_name: "tenants"
+    attributes:
+      - name: "id"
+        type: "uuid"
+        constraints: ["primary_key"]
+      - name: "name"
+        type: "varchar"
+        constraints: ["not_null", "unique"]
+      - name: "subdomain"
+        type: "varchar"
+        constraints: ["not_null", "unique", "indexed"]
+      - name: "plan"
+        type: "varchar"
+        constraints: ["not_null"]
+      - name: "status"
+        type: "varchar"
+        constraints: ["not_null"]
+      - name: "created_at"
+        type: "timestamp"
+        constraints: ["not_null"]
+    relationships:
+      - type: "one_to_many"
+        target: "User"
+        foreign_key: "tenant_id"
+
+  - name: "User"
+    table_name: "users"
+    attributes:
+      - name: "id"
+        type: "uuid"
+        constraints: ["primary_key"]
+      - name: "tenant_id"
+        type: "uuid"
+        constraints: ["not_null", "indexed"]
+      - name: "email"
+        type: "varchar"
+        constraints: ["not_null", "unique"]
+      - name: "password_hash"
+        type: "varchar"
+        constraints: ["not_null"]
+      - name: "role"
+        type: "varchar"
+        constraints: ["not_null"]
+      - name: "created_at"
+        type: "timestamp"
+        constraints: ["not_null"]
+    relationships:
+      - type: "many_to_one"
+        target: "Tenant"
+        foreign_key: "tenant_id"
+      - type: "one_to_many"
+        target: "Session"
+        foreign_key: "user_id"
+
+  - name: "Session"
+    table_name: "sessions"
+    attributes:
+      - name: "id"
+        type: "uuid"
+        constraints: ["primary_key"]
+      - name: "user_id"
+        type: "uuid"
+        constraints: ["not_null", "indexed"]
+      - name: "token"
+        type: "varchar"
+        constraints: ["not_null", "unique"]
+      - name: "expires_at"
+        type: "timestamp"
+        constraints: ["not_null"]
+      - name: "created_at"
+        type: "timestamp"
+        constraints: ["not_null"]
+    relationships:
+      - type: "many_to_one"
+        target: "User"
+        foreign_key: "user_id"
+
+# Services - Microservices with tech stack
+services:
+  - name: "auth-service"
+    scope: "JWT authentication, session management, and tenant isolation"
+    tech_stack:
+      language: "Go"
+      framework: "Echo"
+      database: "PostgreSQL"
+      orm: "GORM"
+    api:
+      type: "rest"
+      base_path: "/api/v1/auth"
+      port: 8080
+      endpoints:
+        - method: "POST"
+          path: "/login"
+          description: "Authenticate user, return JWT"
+        - method: "POST"
+          path: "/logout"
+          description: "Invalidate session"
+        - method: "POST"
+          path: "/refresh"
+          description: "Refresh JWT token"
+    dependencies: []
+    data_access: ["User", "Session", "Tenant"]
+    environment:
+      required: ["DATABASE_URL", "JWT_SECRET", "JWT_EXPIRY"]
+
+  - name: "tenant-service"
+    scope: "Multi-tenant management, provisioning, and billing"
+    tech_stack:
+      language: "Go"
+      framework: "Echo"
+      database: "PostgreSQL"
+      orm: "GORM"
+    api:
+      type: "rest"
+      base_path: "/api/v1/tenants"
+      port: 8081
+    dependencies: ["auth-service"]
+    data_access: ["Tenant", "User"]
+    environment:
+      required: ["DATABASE_URL"]
+
+  - name: "user-service"
+    scope: "User CRUD, profile management, role assignment"
+    tech_stack:
+      language: "Go"
+      framework: "Echo"
+      database: "PostgreSQL"
+      orm: "GORM"
+    api:
+      type: "rest"
+      base_path: "/api/v1/users"
+      port: 8082
+    dependencies: ["auth-service"]
+    data_access: ["User", "Tenant"]
+    environment:
+      required: ["DATABASE_URL"]
+
+# Service Communication
+communication:
+  - from: "tenant-service"
+    to: "auth-service"
+    protocol: "http"
+    pattern: "sync"
+  - from: "user-service"
+    to: "auth-service"
+    protocol: "http"
+    pattern: "sync"
+
+# Infrastructure
+infrastructure:
+  deployment_target: "kubernetes"
+  components:
+    - type: "load_balancer"
+      name: "nginx-ingress"
+      technology: "nginx"
+    - type: "cache"
+      name: "redis-cache"
+      technology: "redis"
+    - type: "database"
+      name: "postgres-cluster"
+      technology: "postgresql"
+
+# Build Configuration
+build_config:
+  - service: "auth-service"
+    build_tool: "make"
+    dockerfile: true
+    ci_cd: "github_actions"
+
+  - service: "tenant-service"
+    build_tool: "make"
+    dockerfile: true
+    ci_cd: "github_actions"
+
+  - service: "user-service"
+    build_tool: "make"
+    dockerfile: true
+    ci_cd: "github_actions"
+
+# Build process definitions (simplified)
+build_processes:
+  - name: "setup"
+    description: "Local development setup"
+    steps:
+      - "make deps"
+      - "docker-compose up -d postgres redis"
+      - "make migrate"
+
+  - name: "development"
+    description: "Start all services"
+    steps:
+      - "make run-auth"
+      - "make run-tenant"
+      - "make run-user"
+
+  - name: "production"
+    description: "Deploy to Kubernetes"
+    steps:
+      - "make build-all"
+      - "kubectl apply -f k8s/"
+      - "make migrate-prod"