README.md

1# Micro-Block Patterns
2
3*Comprehensive pattern library for AI-collaborative development*
4
5## Overview
6
7This directory contains the complete pattern library for the Micro-Block Design Pattern - a command-based architecture designed for AI-collaborative development. The patterns enable building systems from small, discoverable, contract-driven components that AI agents can understand, select, and compose automatically.
8
9## 📚 Documentation Levels
10
11### 🚀 Quick Start
12- **[micro-block-quick-reference.md](micro-block-quick-reference.md)** (5KB)
13  - Ultra-concise reference card
14  - Copy-paste templates
15  - Critical rules and common mistakes
16  - Perfect for: Frequent consultation, minimal AI context
17
18### 📖 Comprehensive Guide  
19- **[micro-block-pattern-summary.md](micro-block-pattern-summary.md)** (13KB)
20  - Detailed patterns with extensive examples
21  - Complete implementation guidance
22  - Testing and configuration patterns
23  - Perfect for: Learning the architecture, detailed reference
24
25### 🏗️ Complete Specification
26- **[micro-block-pattern.md](micro-block-pattern.md)** (30KB) 
27  - Full design pattern specification
28  - Language-agnostic concepts
29  - AI-driven selection patterns
30  - Perfect for: Architecture decisions, complete understanding
31
32## 🔧 Implementation Patterns
33
34### Core Architecture Patterns
35- **[command-registry-pattern.md](command-registry-pattern.md)**
36  - Command discovery and lazy loading
37  - Metadata-driven composition
38  - Dependency injection patterns
39
40- **[service-registry-patterns.md](service-registry-patterns.md)**
41  - Service management and configuration mapping
42  - Portable service design
43  - Primary access point patterns
44
45### Development Patterns
46- **[contract-first-development.md](contract-first-development.md)**
47  - Input/Output/Error contract design
48  - Interface-driven development
49  - Contract validation patterns
50
51- **[validation-patterns.md](validation-patterns.md)**
52  - Error-throwing validation
53  - Detailed error feedback
54  - Input validation strategies
55
56## 🎯 Pattern Hierarchy
57
58```
59Micro-Block Architecture
60├── Commands (Business Logic)
61│   ├── Self-contained with contracts
62│   ├── Metadata-driven discovery
63│   └── Dependency injection
64├── Services (Infrastructure)
65│   ├── Portable implementations  
66│   ├── Interface-based contracts
67│   └── Configuration mapping
68└── Registries (Discovery & Composition)
69    ├── ServiceRegistry (Primary access)
70    ├── CommandRegistry (Lazy loading)
71    └── Configuration adaptation
72```
73
74## 🚨 Critical Principles
75
76### Commands
77- **Contract-First**: Explicit Input/Output/Error interfaces
78- **Self-Describing**: Rich metadata for AI discovery
79- **Dependency Injection**: Services provided via constructor
80- **Category Alignment**: Folder structure matches metadata
81
82### Services  
83- **Portability**: Own configuration interfaces, no project coupling
84- **Rich Metadata**: Features, limitations, recommendations
85- **Interface Contracts**: Abstract capabilities, multiple implementations
86- **Registry Management**: Created and cached by ServiceRegistry
87
88### Registries
89- **Single Access Point**: ServiceRegistry.getInstance() only
90- **Configuration Mapping**: Project config → service config interfaces  
91- **Lazy Loading**: Commands loaded on-demand
92- **Dependency Resolution**: Automatic injection based on metadata
93
94## 🏃‍♂️ Quick Start Guide
95
96### 1. Creating a Command
97```typescript
98// Use micro-block-quick-reference.md template
99export class MyCommand extends OutputCommand<Input, Output, Error> {
100  static readonly metadata = { /* declare dependencies */ };
101  constructor(input, logger, services, commands) { /* inject deps */ }
102  validate() { /* throw detailed errors */ }
103  async execute() { /* business logic */ }
104}
105```
106
107### 2. Creating a Service
108```typescript
109// Use portable service pattern
110export class MyService extends BaseService implements IMyService {
111  constructor(config: MyServiceConfig, logger: ILogger) { /* own config */ }
112  getMetadata() { /* rich metadata for AI selection */ }
113}
114```
115
116### 3. Using Commands
117```typescript
118// Always via ServiceRegistry
119const serviceRegistry = ServiceRegistry.getInstance();
120const commandRegistry = serviceRegistry.getCommandRegistry();
121const command = await commandRegistry.get(MyCommand, input);
122const result = await command.execute();
123```
124
125## 📈 Benefits for AI Development
126
127- **Granular Components**: Single-responsibility commands
128- **Explicit Contracts**: Clear input/output types
129- **Rich Metadata**: AI can understand capabilities and dependencies
130- **Automatic Discovery**: Registry enables component finding
131- **Composition Patterns**: Build complex workflows from simple parts
132- **Error Context**: Detailed validation feedback
133- **Testability**: Clean dependency injection
134
135## 🗂️ Related Resources
136
137### Implementation Guides
138- `utaba/implementations/micro-block-nextjs/` - Next.js specific implementation
139- `utaba/guidance/development/development-guidelines.md` - Development standards
140- `utaba/guidance/development/database-naming-standards.md` - Database conventions
141
142### Core Components
143- `utaba/commands/micro-block/BaseCommand.ts` - Base command implementation
144- `utaba/services/micro-block/CommandRegistry.ts` - Command discovery
145- `utaba/services/micro-block/ServiceRegistry.ts` - Service management
146
147### Examples
148- `utaba/repositories/` - Repository pattern implementations
149- `utaba/services/` - Service implementations
150
151## 🔄 Pattern Evolution
152
153This pattern library represents the current state of the micro-block architecture. As the pattern evolves:
154
155- **Quick Reference** - Updated for immediate developer needs
156- **Summary** - Enhanced with new examples and clarifications  
157- **Full Pattern** - Extended with new concepts and capabilities
158- **Implementation Patterns** - Refined based on real-world usage
159
160## 💡 Usage Recommendations
161
162**For AI Models:**
163- Start with **Quick Reference** for minimal context
164- Use **Summary** for comprehensive understanding
165- Reference **Implementation Patterns** for specific scenarios
166
167**For Developers:**
168- Begin with **Quick Reference** for immediate productivity
169- Study **Summary** for complete pattern understanding
170- Consult **Full Pattern** for architectural decisions
171
172**For Architecture:**
173- Use **Full Pattern** for system design
174- Apply **Implementation Patterns** for specific technology stacks
175- Follow **Development Guidelines** for coding standards