@plyaz/core 1.0.0 → 1.0.1

package/README.md

@@ -36,316 +36,47 @@ import { createLogger } from '@plyaz/logger';
 │   │   ├── asset/             # Digital asset models and economics
 │   │   ├── transaction/       # Transaction domain and validation
 │   │   └── community/         # Community governance and interaction
+│   │   └── featureFlags/      # Domain logic feature flag system
 │   ├── engine/                # Core computational engines
 │   │   ├── calculation/       # Mathematical computation algorithms
 │   │   ├── incentive/         # Reward and incentive systems
 │   │   ├── validation/        # Business rule validation engines
 │   │   └── insights/          # Data analysis and pattern recognition
-│   ├── feature-flags/         # Complete feature flag system
+│   │   └── featureFlags/      # Egnine feature flag system
 │   ├── frontend/              # Frontend-specific implementations
+│   │   └── featureFlags/      # Frontend hooks, providers of feature flag system
 │   ├── backend/               # Backend-specific implementations
+│   │   └── featureFlags/      # Backend service, module, controller, repository of feature flag system. Generally in NestJs, but should be compatible without NestJs.
 │   ├── sdk/                   # B2B SDK foundation
 │   └── contracts/             # External service contracts
 ```
 
-## 🚀 Feature Flag System
+## 🚀 Currently Available Features
 
-The feature flag system is currently the most mature component of `@plyaz/core`:
+### Feature Flag System
+- **Providers**: Memory (implemented), Redis/API/Database/File (stubs)
+- **Frontend**: React hooks and context providers
+- **Backend**: NestJS module with service, controller, and repository
+- **Engine**: Rule-based evaluation with targeting and rollouts
+- **Testing**: Override capabilities for test scenarios
 
-### Backend Integration (NestJS)
+### Cache System
+- **Strategies**: Memory with LRU eviction (implemented), Redis (stub)
+- **Features**: TTL management, statistics, automatic cleanup
+- **Integration**: Used internally by feature flag system
 
-```typescript
-// app.module.ts
-import { FeatureFlagModule } from '@plyaz/core/backend';
-
-@Module({
-  imports: [
-    FeatureFlagModule.forRoot({
-      provider: 'redis',
-      isCacheEnabled: true,
-      cacheTtl: 600,
-      redisConfig: { url: 'redis://localhost:6379' }
-    })
-  ],
-})
-export class AppModule {}
-
-// my.service.ts
-import { FeatureFlagService } from '@plyaz/core/backend';
-
-@Injectable()
-export class MyService {
-  constructor(private featureFlagService: FeatureFlagService) {}
-
-  async processPayment(userId: string) {
-    const isEnabled = await this.featureFlagService.isEnabled('NEW_PAYMENT_FLOW', {
-      userId,
-      environment: 'production'
-    });
-    
-    if (isEnabled) {
-      // New payment implementation
-    } else {
-      // Legacy payment implementation
-    }
-  }
-}
-```
-
-### Backend Integration (Express/Node.js)
-
-```typescript
-// server.js
-import { MemoryFeatureFlagProvider } from '@plyaz/core/domain';
-import { FEATURES } from '@plyaz/config';
-
-// Initialize provider
-const featureFlagProvider = new MemoryFeatureFlagProvider({
-  provider: 'memory',
-  isCacheEnabled: true,
-  cacheTtl: 300
-}, FEATURES);
-
-await featureFlagProvider.initialize();
-
-// Use in routes
-app.get('/api/features/:key', async (req, res) => {
-  const evaluation = await featureFlagProvider.getFlag(req.params.key, {
-    userId: req.user?.id,
-    environment: process.env.NODE_ENV
-  });
-  
-  res.json(evaluation);
-});
-```
-
-### Frontend Integration (React)
-
-```typescript
-// App.tsx
-import { FeatureFlagAppProvider } from '@plyaz/core/frontend';
-import { FEATURES } from '@plyaz/config';
-
-function App() {
-  return (
-    <FeatureFlagAppProvider
-      config={{
-        provider: 'api',
-        apiEndpoint: 'https://api.example.com/feature-flags',
-        isCacheEnabled: true,
-        cacheTtl: 300
-      }}
-      features={FEATURES}
-    >
-      <MyApplication />
-    </FeatureFlagAppProvider>
-  );
-}
-
-// Component.tsx
-import { useFeatureFlag, useFeatureFlagEnabled } from '@plyaz/core/frontend';
-
-function PaymentComponent() {
-  // Full feature flag data with loading state
-  const { value, isLoading, error } = useFeatureFlag('NEW_PAYMENT_FLOW');
-  
-  // Simple boolean check
-  const isGoogleAuthEnabled = useFeatureFlagEnabled('AUTH_GOOGLE');
-  
-  if (isLoading) return <Spinner />;
-  
-  return (
-    <div>
-      {value && <NewPaymentFlow />}
-      {isGoogleAuthEnabled && <GoogleSignInButton />}
-    </div>
-  );
-}
-```
-
-### Frontend Integration (Vanilla JavaScript)
-
-```typescript
-import { MemoryFeatureFlagProvider } from '@plyaz/core/domain';
-import { FEATURES } from '@plyaz/config';
-
-// Initialize provider
-const provider = new MemoryFeatureFlagProvider({
-  provider: 'memory',
-  isCacheEnabled: true
-}, FEATURES);
-
-await provider.initialize();
-
-// Check feature flags
-async function renderPaymentButton() {
-  const isEnabled = await provider.isEnabled('NEW_PAYMENT_FLOW', {
-    userId: getCurrentUserId(),
-    environment: 'production'
-  });
-  
-  if (isEnabled) {
-    document.getElementById('payment-btn').innerHTML = 'New Payment';
-  } else {
-    document.getElementById('payment-btn').innerHTML = 'Legacy Payment';
-  }
-}
-
-// Subscribe to changes
-provider.subscribe(() => {
-  renderPaymentButton();
-});
-```
-
-### Testing Support
-
-```typescript
-import { MemoryFeatureFlagProvider } from '@plyaz/core/domain';
-import { FEATURES } from '@plyaz/config';
-
-// Initialize for testing with overrides
-const testProvider = new MemoryFeatureFlagProvider({
-  provider: 'memory',
-  isLoggingEnabled: false
-}, FEATURES);
-
-await testProvider.initialize();
-
-// Override specific flags for testing
-testProvider.setOverride('NEW_PAYMENT_FLOW', true);
-testProvider.setOverride('BETA_FEATURE', false);
-
-// Use in tests
-describe('Payment Flow', () => {
-  it('should use new payment flow when enabled', async () => {
-    const isEnabled = await testProvider.isEnabled('NEW_PAYMENT_FLOW');
-    expect(isEnabled).toBe(true);
-  });
-});
-```
-
-## 🗄️ Cache System
-
-The cache system provides intelligent caching strategies for business logic coordination:
-
-### Basic Usage
-
-```typescript
-import { CacheManager } from '@plyaz/core/cache';
-
-// Initialize with memory strategy
-const cache = new CacheManager({
-  isEnabled: true,
-  ttl: 300, // 5 minutes
-  strategy: 'memory',
-  memoryConfig: {
-    maxSize: 1000,
-    cleanupInterval: 60000 // 1 minute
-  }
-});
-
-// Store data
-await cache.set('user:123', userData, 600); // Custom TTL of 10 minutes
-
-// Retrieve data
-const user = await cache.get<User>('user:123');
+### Engine Layer
+- **Feature Flag Engine**: Complete evaluation logic with rules and conditions
+- **Future Engines**: Calculation, Incentive, Validation, Insights (planned)
 
-// Check existence
-const exists = await cache.has('user:123');
-
-// Remove specific key
-await cache.delete('user:123');
-
-// Clear all cache
-await cache.clear();
-
-// Get cache statistics
-const stats = await cache.getStats();
-console.log(`Cache hit ratio: ${stats.hitRatio}`);
-```
-
-### Redis Strategy
-
-```typescript
-import { CacheManager } from '@plyaz/core/cache';
-
-const cache = new CacheManager({
-  isEnabled: true,
-  ttl: 300,
-  strategy: 'redis',
-  redisConfig: {
-    url: 'redis://localhost:6379',
-    keyPrefix: 'myapp:',
-    db: 0
-  }
-});
-```
-
-### Integration with Feature Flags
-
-```typescript
-// Feature flags use the cache system internally
-const provider = new MemoryFeatureFlagProvider({
-  provider: 'memory',
-  isCacheEnabled: true,  // Enables caching
-  cacheTtl: 300          // Cache TTL in seconds
-}, FEATURES);
-
-// The provider automatically caches evaluations for performance
-```
-
-### Business Logic Caching Patterns
-
-```typescript
-import { CacheManager } from '@plyaz/core/cache';
-
-class UserService {
-  constructor(private cache: CacheManager) {}
-
-  async getUser(userId: string): Promise<User> {
-    // Try cache first
-    const cacheKey = `user:${userId}`;
-    const cached = await this.cache.get<User>(cacheKey);
-    
-    if (cached) {
-      return cached;
-    }
-
-    // Fetch from database
-    const user = await this.fetchUserFromDb(userId);
-    
-    // Cache for future requests
-    await this.cache.set(cacheKey, user, 600); // 10 minutes
-    
-    return user;
-  }
-
-  async invalidateUser(userId: string): Promise<void> {
-    await this.cache.delete(`user:${userId}`);
-  }
-}
-```
-
-## 🔧 Key Features
+## 🔧 Key Capabilities
 
 - **Environment Isolation**: Complete separation of frontend and backend code
-- **Business Caching**: Intelligent caching strategies for cross-package data coordination
-- **Feature Flags**: Complete feature flag system with multiple providers
-- **Domain-Driven Design**: Clear bounded contexts for different business domains
-- **SDK Ready**: B2B partner integration capabilities
-- **Type Safe**: Full TypeScript support across all environments
-
-## 🏛️ Microservice Strategy
-
-Install `@plyaz/core` into individual microservices and import only needed functionality:
-
-```typescript
-// User Service - only imports user-related functionality
-import { UserDomainService, UserCacheService } from '@plyaz/core/domain';
-
-// Asset Service - only imports asset-related functionality  
-import { AssetDomainService, CalculationEngine } from '@plyaz/core';
-```
+- **Type Safety**: Full TypeScript support with strict boundaries
+- **Domain-Driven Design**: Clear bounded contexts for business domains
+- **Extensible Architecture**: Provider pattern for easy extension
+- **Performance Optimized**: Built-in caching and efficient evaluation
+- **Testing Support**: Override capabilities and test utilities
 
 ## 📚 Documentation
 
@@ -353,6 +84,12 @@ For detailed architecture information, implementation guides, and examples:
 
 **[📖 Full Documentation](https://plyaz.atlassian.net/wiki/spaces/SD/pages/37257227/Core+Package?atlOrigin=eyJpIjoiNmQxZmNhYTllYmZjNDU2Njk0YmRhYWI2M2JkNTA3NDMiLCJwIjoiYyJ9)**
 
+### 📄 Confluence Documentation
+
+- **[Feature Flag System](https://plyaz.atlassian.net/wiki/spaces/SD/pages/44859395/Feature+Flag+System+plyaz+core?atlOrigin=eyJpIjoiNjEyMWY3N2ViZDUxNDIxZTgxNGRmZWMwNjQwMzhiOTQiLCJwIjoiYyJ9)** - Complete feature flag implementation guide
+- **[Engine Layer](https://plyaz.atlassian.net/wiki/spaces/SD/pages/44892169/Engine+Layer+plyaz+core?atlOrigin=eyJpIjoiYTI5M2JhOTA5M2Q4NDY1ZjkzZjM2Yzk5M2U5MTZlMzUiLCJwIjoiYyJ9)** - Core computational engines documentation
+- **[Cache System](https://plyaz.atlassian.net/wiki/spaces/SD/pages/44892180/Cache+System+plyaz+core?atlOrigin=eyJpIjoiNDU2MTU5MWU0NTQ1NDIyMzk0MzJkNjE3MDkyOWVkZDQiLCJwIjoiYyJ9)** - Caching strategies and implementation
+
 ## 🔗 Related Packages
 
 | Package | Purpose | Core Usage |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plyaz/core",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Shared core logic and utilities for Plyaz apps, services, and future SDKs – centralized, reusable, and scalable.",
   "type": "module",
   "keywords": [],