musubi-sdd 5.1.0 → 5.6.1

package/src/templates/agents/qwen-code/QWEN.md

@@ -98,16 +98,16 @@ MUSUBI enforces 9 immutable constitutional articles:
 
 MUSUBI provides advanced AI agent assistance modules:
 
-| Module | Purpose | Import |
-|--------|---------|--------|
-| **StuckDetector** | Detect agent stuck states | `src/analyzers/stuck-detector.js` |
-| **MemoryCondenser** | Compress session history | `src/managers/memory-condenser.js` |
-| **AgentMemoryManager** | Extract & persist learnings | `src/managers/agent-memory.js` |
-| **CriticSystem** | Evaluate SDD stage quality | `src/validators/critic-system.js` |
-| **SecurityAnalyzer** | Detect security risks | `src/analyzers/security-analyzer.js` |
-| **IssueResolver** | GitHub Issue analysis | `src/resolvers/issue-resolver.js` |
-| **SkillLoader** | Load keyword-triggered skills | `src/managers/skill-loader.js` |
-| **RepoSkillManager** | Manage project skills | `src/managers/repo-skill-manager.js` |
+| Module                 | Purpose                       | Import                               |
+| ---------------------- | ----------------------------- | ------------------------------------ |
+| **StuckDetector**      | Detect agent stuck states     | `src/analyzers/stuck-detector.js`    |
+| **MemoryCondenser**    | Compress session history      | `src/managers/memory-condenser.js`   |
+| **AgentMemoryManager** | Extract & persist learnings   | `src/managers/agent-memory.js`       |
+| **CriticSystem**       | Evaluate SDD stage quality    | `src/validators/critic-system.js`    |
+| **SecurityAnalyzer**   | Detect security risks         | `src/analyzers/security-analyzer.js` |
+| **IssueResolver**      | GitHub Issue analysis         | `src/resolvers/issue-resolver.js`    |
+| **SkillLoader**        | Load keyword-triggered skills | `src/managers/skill-loader.js`       |
+| **RepoSkillManager**   | Manage project skills         | `src/managers/repo-skill-manager.js` |
 
 ## Quick Start
 
@@ -146,47 +146,79 @@ npx musubi-sdd <command>
 
 ### Core Commands
 
-| Command | Purpose | Example |
-|---------|---------|--------|
-| `musubi-workflow` | Workflow state & metrics | `npx musubi-workflow status` |
-| `musubi-requirements` | EARS requirements | `npx musubi-requirements init <feature>` |
-| `musubi-design` | C4 + ADR design | `npx musubi-design init <feature>` |
-| `musubi-tasks` | Task breakdown | `npx musubi-tasks init <feature>` |
-| `musubi-trace` | Traceability | `npx musubi-trace matrix` |
-| `musubi-validate` | Constitutional validation | `npx musubi-validate all` |
+| Command               | Purpose                   | Example                                  |
+| --------------------- | ------------------------- | ---------------------------------------- |
+| `musubi-workflow`     | Workflow state & metrics  | `npx musubi-workflow status`             |
+| `musubi-requirements` | EARS requirements         | `npx musubi-requirements init <feature>` |
+| `musubi-design`       | C4 + ADR design           | `npx musubi-design init <feature>`       |
+| `musubi-tasks`        | Task breakdown            | `npx musubi-tasks init <feature>`        |
+| `musubi-trace`        | Traceability              | `npx musubi-trace matrix`                |
+| `musubi-validate`     | Constitutional validation | `npx musubi-validate all`                |
 
 ### Advanced Commands (v3.5.0 NEW)
 
-| Command | Purpose | Example |
-|---------|---------|--------|
-| `musubi-orchestrate` | Multi-skill orchestration | `npx musubi-orchestrate auto <task>` |
-| `musubi-browser` | Browser automation & E2E | `npx musubi-browser run "click login"` |
-| `musubi-gui` | Web GUI dashboard | `npx musubi-gui start` |
-| `musubi-remember` | Agent memory management | `npx musubi-remember extract` |
-| `musubi-resolve` | GitHub Issue resolution | `npx musubi-resolve <issue-number>` |
-| `musubi-convert` | Format conversion | `npx musubi-convert to-speckit` |
+| Command              | Purpose                   | Example                                |
+| -------------------- | ------------------------- | -------------------------------------- |
+| `musubi-orchestrate` | Multi-skill orchestration | `npx musubi-orchestrate auto <task>`   |
+| `musubi-browser`     | Browser automation & E2E  | `npx musubi-browser run "click login"` |
+| `musubi-gui`         | Web GUI dashboard         | `npx musubi-gui start`                 |
+| `musubi-remember`    | Agent memory management   | `npx musubi-remember extract`          |
+| `musubi-resolve`     | GitHub Issue resolution   | `npx musubi-resolve <issue-number>`    |
+| `musubi-convert`     | Format conversion         | `npx musubi-convert to-speckit`        |
 
 ### Replanning Commands (v3.6.0 NEW)
 
-| Command | Purpose | Example |
-|---------|---------|--------|
-| `musubi-orchestrate replan` | Execute dynamic replanning | `npx musubi-orchestrate replan <context-id>` |
-| `musubi-orchestrate goal register` | Register a new goal | `npx musubi-orchestrate goal register --name "Deploy API"` |
-| `musubi-orchestrate goal update` | Update goal progress | `npx musubi-orchestrate goal update <goal-id> --progress 50` |
-| `musubi-orchestrate goal status` | View goal status | `npx musubi-orchestrate goal status [goal-id]` |
-| `musubi-orchestrate optimize run` | Run path optimization | `npx musubi-orchestrate optimize run <path-id>` |
-| `musubi-orchestrate optimize suggest` | Get optimization suggestions | `npx musubi-orchestrate optimize suggest <path-id>` |
-| `musubi-orchestrate path analyze` | Analyze execution path | `npx musubi-orchestrate path analyze <path-id>` |
-| `musubi-orchestrate path optimize` | Optimize execution path | `npx musubi-orchestrate path optimize <path-id>` |
+| Command                               | Purpose                      | Example                                                      |
+| ------------------------------------- | ---------------------------- | ------------------------------------------------------------ |
+| `musubi-orchestrate replan`           | Execute dynamic replanning   | `npx musubi-orchestrate replan <context-id>`                 |
+| `musubi-orchestrate goal register`    | Register a new goal          | `npx musubi-orchestrate goal register --name "Deploy API"`   |
+| `musubi-orchestrate goal update`      | Update goal progress         | `npx musubi-orchestrate goal update <goal-id> --progress 50` |
+| `musubi-orchestrate goal status`      | View goal status             | `npx musubi-orchestrate goal status [goal-id]`               |
+| `musubi-orchestrate optimize run`     | Run path optimization        | `npx musubi-orchestrate optimize run <path-id>`              |
+| `musubi-orchestrate optimize suggest` | Get optimization suggestions | `npx musubi-orchestrate optimize suggest <path-id>`          |
+| `musubi-orchestrate path analyze`     | Analyze execution path       | `npx musubi-orchestrate path analyze <path-id>`              |
+| `musubi-orchestrate path optimize`    | Optimize execution path      | `npx musubi-orchestrate path optimize <path-id>`             |
 
 ### Guardrails Commands (v3.9.0 NEW)
 
-| Command | Purpose | Example |
-|---------|---------|--------|
-| `musubi-validate guardrails` | Input/Output guardrail validation | `npx musubi-validate guardrails --type input` |
-| `musubi-validate guardrails --type output` | Output content validation | `echo "content" \| npx musubi-validate guardrails --type output` |
-| `musubi-validate guardrails --type safety` | Safety check with constitutional | `npx musubi-validate guardrails --type safety --constitutional` |
-| `musubi-validate guardrails-chain` | Chain multiple guardrails | `npx musubi-validate guardrails-chain --parallel` |
+| Command                                    | Purpose                           | Example                                                          |
+| ------------------------------------------ | --------------------------------- | ---------------------------------------------------------------- |
+| `musubi-validate guardrails`               | Input/Output guardrail validation | `npx musubi-validate guardrails --type input`                    |
+| `musubi-validate guardrails --type output` | Output content validation         | `echo "content" \| npx musubi-validate guardrails --type output` |
+| `musubi-validate guardrails --type safety` | Safety check with constitutional  | `npx musubi-validate guardrails --type safety --constitutional`  |
+| `musubi-validate guardrails-chain`         | Chain multiple guardrails         | `npx musubi-validate guardrails-chain --parallel`                |
+
+## Enterprise Scale Modules (v5.5.0 NEW)
+
+MUSUBI v5.5.0 adds advanced modules for analyzing enterprise-scale projects (10,000+ files):
+
+| Module                     | Purpose                              | Import                                       |
+| -------------------------- | ------------------------------------ | -------------------------------------------- |
+| **LargeProjectAnalyzer**   | Streaming analysis for 100K+ files   | `src/analyzers/large-project-analyzer.js`    |
+| **ComplexityAnalyzer**     | Cyclomatic & cognitive complexity    | `src/analyzers/complexity-analyzer.js`       |
+| **RustMigrationGenerator** | C/C++ to Rust migration analysis     | `src/generators/rust-migration-generator.js` |
+| **CodeGraphMCP**           | MCP-based code intelligence server   | `src/integrations/code-graph-mcp.js`         |
+| **HierarchicalReporter**   | Drilldown reports for large projects | `src/reporters/hierarchical-reporter.js`     |
+
+### Usage Examples
+
+```javascript
+// Analyze large projects (100,000+ files)
+const { LargeProjectAnalyzer } = require('musubi-sdd');
+const analyzer = new LargeProjectAnalyzer('/path/to/project');
+const result = await analyzer.analyze();
+console.log(result.stats.totalFiles);
+
+// Calculate code complexity
+const { ComplexityAnalyzer } = require('musubi-sdd');
+const complexity = new ComplexityAnalyzer();
+const score = complexity.calculateCyclomaticComplexity(code, 'javascript');
+
+// Analyze C/C++ for Rust migration
+const { RustMigrationGenerator } = require('musubi-sdd');
+const generator = new RustMigrationGenerator('/path/to/cpp-project');
+const analysis = await generator.analyze();
+```
 
 ## Learn More
 

package/src/templates/agents/windsurf/AGENTS.md

@@ -104,16 +104,16 @@ MUSUBI enforces 9 immutable constitutional articles:
 
 MUSUBI provides advanced AI agent assistance modules:
 
-| Module | Purpose | Import |
-|--------|---------|--------|
-| **StuckDetector** | Detect agent stuck states | `src/analyzers/stuck-detector.js` |
-| **MemoryCondenser** | Compress session history | `src/managers/memory-condenser.js` |
-| **AgentMemoryManager** | Extract & persist learnings | `src/managers/agent-memory.js` |
-| **CriticSystem** | Evaluate SDD stage quality | `src/validators/critic-system.js` |
-| **SecurityAnalyzer** | Detect security risks | `src/analyzers/security-analyzer.js` |
-| **IssueResolver** | GitHub Issue analysis | `src/resolvers/issue-resolver.js` |
-| **SkillLoader** | Load keyword-triggered skills | `src/managers/skill-loader.js` |
-| **RepoSkillManager** | Manage project skills | `src/managers/repo-skill-manager.js` |
+| Module                 | Purpose                       | Import                               |
+| ---------------------- | ----------------------------- | ------------------------------------ |
+| **StuckDetector**      | Detect agent stuck states     | `src/analyzers/stuck-detector.js`    |
+| **MemoryCondenser**    | Compress session history      | `src/managers/memory-condenser.js`   |
+| **AgentMemoryManager** | Extract & persist learnings   | `src/managers/agent-memory.js`       |
+| **CriticSystem**       | Evaluate SDD stage quality    | `src/validators/critic-system.js`    |
+| **SecurityAnalyzer**   | Detect security risks         | `src/analyzers/security-analyzer.js` |
+| **IssueResolver**      | GitHub Issue analysis         | `src/resolvers/issue-resolver.js`    |
+| **SkillLoader**        | Load keyword-triggered skills | `src/managers/skill-loader.js`       |
+| **RepoSkillManager**   | Manage project skills         | `src/managers/repo-skill-manager.js` |
 
 ## Quick Start
 
@@ -157,47 +157,79 @@ npx musubi-sdd <command>
 
 ### Core Commands
 
-| Command | Purpose | Example |
-|---------|---------|--------|
-| `musubi-workflow` | Workflow state & metrics | `npx musubi-workflow status` |
-| `musubi-requirements` | EARS requirements | `npx musubi-requirements init <feature>` |
-| `musubi-design` | C4 + ADR design | `npx musubi-design init <feature>` |
-| `musubi-tasks` | Task breakdown | `npx musubi-tasks init <feature>` |
-| `musubi-trace` | Traceability | `npx musubi-trace matrix` |
-| `musubi-validate` | Constitutional validation | `npx musubi-validate all` |
+| Command               | Purpose                   | Example                                  |
+| --------------------- | ------------------------- | ---------------------------------------- |
+| `musubi-workflow`     | Workflow state & metrics  | `npx musubi-workflow status`             |
+| `musubi-requirements` | EARS requirements         | `npx musubi-requirements init <feature>` |
+| `musubi-design`       | C4 + ADR design           | `npx musubi-design init <feature>`       |
+| `musubi-tasks`        | Task breakdown            | `npx musubi-tasks init <feature>`        |
+| `musubi-trace`        | Traceability              | `npx musubi-trace matrix`                |
+| `musubi-validate`     | Constitutional validation | `npx musubi-validate all`                |
 
 ### Advanced Commands (v3.5.0 NEW)
 
-| Command | Purpose | Example |
-|---------|---------|--------|
-| `musubi-orchestrate` | Multi-skill orchestration | `npx musubi-orchestrate auto <task>` |
-| `musubi-browser` | Browser automation & E2E | `npx musubi-browser run "click login"` |
-| `musubi-gui` | Web GUI dashboard | `npx musubi-gui start` |
-| `musubi-remember` | Agent memory management | `npx musubi-remember extract` |
-| `musubi-resolve` | GitHub Issue resolution | `npx musubi-resolve <issue-number>` |
-| `musubi-convert` | Format conversion | `npx musubi-convert to-speckit` |
+| Command              | Purpose                   | Example                                |
+| -------------------- | ------------------------- | -------------------------------------- |
+| `musubi-orchestrate` | Multi-skill orchestration | `npx musubi-orchestrate auto <task>`   |
+| `musubi-browser`     | Browser automation & E2E  | `npx musubi-browser run "click login"` |
+| `musubi-gui`         | Web GUI dashboard         | `npx musubi-gui start`                 |
+| `musubi-remember`    | Agent memory management   | `npx musubi-remember extract`          |
+| `musubi-resolve`     | GitHub Issue resolution   | `npx musubi-resolve <issue-number>`    |
+| `musubi-convert`     | Format conversion         | `npx musubi-convert to-speckit`        |
 
 ### Replanning Commands (v3.6.0 NEW)
 
-| Command | Purpose | Example |
-|---------|---------|--------|
-| `musubi-orchestrate replan` | Execute dynamic replanning | `npx musubi-orchestrate replan <context-id>` |
-| `musubi-orchestrate goal register` | Register a new goal | `npx musubi-orchestrate goal register --name "Deploy API"` |
-| `musubi-orchestrate goal update` | Update goal progress | `npx musubi-orchestrate goal update <goal-id> --progress 50` |
-| `musubi-orchestrate goal status` | View goal status | `npx musubi-orchestrate goal status [goal-id]` |
-| `musubi-orchestrate optimize run` | Run path optimization | `npx musubi-orchestrate optimize run <path-id>` |
-| `musubi-orchestrate optimize suggest` | Get optimization suggestions | `npx musubi-orchestrate optimize suggest <path-id>` |
-| `musubi-orchestrate path analyze` | Analyze execution path | `npx musubi-orchestrate path analyze <path-id>` |
-| `musubi-orchestrate path optimize` | Optimize execution path | `npx musubi-orchestrate path optimize <path-id>` |
+| Command                               | Purpose                      | Example                                                      |
+| ------------------------------------- | ---------------------------- | ------------------------------------------------------------ |
+| `musubi-orchestrate replan`           | Execute dynamic replanning   | `npx musubi-orchestrate replan <context-id>`                 |
+| `musubi-orchestrate goal register`    | Register a new goal          | `npx musubi-orchestrate goal register --name "Deploy API"`   |
+| `musubi-orchestrate goal update`      | Update goal progress         | `npx musubi-orchestrate goal update <goal-id> --progress 50` |
+| `musubi-orchestrate goal status`      | View goal status             | `npx musubi-orchestrate goal status [goal-id]`               |
+| `musubi-orchestrate optimize run`     | Run path optimization        | `npx musubi-orchestrate optimize run <path-id>`              |
+| `musubi-orchestrate optimize suggest` | Get optimization suggestions | `npx musubi-orchestrate optimize suggest <path-id>`          |
+| `musubi-orchestrate path analyze`     | Analyze execution path       | `npx musubi-orchestrate path analyze <path-id>`              |
+| `musubi-orchestrate path optimize`    | Optimize execution path      | `npx musubi-orchestrate path optimize <path-id>`             |
 
 ### Guardrails Commands (v3.9.0 NEW)
 
-| Command | Purpose | Example |
-|---------|---------|--------|
-| `musubi-validate guardrails` | Input/Output guardrail validation | `npx musubi-validate guardrails --type input` |
-| `musubi-validate guardrails --type output` | Output content validation | `echo "content" \| npx musubi-validate guardrails --type output` |
-| `musubi-validate guardrails --type safety` | Safety check with constitutional | `npx musubi-validate guardrails --type safety --constitutional` |
-| `musubi-validate guardrails-chain` | Chain multiple guardrails | `npx musubi-validate guardrails-chain --parallel` |
+| Command                                    | Purpose                           | Example                                                          |
+| ------------------------------------------ | --------------------------------- | ---------------------------------------------------------------- |
+| `musubi-validate guardrails`               | Input/Output guardrail validation | `npx musubi-validate guardrails --type input`                    |
+| `musubi-validate guardrails --type output` | Output content validation         | `echo "content" \| npx musubi-validate guardrails --type output` |
+| `musubi-validate guardrails --type safety` | Safety check with constitutional  | `npx musubi-validate guardrails --type safety --constitutional`  |
+| `musubi-validate guardrails-chain`         | Chain multiple guardrails         | `npx musubi-validate guardrails-chain --parallel`                |
+
+## Enterprise Scale Modules (v5.5.0 NEW)
+
+MUSUBI v5.5.0 adds advanced modules for analyzing enterprise-scale projects (10,000+ files):
+
+| Module                     | Purpose                              | Import                                       |
+| -------------------------- | ------------------------------------ | -------------------------------------------- |
+| **LargeProjectAnalyzer**   | Streaming analysis for 100K+ files   | `src/analyzers/large-project-analyzer.js`    |
+| **ComplexityAnalyzer**     | Cyclomatic & cognitive complexity    | `src/analyzers/complexity-analyzer.js`       |
+| **RustMigrationGenerator** | C/C++ to Rust migration analysis     | `src/generators/rust-migration-generator.js` |
+| **CodeGraphMCP**           | MCP-based code intelligence server   | `src/integrations/code-graph-mcp.js`         |
+| **HierarchicalReporter**   | Drilldown reports for large projects | `src/reporters/hierarchical-reporter.js`     |
+
+### Usage Examples
+
+```javascript
+// Analyze large projects (100,000+ files)
+const { LargeProjectAnalyzer } = require('musubi-sdd');
+const analyzer = new LargeProjectAnalyzer('/path/to/project');
+const result = await analyzer.analyze();
+console.log(result.stats.totalFiles);
+
+// Calculate code complexity
+const { ComplexityAnalyzer } = require('musubi-sdd');
+const complexity = new ComplexityAnalyzer();
+const score = complexity.calculateCyclomaticComplexity(code, 'javascript');
+
+// Analyze C/C++ for Rust migration
+const { RustMigrationGenerator } = require('musubi-sdd');
+const generator = new RustMigrationGenerator('/path/to/cpp-project');
+const analysis = await generator.analyze();
+```
 
 ## Learn More
 

package/src/templates/architectures/README.md

@@ -0,0 +1,41 @@
+# Reference Architecture Templates
+
+This directory contains reference architecture templates for common architectural patterns.
+
+## Available Templates
+
+| Template                                    | Pattern                    | Best For                                 |
+| ------------------------------------------- | -------------------------- | ---------------------------------------- |
+| [clean-architecture](./clean-architecture/) | Clean Architecture         | Enterprise applications, complex domains |
+| [hexagonal](./hexagonal/)                   | Hexagonal/Ports & Adapters | Highly testable systems                  |
+| [event-driven](./event-driven/)             | Event-Driven Architecture  | Microservices, distributed systems       |
+| [layered](./layered/)                       | Traditional Layered        | Simple CRUD applications                 |
+| [modular-monolith](./modular-monolith/)     | Modular Monolith           | Scalable monoliths                       |
+
+## Usage
+
+Use `musubi init --template <template-name>` to initialize a project with a reference architecture:
+
+```bash
+# Clean Architecture template
+musubi init --template clean-architecture
+
+# Hexagonal Architecture template
+musubi init --template hexagonal
+
+# Event-Driven Architecture template
+musubi init --template event-driven
+```
+
+## Template Structure
+
+Each template provides:
+
+- Directory structure
+- Layer definitions
+- Sample code organization
+- Recommended patterns
+
+---
+
+_Generated by MUSUBI SDD_

package/src/templates/architectures/clean-architecture/README.md

@@ -0,0 +1,113 @@
+# Clean Architecture Template
+
+## Overview
+
+Clean Architecture separates concerns into concentric circles, with dependencies pointing inward.
+
+## Directory Structure
+
+```
+src/
+├── domain/                 # Enterprise Business Rules (innermost)
+│   ├── entities/           # Business entities
+│   ├── value-objects/      # Immutable value types
+│   ├── errors/             # Domain-specific errors
+│   └── services/           # Domain services (no I/O)
+│
+├── application/            # Application Business Rules
+│   ├── use-cases/          # Application-specific use cases
+│   ├── ports/              # Interfaces for external services
+│   │   ├── input/          # Input ports (use case interfaces)
+│   │   └── output/         # Output ports (repository interfaces)
+│   ├── dtos/               # Data Transfer Objects
+│   └── services/           # Application services
+│
+├── infrastructure/         # Frameworks & Drivers (outermost)
+│   ├── persistence/        # Database implementations
+│   │   ├── repositories/   # Repository implementations
+│   │   └── mappers/        # Entity <-> DB mappers
+│   ├── external/           # External API clients
+│   ├── messaging/          # Message queue adapters
+│   └── config/             # Configuration
+│
+└── interface/              # Interface Adapters
+    ├── controllers/        # HTTP/gRPC controllers
+    ├── presenters/         # Response formatters
+    ├── cli/                # CLI handlers
+    └── gateways/           # External service gateways
+```
+
+## Dependency Rules
+
+1. **Domain** has NO external dependencies
+2. **Application** depends only on Domain
+3. **Infrastructure** implements Application ports
+4. **Interface** orchestrates Application use cases
+
+## Key Principles
+
+- **Dependency Inversion**: High-level modules don't depend on low-level modules
+- **Separation of Concerns**: Each layer has a single responsibility
+- **Testability**: Business logic is testable without frameworks
+- **Independence**: Framework/database changes don't affect business logic
+
+## Example Structure by Language
+
+### TypeScript
+
+```
+src/
+├── domain/
+│   └── user/
+│       ├── User.ts           # Entity
+│       ├── UserId.ts         # Value Object
+│       └── UserRepository.ts # Port (interface)
+├── application/
+│   └── user/
+│       ├── CreateUser.ts     # Use Case
+│       └── GetUser.ts        # Use Case
+├── infrastructure/
+│   └── persistence/
+│       └── PrismaUserRepository.ts
+└── interface/
+    └── http/
+        └── UserController.ts
+```
+
+### Rust
+
+```
+src/
+├── domain/
+│   └── user/
+│       ├── mod.rs
+│       ├── entity.rs         # User struct
+│       ├── value_objects.rs  # UserId, Email
+│       └── repository.rs     # Trait definition
+├── application/
+│   └── user/
+│       ├── mod.rs
+│       ├── create_user.rs    # Use case
+│       └── get_user.rs       # Use case
+├── infrastructure/
+│   └── persistence/
+│       ├── mod.rs
+│       └── postgres_user_repo.rs
+└── interface/
+    └── api/
+        ├── mod.rs
+        └── user_handler.rs
+```
+
+## Testing Strategy
+
+| Layer          | Test Type          | Dependencies     |
+| -------------- | ------------------ | ---------------- |
+| Domain         | Unit               | None             |
+| Application    | Unit + Integration | Mocked ports     |
+| Infrastructure | Integration        | Real DB/Services |
+| Interface      | E2E                | Full stack       |
+
+---
+
+_Clean Architecture Template - MUSUBI SDD_

package/src/templates/architectures/event-driven/README.md

@@ -0,0 +1,162 @@
+# Event-Driven Architecture Template
+
+## Overview
+
+Event-Driven Architecture (EDA) enables loose coupling through asynchronous event communication.
+
+## Directory Structure
+
+```
+src/
+├── domain/
+│   ├── events/             # Domain events
+│   │   ├── UserCreated.ts
+│   │   ├── OrderPlaced.ts
+│   │   └── PaymentReceived.ts
+│   ├── aggregates/         # Aggregate roots
+│   └── commands/           # Command definitions
+│
+├── application/
+│   ├── command-handlers/   # Handle commands, emit events
+│   ├── event-handlers/     # React to events
+│   ├── sagas/              # Long-running processes
+│   └── projections/        # Read model projections
+│
+├── infrastructure/
+│   ├── messaging/          # Message broker adapters
+│   │   ├── kafka/
+│   │   ├── rabbitmq/
+│   │   └── sqs/
+│   ├── event-store/        # Event sourcing storage
+│   └── projections/        # Projection storage
+│
+└── interface/
+    ├── api/                # REST/GraphQL API
+    ├── consumers/          # Event consumers
+    └── publishers/         # Event publishers
+```
+
+## Event Types
+
+### Domain Events
+
+```typescript
+// domain/events/UserCreated.ts
+interface UserCreated {
+  eventId: string;
+  eventType: 'UserCreated';
+  aggregateId: string;
+  timestamp: Date;
+  data: {
+    userId: string;
+    email: string;
+    name: string;
+  };
+  metadata: {
+    correlationId: string;
+    causationId: string;
+  };
+}
+```
+
+### Integration Events
+
+```typescript
+// infrastructure/messaging/events/UserRegistrationCompleted.ts
+interface UserRegistrationCompleted {
+  eventId: string;
+  eventType: 'UserRegistrationCompleted';
+  source: 'user-service';
+  timestamp: Date;
+  data: {
+    userId: string;
+    email: string;
+  };
+}
+```
+
+## Patterns
+
+### Command Handler
+
+```typescript
+class CreateUserHandler {
+  async handle(command: CreateUserCommand): Promise<void> {
+    const user = User.create(command);
+    await this.repository.save(user);
+    await this.eventPublisher.publish(new UserCreated(user));
+  }
+}
+```
+
+### Event Handler
+
+```typescript
+class SendWelcomeEmailHandler {
+  async handle(event: UserCreated): Promise<void> {
+    await this.emailService.sendWelcome(event.data.email);
+  }
+}
+```
+
+### Saga (Process Manager)
+
+```typescript
+class OrderFulfillmentSaga {
+  async handle(event: OrderPlaced): Promise<void> {
+    // Step 1: Reserve inventory
+    await this.dispatch(new ReserveInventory(event.orderId));
+
+    // Step 2: Process payment
+    await this.dispatch(new ProcessPayment(event.orderId));
+
+    // Step 3: Ship order (triggered by PaymentReceived)
+  }
+
+  async onPaymentReceived(event: PaymentReceived): Promise<void> {
+    await this.dispatch(new ShipOrder(event.orderId));
+  }
+}
+```
+
+## Event Sourcing (Optional)
+
+```
+events/
+├── event-store/
+│   └── PostgresEventStore.ts
+├── snapshots/
+│   └── UserSnapshot.ts
+└── projections/
+    ├── UserProjection.ts
+    └── OrderProjection.ts
+```
+
+## Message Broker Integration
+
+| Broker        | Use Case                        | Configuration            |
+| ------------- | ------------------------------- | ------------------------ |
+| Kafka         | High-throughput, ordered events | Topics, partitions       |
+| RabbitMQ      | Complex routing, reliability    | Exchanges, queues        |
+| AWS SQS/SNS   | Serverless, AWS integration     | Queues, topics           |
+| Redis Streams | Low-latency, in-memory          | Streams, consumer groups |
+
+## Key Principles
+
+1. **Eventual Consistency**: Accept that data will be consistent eventually
+2. **Idempotency**: Handlers must be idempotent (safe to retry)
+3. **Event Ordering**: Consider ordering requirements per aggregate
+4. **Dead Letter Queues**: Handle failed events gracefully
+
+## Testing Strategy
+
+| Component | Test Type   | Approach                  |
+| --------- | ----------- | ------------------------- |
+| Events    | Schema      | JSON Schema validation    |
+| Handlers  | Unit        | Mock event publisher      |
+| Sagas     | Integration | In-memory event store     |
+| E2E       | Contract    | Consumer-driven contracts |
+
+---
+
+_Event-Driven Architecture Template - MUSUBI SDD_