awesome-claude-md

sergelents/CartWise

View CLAUDE.md
complex projects Updated 2026-02-10

Analysis

Category: Complex Projects Source: sergelents/CartWise CLAUDE.md: View Original License: Not specified Why it's exemplary: Demonstrates comprehensive iOS architecture documentation with MVVM+Coordinator patterns, Swift Actor model usage, and detailed data flow explanations for complex mobile applications.

Key Features That Make This Exemplary

1. MVVM+Coordinator Architecture

  • Hybrid Navigation: AppCoordinator for root-level flow with 5 specialized child coordinators
  • Lazy Initialization: Child coordinators instantiate only on tab access
  • Cleanup Patterns: Documented coordinator cleanup obligations on logout
  • ViewModel Ownership: Clear rules for shared vs. isolated ViewModels

2. Swift Actor Model for Core Data

  • Thread Safety: CoreDataStack leverages Swift's actor pattern
  • Compile-Time Guarantees: "Compile-time safety checks" for data races
  • Modern Concurrency: async/await patterns throughout
  • Error Propagation: Consistent try/catch with published errorMessage

3. Soft-Delete Implementation Pattern

  • Data Integrity: Products flagged rather than permanently removed
  • Historical Preservation: Maintains price history and social context
  • Clear Rationale: Documents why soft-delete was chosen
  • Implementation Details: isInShoppingList boolean controls visibility

4. Comprehensive Data Flow Documentation

  • Product Addition Flow: Step-by-step from user action to persistence
  • Price Comparison Logic: 85% threshold for store inclusion
  • Social Feed Architecture: Reputation-based gamification system
  • Image Caching Strategy: Two-tier URL + binary cache

Specific Techniques to Learn

Coordinator Pattern Documentation

**Navigation Architecture:**
- AppCoordinator: Root-level flow management
- ShoppingListCoordinator: Shopping list feature navigation
- SearchItemsCoordinator: Product search navigation
- SocialFeedCoordinator: Community features (isolated ViewModel)
- Lazy initialization reduces memory footprint

Clear hierarchy with ownership and lifecycle rules.

Actor-Based Persistence

**CoreDataStack (Actor):**
- Swift actor for thread-safe Core Data operations
- Compile-time data race prevention
- Async/await integration throughout
- Protocol-based ProductRepository facade

Documents modern Swift concurrency patterns.

Gamification System

**Reputation Levels:**
- New Shopper → Regular → Smart → Expert → Master → Legendary
- Progression based on UserEntity.updates counter
- Each level unlocks community features
- Contribution tracking via ReputationManager

Complete gamification logic documentation.

Operational Patterns

**Quiet vs. Loud Operations:**
- Background checks: Avoid full list reloads (prevent UI flicker)
- User-initiated actions: Trigger comprehensive refreshes
- Clear distinction prevents UX issues

Documents UX-informed implementation decisions.

Key Takeaways

  1. Document Architecture Patterns: Explain MVVM+Coordinator with specific responsibilities
  2. Modern Swift Concurrency: Show Actor model and async/await integration
  3. Data Persistence Strategies: Document soft-delete rationale and implementation
  4. Complete Data Flows: Trace operations from user action to database
  5. UX-Informed Decisions: Include patterns like "quiet vs. loud" operations

Attribution

This analysis references the original CLAUDE.md from sergelents/CartWise. All credit for the original documentation belongs to the repository maintainers.