@umituz/react-native-subscription 2.14.99 → 2.14.101

package/src/domains/README.md.bak

@@ -0,0 +1,274 @@
+# Domains
+
+Specialized domain modules implementing specific business logic and features.
+
+## Location
+
+**Directory**: `src/domains/`
+
+**Type**: Domain Collection
+
+## Strategy
+
+### Domain-Driven Design
+
+This directory implements Domain-Driven Design (DDD) principles:
+
+1. **Wallet Domain**: Credit balance, transactions, and purchase flow
+2. **Paywall Domain**: Upgrade prompts, subscription management
+3. **Config Domain**: Feature flags, subscription configuration
+
+Each domain is self-contained with:
+- **Domain Layer**: Business logic, entities, value objects
+- **Infrastructure Layer**: External integrations, repositories
+- **Presentation Layer**: Domain-specific hooks and components
+
+### Architecture Pattern
+
+```
+┌─────────────────────────────────────┐
+│         Application Layer           │
+│    (Use Cases, Orchestration)       │
+└──────────────┬──────────────────────┘
+               │
+       ┌───────┴────────┐
+       │                │
+┌──────▼──────┐  ┌─────▼──────┐
+│ Wallet      │  │ Paywall    │
+│ Domain      │  │ Domain     │
+├─────────────┤  ├────────────┤
+│ Domain      │  │ Domain     │
+│ Infra       │  │ Infra      │
+│ Presentation│  │ Presentation│
+└──────┬──────┘  └─────┬──────┘
+       │                │
+       └────────┬───────┘
+                │
+       ┌────────▼──────────┐
+       │ Shared Infra      │
+       │ (Firebase, etc)   │
+       └───────────────────┘
+```
+
+## Domain Modules
+
+### Wallet Domain (`wallet/`)
+
+**Responsibility**: Credit balance and transaction management
+
+**Key Features**:
+- Credit balance tracking
+- Transaction history
+- Purchase initialization
+- Real-time updates
+
+**Documentation**: `wallet/README.md`
+
+### Paywall Domain (`paywall/`)
+
+**Responsibility**: Subscription upgrade flows and paywall UI
+
+**Key Features**:
+- Paywall display logic
+- Subscription management
+- Feature gating
+- Upgrade prompts
+
+**Documentation**: `paywall/README.md`
+
+### Config Domain (`config/`)
+
+**Responsibility**: Subscription configuration and feature flags
+
+**Key Features**:
+- Subscription tiers
+- Feature configuration
+- Pricing rules
+- Feature flags
+
+**Documentation**: `config/README.md`
+
+## Restrictions
+
+### REQUIRED
+
+- **Domain Isolation**: Domains MUST NOT directly depend on each other
+- **Interface Segregation**: Use well-defined interfaces between layers
+- **Dependency Inversion**: Depend on abstractions, not concretions
+- **Testability**: All domains MUST be testable in isolation
+
+### PROHIBITED
+
+- **NEVER** share domain logic between domains (use shared kernel if needed)
+- **NEVER** create circular dependencies between domains
+- **DO NOT** bypass domain layer from presentation
+- **NEVER** expose infrastructure details to other domains
+
+### CRITICAL SAFETY
+
+- **ALWAYS** validate invariants at domain boundaries
+- **ALWAYS** implement domain errors for business rule violations
+- **NEVER** allow inconsistent domain state
+- **MUST** implement proper transaction boundaries
+- **ALWAYS** sanitize inputs from external sources
+
+## Rules
+
+### Domain Boundaries
+
+```typescript
+// CORRECT - Respecting domain boundaries
+// Wallet domain handles credits
+const { credits } = useCredits(); // From wallet domain
+
+// Paywall domain handles upgrades
+const { showPaywall } = usePaywallOperations(); // From paywall domain
+
+// INCORRECT - Crossing domain boundaries
+const walletRepository = new WalletRepository();
+// Directly using wallet repo in paywall component
+```
+
+### Domain Errors
+
+```typescript
+// CORRECT - Domain-specific errors
+class InsufficientCreditsError extends DomainError {
+  constructor(required: number, available: number) {
+    super(`Insufficient credits: need ${required}, have ${available}`);
+  }
+}
+
+// INCORRECT - Generic errors
+throw new Error('Not enough credits'); // Loses domain context
+```
+
+### Dependency Direction
+
+```typescript
+// CORRECT - Dependency inversion
+interface ICreditsRepository {
+  getBalance(userId: string): Promise<number>;
+  deductCredits(userId: string, amount: number): Promise<void>;
+}
+
+// Domain depends on interface, not implementation
+class CreditService {
+  constructor(private repo: ICreditsRepository) {}
+}
+
+// INCORRECT - Concrete dependency
+class CreditService {
+  constructor(private repo: FirebaseCreditsRepository) {}
+  // Tightly coupled to Firebase
+}
+```
+
+## AI Agent Guidelines
+
+### When Working with Domains
+
+1. **Always** respect domain boundaries
+2. **Always** use dependency inversion
+3. **Always** implement domain-specific errors
+4. **Always** validate invariants at boundaries
+5. **Never** create circular dependencies
+
+### Integration Checklist
+
+- [ ] Identify correct domain for feature
+- [ ] Respect domain boundaries
+- [ ] Use appropriate interfaces
+- [ ] Handle domain errors
+- [ ] Test domain in isolation
+- [ ] Document domain interactions
+- [ ] Validate invariants
+- [ ] Implement transaction boundaries
+- [ ] Test cross-domain scenarios
+- [ ] Verify no circular dependencies
+
+### Common Patterns
+
+1. **Aggregate Root**: Single entry point for aggregate
+2. **Value Objects**: Immutable values with no identity
+3. **Domain Events**: Publish domain events for side effects
+4. **Repositories**: Abstract data access
+5. **Factories**: Complex object creation
+6. **Domain Services**: Business logic that doesn't fit entities
+7. **Specification**: Business rule encapsulation
+8. **Anti-Corruption Layer**: Isolate from external systems
+
+## Related Documentation
+
+- **Wallet Domain**: `wallet/README.md`
+- **Paywall Domain**: `paywall/README.md`
+- **Config Domain**: `config/README.md`
+- **Domain Layer**: `../domain/README.md`
+- **Infrastructure**: `../infrastructure/README.md`
+
+## Domain Structure
+
+```
+src/domains/
+├── wallet/                # Wallet and credits domain
+│   ├── domain/           # Business logic
+│   ├── infrastructure/   # External integrations
+│   └── presentation/     # UI hooks and components
+├── paywall/              # Paywall and upgrades domain
+│   ├── domain/
+│   ├── infrastructure/
+│   └── presentation/
+└── config/               # Configuration domain
+    ├── domain/
+    ├── infrastructure/
+    └── presentation/
+```
+
+## Creating a New Domain
+
+When creating a new domain:
+
+1. **Define Boundaries**: What is the domain's responsibility?
+2. **Identify Entities**: What are the core business objects?
+3. **Define Invariants**: What rules must always be true?
+4. **Design Interfaces**: How will other layers interact?
+5. **Implement Repository**: Abstract data access
+6. **Create Presentation Layer**: Hooks and components
+7. **Write Tests**: Test domain logic in isolation
+8. **Document**: Provide comprehensive README
+
+Example:
+
+```typescript
+// Domain entity
+export class FeatureFlag {
+  constructor(
+    public readonly id: string,
+    public readonly name: string,
+    private _isEnabled: boolean
+  ) {}
+
+  get isEnabled(): boolean {
+    return this._isEnabled;
+  }
+
+  enable(): void {
+    this._isEnabled = true;
+  }
+
+  disable(): void {
+    this._isEnabled = false;
+  }
+}
+
+// Repository interface
+export interface IFeatureFlagRepository {
+  findById(id: string): Promise<FeatureFlag | null>;
+  save(flag: FeatureFlag): Promise<void>;
+}
+
+// Presentation hook
+export function useFeatureFlag(featureId: string) {
+  // Hook implementation
+}
+```