# CLAUDE.md Template - macOS App (SwiftUI)
# Place this file in the ROOT of your project folder

> For native macOS app development with SwiftUI

---

## 🎯 Project Overview

**Project Name:** [Your macOS App Name]
**Type:** macOS App
**Framework:** SwiftUI
**One-liner:** [What does this app do in one sentence?]

### Problem Being Solved
[Describe the core problem your users face]

### Target User
[Who is this for? Be specific]

### Success Looks Like
[What does a successful v1.0 look like?]

---

## 🛠️ Tech Stack

| Layer | Technology | Why |
|-------|------------|-----|
| UI | SwiftUI | Native, declarative |
| Architecture | MVVM + @Observable | Clean separation |
| Networking | URLSession + async/await | Native, performant |
| Storage | SwiftData | Modern persistence |
| Keychain | KeychainAccess | Secure storage |
| Analytics | TelemetryDeck | Privacy-friendly |

---

## 📁 Project Structure

```
MyApp/
├── App/
│   ├── MyApp.swift              # @main entry point
│   └── AppDelegate.swift        # If needed for lifecycle
├── Features/
│   ├── Auth/
│   │   ├── Views/
│   │   │   └── LoginView.swift
│   │   ├── ViewModels/
│   │   │   └── LoginViewModel.swift
│   │   └── Models/
│   │       └── User.swift
│   └── Dashboard/
│       └── ...
├── Core/
│   ├── Network/
│   │   └── APIClient.swift
│   ├── Storage/
│   │   └── DataStore.swift
│   └── Extensions/
│       └── View+Extensions.swift
├── Resources/
│   ├── Assets.xcassets
│   └── Localizable.strings
└── Tests/
    └── MyAppTests/
```

---

## ✅ Coding Conventions

### General
- Use Swift 5.9+ features
- Prefer value types (struct, enum) over classes
- Use `@Observable` macro (iOS 17+/macOS 14+)
- Keep views small, extract subviews

### SwiftUI Specific
```swift
// GOOD: Observable ViewModel
@Observable
class DashboardViewModel {
    var items: [Item] = []
    var isLoading = false
    
    func loadItems() async {
        isLoading = true
        defer { isLoading = false }
        items = await api.fetchItems()
    }
}

// GOOD: View with injected ViewModel
struct DashboardView: View {
    @State private var viewModel = DashboardViewModel()
    
    var body: some View {
        List(viewModel.items) { item in
            ItemRow(item: item)
        }
        .task { await viewModel.loadItems() }
    }
}
```

### Naming Conventions
- Types: PascalCase (`UserProfile`)
- Functions/Variables: camelCase (`fetchUser`)
- Constants: camelCase (`defaultTimeout`)
- Protocols: Descriptive, often ending in `-able` or `-ing`

### Error Handling
```swift
// Use typed errors
enum APIError: LocalizedError {
    case networkError(Error)
    case invalidResponse
    case unauthorized
    
    var errorDescription: String? {
        switch self {
        case .networkError(let error): return error.localizedDescription
        case .invalidResponse: return "Invalid server response"
        case .unauthorized: return "Please log in again"
        }
    }
}

// Handle with Result or throws
func fetchUser() async throws -> User {
    // ...
}
```

---

## 🚫 Do NOT

- Do not use force unwrap (`!`) except in tests
- Do not block main thread with sync operations
- Do not store secrets in UserDefaults (use Keychain)
- Do not ignore memory management (watch for retain cycles)
- Do not use AppKit unless SwiftUI lacks the capability
- Do not skip supporting both Intel and Apple Silicon

---

## 🖥️ macOS Specific Patterns

### Window Management
```swift
@main
struct MyApp: App {
    var body: some Scene {
        WindowGroup {
            ContentView()
        }
        .windowStyle(.hiddenTitleBar)
        .defaultSize(width: 800, height: 600)
        
        Settings {
            SettingsView()
        }
    }
}
```

### Menu Bar
```swift
MenuBarExtra("My App", systemImage: "star") {
    Button("Show Window") { /* action */ }
    Divider()
    Button("Quit") { NSApplication.shared.terminate(nil) }
}
```

### Keyboard Shortcuts
```swift
Button("Save") { save() }
    .keyboardShortcut("s", modifiers: .command)
```

### Sandboxing & Entitlements
- Enable App Sandbox for Mac App Store
- Request only needed entitlements
- Handle file access with proper security-scoped bookmarks

---

## 📋 Current Phase

**Current Focus:** [e.g., "MVP Development - Core Features"]

**What's Done:**
- [x] Project setup
- [x] Basic window structure
- [ ] Authentication
- [ ] Core feature

**What's Next:**
- [ ] Implement main UI
- [ ] Add persistence
- [ ] Prepare for notarization

---

## 🔗 Key Files to Know

| File | Purpose |
|------|---------|
| `MyApp.swift` | App entry point, scenes |
| `Core/Network/APIClient.swift` | Network layer |
| `Core/Storage/DataStore.swift` | SwiftData models |
| `Info.plist` | App configuration |
| `/docs/PRD.md` | Product requirements |

---

## 💬 How to Work With Me

**My Role:** I am the product owner and reviewer.

**Your Role:** You implement features following Apple HIG guidelines.

**Before Coding:**
- Check if SwiftUI can do it or if AppKit is needed
- Consider window management (single vs multi-window)
- Think about menu bar vs dock app

**Communication Style:**
- Explain SwiftUI vs AppKit tradeoffs
- Note macOS version requirements
- Flag Apple Silicon compatibility issues

---

## 📦 Distribution

### Development
- Sign with Development certificate
- Use Debug configuration

### Testing
- Use TestFlight for beta (Mac App Store)
- Or use direct notarization for outside distribution

### Release
- Mac App Store: Submit via App Store Connect
- Direct: Notarize with `notarytool` and staple

---

## 📚 Reference Documents

- [PRD](/docs/PRD.md) - Product Requirements
- [Tasks](/docs/tasks.md) - Current tasks
- [Apple HIG](https://developer.apple.com/design/human-interface-guidelines/macos)

---

*Last Updated: [Date]*