README.md

1# Micro-Block Core Services
2
3*Foundation services for the micro-block architecture pattern*
4
5## Overview
6
7This directory contains the core infrastructure services that enable the micro-block architecture pattern. These services provide dependency injection, command orchestration, logging, and service management capabilities that form the foundation for AI-collaborative development.
8
9**Important**: Review the `utaba/main/patterns/micro-block` section prior to implementation to understand the architectural patterns and principles these services implement.
10
11## 🏗️ Core Architecture Components
12
13### ServiceRegistry - Configuration Adapter & Central Access Point
14- **[ServiceRegistry.ts](ServiceRegistry.ts)** - Singleton service registry with lazy initialization and dependency injection
15- **Purpose**: Central dependency injection container and primary access point for all services and commands
16
17### CommandRegistry - Dynamic Command Orchestration  
18- **[CommandRegistry.ts](CommandRegistry.ts)** - Central registry for discovering and instantiating commands with dynamic loading
19- **Purpose**: Metadata-driven command discovery and lazy loading system
20
21### BaseService - Service Foundation
22- **[BaseService.ts](BaseService.ts)** - Abstract base class with comprehensive metadata, operation framework, and validation
23- **Purpose**: Common foundation for all micro-block services
24
25### LoggerFactory - Structured Logging
26- **[LoggerFactory.ts](LoggerFactory.ts)** - Complete logging system with ILogger interface and ConsoleLogger implementation
27- **Purpose**: Centralized logging with no external dependencies
28
29## 🔄 Service Relationships
30
31### Access Pattern Hierarchy
32```
33ServiceRegistry (Singleton)
34├── CommandRegistry (Managed by ServiceRegistry)
35│   ├── Command Discovery & Loading
36│   ├── Dependency Injection
37│   └── Metadata-driven Orchestration
38├── Service Factory Management
39│   ├── Configuration Adaptation
40│   ├── Dependency Resolution
41│   └── Service Lifecycle
42└── Logger Provisioning
43    ├── Service-specific Loggers
44    ├── Structured Logging
45    └── Performance Monitoring
46```
47
48### Critical Access Rules
49- **✅ CORRECT**: Always use `ServiceRegistry.getInstance()` as the primary entry point
50- **✅ CORRECT**: Access CommandRegistry via `serviceRegistry.getCommandRegistry()`
51- **❌ INCORRECT**: Never call `CommandRegistry.getInstance()` directly
52- **❌ INCORRECT**: Never instantiate services directly in business logic
53
54## 🚀 Quick Start Guide
55
56### 1. Basic Service Access
57```typescript
58// Primary access pattern
59const serviceRegistry = ServiceRegistry.getInstance();
60const cacheService = serviceRegistry.get<ICacheService>('ICacheService');
61```
62
63### 2. Command Execution
64```typescript
65// Command execution through ServiceRegistry
66const serviceRegistry = ServiceRegistry.getInstance();
67const commandRegistry = serviceRegistry.getCommandRegistry();
68
69const { CreateUserCommand } = await import('@/commands/user/CreateUserCommand');
70const command = await commandRegistry.get(CreateUserCommand, input);
71const result = await command.execute();
72```
73
74### 3. Service Registration (ServiceRegistry initialization)
75```typescript
76// Configuration adapter pattern
77this.register('ICacheService', () => {
78  // Map project config to service config
79  const serviceConfig: CacheServiceConfig = {
80    maxMemoryMB: this.getConfig().cache.maxMemoryMB || 100,
81    defaultTtlSeconds: this.getConfig().cache.defaultTtlSeconds || 3600,
82    evictionPolicy: this.getConfig().cache.evictionPolicy || 'LRU'
83  };
84  
85  // Inject dependencies
86  const logger = this.getLogger('CacheService');
87  const metricsService = this.get<IMetricsService>('IMetricsService');
88  
89  return new MemoryCacheService(serviceConfig, logger, metricsService);
90});
91```
92
93## 📋 Key Patterns & Principles
94
95### Configuration Adapter Pattern
96ServiceRegistry serves as a **configuration adapter** that enables true service portability:
97- **Translates** project-specific configuration to service-specific interfaces
98- **Provides** sensible defaults for optional service properties
99- **Isolates** services from direct project configuration access
100- **Enables** services to work across projects without modification
101
102### Dependency Injection
103- **Constructor Injection**: Services receive all dependencies via constructor
104- **Service Resolution**: ServiceRegistry resolves service dependencies automatically
105- **Command Dependencies**: CommandRegistry injects services into commands based on metadata
106- **Logger Injection**: Each service receives its own logger instance
107
108### Lazy Loading & Caching
109- **Service Instances**: Created on first access and cached for performance
110- **Command Loading**: Commands are dynamically imported when first requested
111- **Memory Efficiency**: Only required services are instantiated
112- **Performance**: Cached instances avoid repeated initialization
113
114## 🔗 Related Resources
115
116### Core Patterns
117- **[Service Registry Patterns](utaba/main/patterns/micro-block/service-registry-patterns.md)** - Comprehensive patterns for ServiceRegistry implementation and usage
118- **[Command Registry Pattern](utaba/main/patterns/micro-block/command-registry-pattern.md)** - Guide to CommandRegistry for dynamic command loading and metadata-driven composition
119- **[Micro-Block Architecture](utaba/main/patterns/micro-block/micro-block-pattern.md)** - Complete design pattern specification
120
121### Implementation Examples
122- **[Next.js Implementation](utaba/main/implementations/micro-block-nextjs/README.md)** - Complete Next.js implementation guide
123- **[Base Command](utaba/main/commands/micro-block/BaseCommand.ts)** - Command architecture with dependency injection support
124
125### Service Implementations
126- **[Cache Services](utaba/main/services/cache/)** - Memory and Redis cache implementations
127- **[Communication Services](utaba/main/services/communication/)** - Email service with template support
128- **[Storage Services](utaba/main/services/storage/)** - Azure Blob Storage implementation
129
130## 🎯 AI-Collaborative Features
131
132These services are specifically designed for AI-collaborative development:
133
134- **Rich Metadata**: Every service includes comprehensive metadata for AI discovery
135- **Contract-First**: All interfaces are defined before implementation
136- **Discoverable**: AI agents can find and compose functionality automatically
137- **Portable**: Services work across projects without modification
138- **Self-Documenting**: Clear interfaces and metadata enable AI understanding
139
140---
141
142*This service library represents the core infrastructure of the micro-block architecture pattern. For complete implementation details, see the [Service Registry Patterns](utaba/main/patterns/micro-block/service-registry-patterns.md) guide.*