dhurandhar 1.0.0

package/docs/engineering-first-philosophy.md

@@ -0,0 +1,263 @@
+# Engineering-First Philosophy
+
+## Problem Statement
+
+Traditional system design frameworks suffer from:
+
+1. **Cognitive Fatigue**: Excessive philosophical prompting ("Why do you need this?")
+2. **Architectural Drift**: Lost context between sessions requires rediscovery
+3. **Justification Loops**: Endless "have you considered..." discussions
+4. **Business-Process Heavy**: Focus on stakeholders over technical implementation
+
+## Dhurandhar's Solution
+
+### 1. Engineering First, Not Business First
+
+❌ **Traditional Approach**:
+```
+Agent: "Why do you need an authentication service?"
+User: "For user login"
+Agent: "What are your authentication requirements?"
+User: "JWT tokens"
+Agent: "Have you considered OAuth2?"
+User: "No, I want JWT"
+Agent: "What's the business value?"
+User: "Just add JWT auth!"
+Agent: "Let's explore the requirements together..."
+```
+
+✅ **Dhurandhar Approach**:
+```
+User: "Add auth service"
+Agent: [Checks SDM for primary language: Go]
+Agent: "Framework: Echo, Gin, or Fiber?"
+User: "Echo"
+Agent: "Database: PostgreSQL or Redis?"
+User: "PostgreSQL"
+Agent: "✓ auth-service added: Go/Echo/PostgreSQL on port 8080"
+```
+
+**3 questions. Done. No justifications.**
+
+### 2. Direct Action Over Discovery
+
+**Principle**: When a user requests something, they've already made the decision.
+
+Your job: Get technical specs and implement.
+Not your job: Question the decision.
+
+**Max 3 Technical Questions** per component:
+1. Technology choice (if not obvious from context)
+2. Integration point
+3. Configuration detail
+
+Then implement. No further discussion unless explicitly requested.
+
+### 3. Persistent Context via SDM
+
+**Problem**: Context loss between sessions
+
+```
+Session 1:
+User: "Add user service with PostgreSQL"
+Agent: "Done"
+
+[New session starts]
+
+Session 2:
+User: "Add posts that belong to users"
+Agent: "What database are you using?"  ← COGNITIVE FATIGUE
+User: "I told you last time! PostgreSQL!"
+```
+
+**Solution**: System Design Map
+
+```
+Session 1:
+User: "Add user service with PostgreSQL"
+Agent: "✓ Updated SYSTEM_DESIGN_MAP.yaml"
+
+[New session starts]
+
+Session 2:
+Agent: [Reads SDM - sees PostgreSQL, User entity exists]
+User: "Add posts that belong to users"
+Agent: "✓ Post entity added with user_id foreign key"
+```
+
+No rediscovery. No cognitive fatigue.
+
+### 4. Implementation Focus
+
+Focus on:
+- **What**: Component name and purpose
+- **How**: Tech stack, API, database
+- **Where**: Integration points
+
+Ignore:
+- **Why**: Business justification
+- **Who**: Stakeholders
+- **When**: Timeline (not architecture concern)
+
+### 5. Tech Stack Mandated Upfront
+
+On framework initialization (3 questions only):
+1. Architecture type: microservices/monolith/serverless
+2. Primary language: Go/TypeScript/Python/Rust/Java
+3. Done.
+
+All subsequent services inherit sensible defaults:
+- Go → Echo framework, PostgreSQL
+- TypeScript → Express, PostgreSQL
+- Python → FastAPI, PostgreSQL
+
+No framework debates for every service.
+
+## Workflow Comparison
+
+### Traditional (Business-Heavy)
+
+```
+1. Discovery phase (30 minutes)
+   - What's the business problem?
+   - Who are the stakeholders?
+   - What are the requirements?
+   - Have you considered alternatives?
+   
+2. Requirements documentation (1 hour)
+   - User stories
+   - Acceptance criteria
+   - Business value analysis
+   
+3. Architecture discussion (1 hour)
+   - Explore options
+   - Pros/cons analysis
+   - Technology evaluation
+   
+4. Finally: Add service (5 minutes)
+
+Total: 2.5 hours for one service
+```
+
+### Dhurandhar (Engineering-First)
+
+```
+1. Check SDM for context (5 seconds)
+2. Ask 3 technical questions (30 seconds)
+3. Add service to SDM (10 seconds)
+4. Confirm (5 seconds)
+
+Total: 50 seconds for one service
+```
+
+**300x faster.**
+
+## Anti-Patterns to Avoid
+
+### ❌ Justification Loop
+```
+Agent: "Why do you need Redis?"
+User: "For caching"
+Agent: "What's your caching strategy?"
+User: "LRU with 1 hour TTL"
+Agent: "Have you measured cache hit rates?"
+User: "No, I just want caching!"
+Agent: "Let's define metrics first..."
+```
+
+### ❌ Alternative Exploration
+```
+User: "Use PostgreSQL"
+Agent: "Have you considered MongoDB?"
+User: "No"
+Agent: "What about MySQL?"
+User: "No, PostgreSQL"
+Agent: "But MongoDB might be better for..."
+```
+
+### ❌ Requirements Gathering
+```
+User: "Add user service"
+Agent: "Let's gather requirements first.
+       What fields does a user have?
+       What operations are needed?
+       What's the expected load?
+       What's the data retention policy?..."
+```
+
+## Engineering-First Patterns
+
+### ✅ Direct Technical Questions
+```
+User: "Add caching"
+Agent: "Cache: Redis or Memcached?"
+User: "Redis"
+Agent: "✓ Redis added to infrastructure"
+```
+
+### ✅ Context-Aware Defaults
+```
+User: "Add payment service"
+Agent: [Checks SDM - primary language is Go, using Echo/PostgreSQL]
+Agent: "✓ payment-service added: Go/Echo/PostgreSQL on port 8082"
+Agent: [Auto-incremented port based on existing services]
+```
+
+### ✅ Minimal Confirmation
+```
+User: "Add User entity"
+Agent: "✓ User entity added (5 attributes)"
+```
+
+## Implementation Rules
+
+1. **Always read SDM first** before asking any questions
+2. **Max 3 questions** per architectural component
+3. **Technical questions only** (language/database/protocol)
+4. **Brief confirmations** (one line)
+5. **Update SDM immediately** after changes
+6. **No "why" questions** unless architectural conflict exists
+
+## Session Management
+
+### Starting New Session
+
+```
+Agent initialization:
+1. Read SYSTEM_DESIGN_MAP.yaml
+2. Load architecture context
+3. Display brief summary
+4. Ready for commands
+
+Agent: "Rehydrated from SDM:
+        - 3 services (Go/Echo stack)
+        - 5 entities
+        - Microservices architecture
+        Ready. What's next?"
+```
+
+### Ending Session
+
+```
+Agent: "Session changes:
+        ✓ 2 services added
+        ✓ 1 entity modified
+        All persisted to SYSTEM_DESIGN_MAP.yaml"
+```
+
+## Benefits
+
+1. **Reduced Cognitive Load**: No justification overhead
+2. **Faster Decisions**: Technical specs only
+3. **Session Continuity**: Context persists via SDM
+4. **Predictable Interactions**: Always 3 questions max
+5. **Focus on Implementation**: Build, don't plan endlessly
+
+## Remember
+
+> "Engineers make technical decisions. 
+> Agents implement them.
+> SDM persists them.
+> No ceremony required."
+
+Dhurandhar: Engineering first, ceremony last.

package/docs/getting-started.md

@@ -0,0 +1,218 @@
+# Getting Started with Dhurandhar
+
+This guide will help you get started with Dhurandhar, a framework for system design and build processes.
+
+## Prerequisites
+
+Before you begin, ensure you have:
+
+- Node.js version 20.0.0 or higher
+- npm (comes with Node.js) or yarn
+- A text editor (VS Code, Sublime Text, etc.)
+- Basic familiarity with YAML
+
+## Installation
+
+### Step 1: Clone or Install
+
+If you're starting a new project:
+
+```bash
+# Clone the repository
+git clone https://github.com/rweb22/dhurandhar.git
+cd dhurandhar
+
+# Install dependencies
+npm install
+```
+
+### Step 2: Initialize Framework
+
+Run the installation command to set up Dhurandhar in your project:
+
+```bash
+# Interactive installation (recommended for first time)
+npm run install:framework
+```
+
+You'll be prompted for:
+
+1. **Project Name**: A unique identifier for your project (lowercase, alphanumeric, hyphens)
+2. **User Name**: What the framework should call you (or your team name)
+3. **Output Folder**: Where generated files should be saved (default: `_dhurandhar-output`)
+4. **Modules**: Which modules to install (at minimum, select `core`)
+
+### Step 3: Verify Installation
+
+Check that everything is set up correctly:
+
+```bash
+# Show configuration
+node tools/cli/dhurandhar.js config --show
+
+# Validate installation
+node tools/cli/dhurandhar.js validate
+```
+
+You should see:
+- Configuration details displayed
+- All validations passing with green checkmarks
+
+## Your First Design
+
+Let's create a simple three-tier web application design.
+
+### Step 1: Install Example Module
+
+```bash
+node tools/cli/dhurandhar.js module --add example
+```
+
+This installs the example module which demonstrates a web frontend, API service, and database.
+
+### Step 2: Explore the Module
+
+View the module structure:
+
+```bash
+node tools/cli/dhurandhar.js module --info example
+```
+
+Check the installed files in `.dhurandhar/modules/example/`
+
+### Step 3: Customize
+
+Copy the example module to create your own:
+
+1. Create a new directory: `src/modules/my-design/`
+2. Copy `module.yaml` from the example
+3. Modify the components and relationships
+4. Install your custom module
+
+## Understanding the Configuration
+
+The configuration file is located at `.dhurandhar/config.yaml`:
+
+```yaml
+version: "0.1.0"
+projectName: my-system
+userName: John Doe
+outputFolder: _dhurandhar-output
+modules:
+  - core
+  - example
+settings:
+  created: "2024-01-01T00:00:00.000Z"
+  lastModified: "2024-01-01T00:00:00.000Z"
+variables:
+  projectRoot: /path/to/project
+  configDir: /path/to/project/.dhurandhar
+```
+
+### Key Fields
+
+- **version**: Framework version
+- **projectName**: Your project identifier
+- **userName**: User or team name
+- **outputFolder**: Where outputs are saved
+- **modules**: List of installed modules
+- **variables**: Auto-populated runtime variables
+
+## Next Steps
+
+Now that you have Dhurandhar set up:
+
+1. **Explore Modules**: Learn about available modules
+   ```bash
+   node tools/cli/dhurandhar.js module --list
+   ```
+
+2. **Read Module Documentation**: Check out module-specific guides
+   - [Module Development](module-development.md)
+   - [Core Module](../src/core/README.md)
+   - [Example Module](../src/modules/example/README.md)
+
+3. **Create Your Design**: Start building your system architecture
+   - Define components
+   - Map relationships
+   - Specify build processes
+
+4. **Validate Regularly**: Ensure your design is consistent
+   ```bash
+   node tools/cli/dhurandhar.js validate
+   ```
+
+## Common Tasks
+
+### Adding a Module
+
+```bash
+node tools/cli/dhurandhar.js module --add <module-name>
+```
+
+### Removing a Module
+
+```bash
+node tools/cli/dhurandhar.js module --remove <module-name>
+```
+
+### Updating Configuration
+
+```bash
+node tools/cli/dhurandhar.js config --edit
+```
+
+### Resetting Configuration
+
+```bash
+node tools/cli/dhurandhar.js config --reset
+```
+
+## Troubleshooting
+
+### Command Not Found
+
+If you get "command not found" errors:
+
+```bash
+# Use the full path
+node tools/cli/dhurandhar.js <command>
+
+# Or use npm scripts
+npm run cli -- <command>
+```
+
+### Module Installation Fails
+
+Check that:
+- Module dependencies are met
+- Module code is valid
+- Configuration is correct
+
+Run validation:
+```bash
+node tools/cli/dhurandhar.js validate --strict
+```
+
+### Configuration Issues
+
+Reset to defaults:
+```bash
+node tools/cli/dhurandhar.js config --reset
+```
+
+## Getting Help
+
+- **CLI Help**: Run commands with `--help` flag
+- **Documentation**: See the `docs/` directory
+- **Examples**: Check the `examples/` directory
+- **Issues**: Report bugs on GitHub
+
+## What's Next?
+
+Continue learning:
+
+- [Module Development Guide](module-development.md) - Create custom modules
+- [CLI Reference](cli-reference.md) - Complete command reference
+- [Configuration Guide](configuration.md) - Advanced configuration options
+- [API Documentation](api.md) - Programmatic usage