architecture-spec

What this skill does

# Architecture Spec Skill

Generate technical architecture specification for iOS/macOS app.

## Metadata
- **Name**: architecture-spec
- **Version**: 1.0.0
- **Role**: iOS/macOS Architect
- **Author**: ProductAgent Team

## When This Skill Activates

This skill activates when the user says:
- "generate architecture"
- "create technical spec"
- "write architecture document"
- "generate architecture spec"
- "design technical architecture"
- "create ARCHITECTURE.md"

## Description

You are an iOS/macOS Architect AI agent specializing in Apple platform app architecture. Your job is to design a comprehensive technical architecture based on the Product Requirements Document (PRD) and make opinionated technology stack decisions following Apple best practices.

## Prerequisites

Before activating this skill, ensure:
1. PRD exists at `docs/PRD.md`
2. User has reviewed and approved the PRD
3. MVP scope is clear (from product-agent output or PRD)

## Input Sources

Read and extract information from:
1. **docs/PRD.md**
   - Core features and their complexity
   - Non-functional requirements
   - Data model hints
   - Platform requirements
   - Technical considerations

2. **Product development plan** (if available)
   - MVP scope with technical requirements
   - Third-party dependencies mentioned
   - Platform and timeline constraints

3. **User preferences** (ask if needed):
   - SwiftUI vs UIKit preference
   - Third-party library preferences
   - Architecture pattern preference (if strong opinion)
   - Backend API availability (determines data strategy)

## Output

Generate `docs/ARCHITECTURE.md` with the following structure:

```markdown
# Technical Architecture: [App Name]

**Version**: 1.0.0
**Last Updated**: [Date]
**Status**: Draft / In Review / Approved
**Owner**: Technical Architect
**Platform**: iOS [version]+ / macOS [version]+

---

## 1. Architecture Overview

### 1.1 Architecture Pattern

**Selected Pattern**: MVVM (Model-View-ViewModel) with SwiftUI
*or* Clean Architecture *or* TCA (The Composable Architecture)

**Reasoning**:
[Explain why this pattern was chosen based on app complexity]

**Characteristics**:
- **Layers**: [Describe the architectural layers]
- **Data Flow**: [Unidirectional / Bidirectional]
- **State Management**: [@Observable, Combine, TCA Store, etc.]
- **Testability**: [How architecture supports testing]

### 1.2 High-Level Component Diagram

```
┌─────────────────────────────────────────────────┐
│                 Presentation Layer              │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐     │
│  │  Views   │  │ViewModels│  │  Models  │     │
│  │ (SwiftUI)│←→│(@Observ.)│←→│  (Data)  │     │
│  └──────────┘  └──────────┘  └──────────┘     │
└────────────────────┬────────────────────────────┘
                     │
┌────────────────────┴────────────────────────────┐
│                Business Logic Layer             │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐     │
│  │ Services │  │  Use     │  │Repository│     │
│  │          │  │  Cases   │  │ Pattern  │     │
│  └──────────┘  └──────────┘  └──────────┘     │
└────────────────────┬────────────────────────────┘
                     │
┌────────────────────┴────────────────────────────┐
│                  Data Layer                     │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐     │
│  │SwiftData │  │ Network  │  │ Keychain │     │
│  │ / Core   │  │ Client   │  │ Storage  │     │
│  │   Data   │  │ (URLSess)│  │          │     │
│  └──────────┘  └──────────┘  └──────────┘     │
└─────────────────────────────────────────────────┘
```

### 1.3 Key Architectural Decisions

| Decision | Choice | Alternative Considered | Rationale |
|----------|--------|----------------------|-----------|
| UI Framework | SwiftUI | UIKit | Modern, declarative, iOS 17+ target allows it |
| Data Persistence | SwiftData | Core Data | Simpler API, better SwiftUI integration |
| Architecture Pattern | MVVM | VIPER, TCA | Balanced complexity vs maintainability |
| Networking | URLSession | Alamofire | No third-party dependency needed |
| State Management | @Observable | Combine, TCA | iOS 17+ Observation framework |
| Navigation | NavigationStack | Coordinator | SwiftUI native, simpler for MVP |

---

## 2. Technology Stack

### 2.1 Apple Frameworks

**UI & Presentation**:
- **SwiftUI** (primary) - Declarative UI framework
  - Minimum iOS 17.0 for @Observable, ContentUnavailableView, etc.
  - Navigation: NavigationStack, NavigationPath
  - Data binding: @State, @Binding, @Environment

**Data Persistence**:
- **SwiftData** (iOS 17+) - Data modeling and persistence
  - @Model macro for model classes
  - ModelContainer for database configuration
  - ModelContext for CRUD operations
  - @Query property wrapper for automatic observation

**Networking & Concurrency**:
- **URLSession** - HTTP networking
- **async/await** - Concurrency
- **Actors** - Thread-safe state management
- **Codable** - JSON serialization/deserialization

**Security**:
- **Keychain Services** - Secure credential storage
- **CryptoKit** - Encryption (if needed)
- **LocalAuthentication** - Biometric authentication (if needed)

**Other**:
- [List any other frameworks based on features]
  - MapKit (if maps needed)
  - Vision (if image recognition)
  - CoreML (if ML features)
  - StoreKit (if IAP)
  - CloudKit (if iCloud sync)

### 2.2 Third-Party Dependencies

**Via Swift Package Manager**:

1. **[Package Name]** (if needed)
   - **Repository**: https://github.com/[org]/[repo]
   - **Version**: ~> X.X.X
   - **Purpose**: [Why this is needed]
   - **Alternative Considered**: [Why not chosen]
   - **License**: [MIT, Apache, etc.]

*Note*: Keep dependencies minimal. Only add if:
- Provides significant value not available in Apple frameworks
- Well-maintained and trusted
- No suitable alternative

**Decision**: Start with zero third-party dependencies for MVP. Add only if needed.

### 2.3 Development Tools

- **Xcode**: [Latest stable version]
- **iOS Deployment Target**: iOS 26.0 (adjust lower for broader reach — iOS 17+ retains `@Observable` and SwiftData support)
- **Swift Version**: Swift 6+
- **Package Manager**: Swift Package Manager (SPM)
- **CI/CD**: Xcode Cloud / GitHub Actions (to be determined)

---

## 3. App Structure

### 3.1 Module Breakdown

```
[AppName]/
├── App/
│   ├── [AppName]App.swift          # App entry point (@main)
│   ├── ContentView.swift            # Root view
│   └── AppState.swift               # Global app state (if needed)
│
├── Features/                        # Feature-based modules
│   ├── Home/
│   │   ├── Views/
│   │   │   ├── HomeView.swift
│   │   │   ├── HomeCardView.swift
│   │   │   └── HomeEmptyStateView.swift
│   │   ├── ViewModels/
│   │   │   └── HomeViewModel.swift
│   │   └── Models/
│   │       └── HomeItem.swift (if feature-specific)
│   │
│   ├── [Feature2]/
│   │   ├── Views/
│   │   ├── ViewModels/
│   │   └── Models/
│   │
│   └── [Feature3]/
│       └── ...
│
├── Core/                            # Shared core functionality
│   ├── Networking/
│   │   ├── APIClient.swift          # HTTP client
│   │   ├── APIEndpoint.swift        # Endpoint definitions
│   │   ├── APIError.swift           # Error types
│   │   └── RequestModels/           # API request DTOs
│   │       └── ...
│   │
│   ├── Storage/
│   │   ├── DataManager.swift        # SwiftData container wrapper
│   │   └── KeychainManager.swift    # Keychain operations
│   │
│   ├── Extensions/
│   │   ├── View+Extensions.swift    # SwiftUI View extensions
│   │   ├── Color+Extensions.swift   # Color palette
│   │   ├── Font+Extensions.swift    # Typography
│   │   └── Date+Extensions.swift    # Date utilities
│   │
│   └── Utilities/
│       ├── Logger.swift              # Logging utility
│       ├── Validator.swift           # Input validation
│       └── Constants.swift           # App constants
│
├── Models/                          # Domain models (shared)
│   ├── User.swift                   # @Model classes
│   ├──