@shaykec/app-agent 1.0.0

package/templates/ios/ChatTemplate/ChatTemplate/ARCHITECTURE.md

@@ -0,0 +1,726 @@
+# ChatTemplate - iOS Architecture
+
+## Overview
+
+ChatTemplate implements **MVVM with SwiftUI**, designed for real-time messaging applications with WebSocket support.
+
+## Architecture Diagram
+
+```mermaid
+graph TB
+    subgraph Views["Views (SwiftUI)"]
+        CV[ConversationsView]
+        CHV[ChatView]
+        CAV[CallsView]
+        COV[ContactsView]
+        SV[SettingsView]
+    end
+    
+    subgraph ViewModels["ViewModels"]
+        CVM[ConversationsViewModel]
+        MVM[MessagesViewModel]
+        CAVM[CallViewModel]
+    end
+    
+    subgraph Models["Models"]
+        CM[Conversation]
+        MM[Message]
+        UM[User]
+        CLM[Call]
+    end
+    
+    subgraph Services["Services"]
+        WS[WebSocketService]
+        NS[NotificationService]
+        CS[CallService]
+        ES[EncryptionService]
+        MD[MockDataProvider]
+    end
+    
+    Views --> ViewModels
+    ViewModels --> Models
+    ViewModels --> Services
+    WS -.-> ViewModels
+```
+
+## Real-Time Message Flow
+
+```mermaid
+sequenceDiagram
+    participant U as User
+    participant V as ChatView
+    participant VM as MessagesViewModel
+    participant WS as WebSocket
+    participant S as Server
+    
+    U->>V: Type message
+    V->>VM: sendMessage(text)
+    VM->>VM: Create local message (pending)
+    VM-->>V: Update UI (pending)
+    VM->>WS: Send via WebSocket
+    WS->>S: Deliver message
+    S-->>WS: Acknowledge (delivered)
+    WS->>VM: Update status
+    VM-->>V: Update UI (delivered)
+    
+    Note over S: Recipient online
+    S-->>WS: Read receipt
+    WS->>VM: Update status
+    VM-->>V: Update UI (read)
+```
+
+## Project Structure
+
+```
+ChatTemplate/
+├── App/
+│   ├── ChatTemplateApp.swift
+│   └── AppConfig.swift
+├── Models/
+│   └── Models.swift
+│       ├── User
+│       ├── Conversation
+│       ├── Message
+│       ├── Call
+│       └── Attachment
+├── Features/
+│   ├── Navigation/
+│   │   └── MainTabView.swift
+│   ├── Conversations/
+│   │   ├── ConversationsView.swift
+│   │   ├── ConversationRow.swift
+│   │   └── NewChatView.swift
+│   ├── Chat/
+│   │   ├── ChatView.swift
+│   │   ├── MessageBubble.swift
+│   │   ├── MessageInput.swift
+│   │   ├── MediaPreview.swift
+│   │   └── ChatHeader.swift
+│   ├── Calls/
+│   │   ├── CallsView.swift
+│   │   ├── ActiveCallView.swift
+│   │   └── IncomingCallView.swift
+│   ├── Contacts/
+│   │   ├── ContactsView.swift
+│   │   └── ContactDetailView.swift
+│   └── Settings/
+│       ├── SettingsView.swift
+│       └── ProfileView.swift
+├── MockData/
+│   └── MockDataProvider.swift
+└── Core/
+    ├── Theme/
+    ├── Components/
+    │   ├── AvatarView.swift
+    │   ├── OnlineIndicator.swift
+    │   └── TypingIndicator.swift
+    └── Services/
+        ├── WebSocketService.swift
+        ├── EncryptionService.swift
+        └── CallService.swift
+```
+
+## Data Models
+
+### User
+```swift
+struct User: Identifiable, Codable {
+    let id: String
+    var name: String
+    var avatar: String?
+    var phone: String?
+    var email: String?
+    var status: UserStatus
+    var lastSeen: Date?
+    var isBlocked: Bool
+}
+
+enum UserStatus: String, Codable {
+    case online
+    case offline
+    case away
+    case doNotDisturb
+}
+```
+
+### Conversation
+```swift
+struct Conversation: Identifiable, Codable {
+    let id: String
+    var type: ConversationType
+    var participants: [User]
+    var lastMessage: Message?
+    var unreadCount: Int
+    var isPinned: Bool
+    var isMuted: Bool
+    var isArchived: Bool
+    var createdAt: Date
+    var updatedAt: Date
+    
+    // For groups
+    var name: String?
+    var avatar: String?
+    var adminIds: [String]
+}
+
+enum ConversationType: String, Codable {
+    case direct
+    case group
+    case channel
+}
+```
+
+### Message
+```swift
+struct Message: Identifiable, Codable {
+    let id: String
+    var conversationId: String
+    var senderId: String
+    var content: String
+    var type: MessageType
+    var attachments: [Attachment]
+    var replyTo: String?         // Reply to message ID
+    var status: MessageStatus
+    var reactions: [MessageReaction]
+    var createdAt: Date
+    var editedAt: Date?
+    var deletedAt: Date?
+}
+
+enum MessageType: String, Codable {
+    case text
+    case image
+    case video
+    case audio
+    case file
+    case location
+    case contact
+    case sticker
+    case system
+}
+
+enum MessageStatus: String, Codable {
+    case pending
+    case sent
+    case delivered
+    case read
+    case failed
+}
+
+struct MessageReaction: Codable {
+    var emoji: String
+    var userId: String
+    var createdAt: Date
+}
+```
+
+### Attachment
+```swift
+struct Attachment: Identifiable, Codable {
+    let id: String
+    var type: AttachmentType
+    var url: String
+    var thumbnailUrl: String?
+    var fileName: String?
+    var fileSize: Int?
+    var mimeType: String?
+    var duration: Int?           // For audio/video
+    var dimensions: CGSize?      // For images/video
+}
+```
+
+### Call
+```swift
+struct Call: Identifiable, Codable {
+    let id: String
+    var conversationId: String
+    var callerId: String
+    var participants: [String]
+    var type: CallType
+    var status: CallStatus
+    var startedAt: Date?
+    var endedAt: Date?
+    var duration: Int?
+}
+
+enum CallType: String, Codable {
+    case audio
+    case video
+}
+
+enum CallStatus: String, Codable {
+    case ringing
+    case ongoing
+    case ended
+    case missed
+    case declined
+}
+```
+
+## State Management
+
+### MessagesViewModel
+```swift
+class MessagesViewModel: ObservableObject {
+    @Published var messages: [Message] = []
+    @Published var isTyping = false
+    @Published var typingUsers: [User] = []
+    @Published var error: Error?
+    
+    private var conversation: Conversation
+    private let webSocket: WebSocketService
+    
+    init(conversation: Conversation) {
+        self.conversation = conversation
+        self.webSocket = WebSocketService.shared
+        
+        setupWebSocketHandlers()
+        loadMessages()
+    }
+    
+    func sendMessage(_ content: String, type: MessageType = .text) {
+        let message = Message(
+            id: UUID().uuidString,
+            conversationId: conversation.id,
+            senderId: currentUserId,
+            content: content,
+            type: type,
+            attachments: [],
+            status: .pending,
+            reactions: [],
+            createdAt: Date()
+        )
+        
+        // Optimistic update
+        messages.append(message)
+        
+        // Send via WebSocket
+        webSocket.send(message)
+    }
+    
+    func markAsRead(_ messageId: String) {
+        webSocket.send(ReadReceipt(messageId: messageId, conversationId: conversation.id))
+    }
+    
+    private func setupWebSocketHandlers() {
+        webSocket.onMessage = { [weak self] message in
+            self?.handleIncomingMessage(message)
+        }
+        
+        webSocket.onStatusUpdate = { [weak self] update in
+            self?.updateMessageStatus(update)
+        }
+        
+        webSocket.onTyping = { [weak self] typing in
+            self?.handleTypingIndicator(typing)
+        }
+    }
+}
+```
+
+## Navigation Structure
+
+```mermaid
+graph LR
+    subgraph TabView
+        T1[Chats]
+        T2[Calls]
+        T3[Contacts]
+        T4[Settings]
+    end
+    
+    T1 --> CL[Conversation List]
+    CL --> CH[Chat View]
+    CH --> PR[Profile]
+    CH --> ME[Media Gallery]
+    CH --> SE[Search Messages]
+    CL --> NC[New Chat]
+    NC --> GR[New Group]
+    
+    T2 --> CAL[Call History]
+    CAL --> AC[Active Call]
+    
+    T3 --> CON[Contacts List]
+    CON --> CD[Contact Detail]
+    CD --> CH
+    
+    T4 --> SET[Settings]
+    SET --> PF[Profile]
+    SET --> PR[Privacy]
+    SET --> NT[Notifications]
+```
+
+## Key Components
+
+### MessageBubble
+```swift
+struct MessageBubble: View {
+    let message: Message
+    let isFromCurrentUser: Bool
+    let showAvatar: Bool
+    let onReply: () -> Void
+    let onReact: (String) -> Void
+    
+    var body: some View {
+        HStack(alignment: .bottom, spacing: 8) {
+            if !isFromCurrentUser && showAvatar {
+                AvatarView(url: message.senderAvatar, size: 32)
+            }
+            
+            VStack(alignment: isFromCurrentUser ? .trailing : .leading, spacing: 4) {
+                // Replied message preview
+                if let replyTo = message.replyTo {
+                    ReplyPreview(messageId: replyTo)
+                }
+                
+                // Message content
+                MessageContent(message: message, isFromCurrentUser: isFromCurrentUser)
+                
+                // Timestamp and status
+                HStack(spacing: 4) {
+                    Text(message.createdAt, style: .time)
+                        .font(.caption2)
+                    
+                    if isFromCurrentUser {
+                        MessageStatusIcon(status: message.status)
+                    }
+                }
+            }
+            
+            if isFromCurrentUser && showAvatar {
+                Spacer().frame(width: 32)
+            }
+        }
+        .contextMenu {
+            Button("Reply", action: onReply)
+            Menu("React") {
+                ForEach(["👍", "❤️", "😂", "😮", "😢", "😡"], id: \.self) { emoji in
+                    Button(emoji) { onReact(emoji) }
+                }
+            }
+        }
+    }
+}
+```
+
+### MessageInput
+```swift
+struct MessageInput: View {
+    @Binding var text: String
+    let onSend: () -> Void
+    let onAttachment: () -> Void
+    let onVoice: () -> Void
+    
+    @State private var isRecording = false
+    
+    var body: some View {
+        HStack(spacing: 12) {
+            Button(action: onAttachment) {
+                Image(systemName: "plus.circle.fill")
+                    .font(.title2)
+            }
+            
+            TextField("Message", text: $text, axis: .vertical)
+                .textFieldStyle(.plain)
+                .padding(.horizontal, 12)
+                .padding(.vertical, 8)
+                .background(Color(.systemGray6))
+                .cornerRadius(20)
+            
+            if text.isEmpty {
+                Button(action: onVoice) {
+                    Image(systemName: isRecording ? "stop.circle.fill" : "mic.circle.fill")
+                        .font(.title2)
+                        .foregroundColor(isRecording ? .red : .blue)
+                }
+            } else {
+                Button(action: onSend) {
+                    Image(systemName: "arrow.up.circle.fill")
+                        .font(.title2)
+                }
+            }
+        }
+        .padding()
+    }
+}
+```
+
+### TypingIndicator
+```swift
+struct TypingIndicator: View {
+    let users: [User]
+    
+    var body: some View {
+        HStack(spacing: 4) {
+            ForEach(users.prefix(3)) { user in
+                AvatarView(url: user.avatar, size: 20)
+            }
+            
+            HStack(spacing: 2) {
+                ForEach(0..<3) { index in
+                    Circle()
+                        .fill(Color.gray)
+                        .frame(width: 6, height: 6)
+                        .animation(
+                            Animation.easeInOut(duration: 0.5)
+                                .repeatForever()
+                                .delay(Double(index) * 0.15),
+                            value: true
+                        )
+                }
+            }
+            
+            Text(typingText)
+                .font(.caption)
+                .foregroundColor(.secondary)
+        }
+    }
+    
+    var typingText: String {
+        switch users.count {
+        case 1: return "\(users[0].name) is typing..."
+        case 2: return "\(users[0].name) and \(users[1].name) are typing..."
+        default: return "Several people are typing..."
+        }
+    }
+}
+```
+
+## WebSocket Service
+
+```swift
+class WebSocketService: ObservableObject {
+    static let shared = WebSocketService()
+    
+    @Published var isConnected = false
+    private var webSocket: URLSessionWebSocketTask?
+    private var pingTimer: Timer?
+    
+    // Callbacks
+    var onMessage: ((Message) -> Void)?
+    var onStatusUpdate: ((MessageStatusUpdate) -> Void)?
+    var onTyping: ((TypingEvent) -> Void)?
+    var onPresence: ((PresenceEvent) -> Void)?
+    
+    func connect() {
+        guard let url = URL(string: "\(AppConfig.API.wsURL)/chat") else { return }
+        
+        var request = URLRequest(url: url)
+        if let token = AuthManager.shared.token {
+            request.setValue("Bearer \(token)", forHTTPHeaderField: "Authorization")
+        }
+        
+        webSocket = URLSession.shared.webSocketTask(with: request)
+        webSocket?.resume()
+        isConnected = true
+        
+        listen()
+        startPing()
+    }
+    
+    func send(_ message: Message) {
+        let event = WebSocketEvent(type: "message", payload: message)
+        guard let data = try? JSONEncoder().encode(event),
+              let string = String(data: data, encoding: .utf8) else { return }
+        
+        webSocket?.send(.string(string)) { error in
+            if let error = error {
+                print("Send error: \(error)")
+            }
+        }
+    }
+    
+    func sendTyping(conversationId: String, isTyping: Bool) {
+        let event = WebSocketEvent(
+            type: "typing",
+            payload: TypingEvent(conversationId: conversationId, isTyping: isTyping)
+        )
+        // Send...
+    }
+    
+    private func listen() {
+        webSocket?.receive { [weak self] result in
+            switch result {
+            case .success(let message):
+                self?.handleMessage(message)
+                self?.listen()
+            case .failure:
+                self?.reconnect()
+            }
+        }
+    }
+    
+    private func handleMessage(_ message: URLSessionWebSocketTask.Message) {
+        guard case .string(let text) = message,
+              let data = text.data(using: .utf8),
+              let event = try? JSONDecoder().decode(WebSocketEvent.self, from: data)
+        else { return }
+        
+        DispatchQueue.main.async {
+            switch event.type {
+            case "message":
+                if let msg = event.message { self.onMessage?(msg) }
+            case "status":
+                if let update = event.statusUpdate { self.onStatusUpdate?(update) }
+            case "typing":
+                if let typing = event.typingEvent { self.onTyping?(typing) }
+            case "presence":
+                if let presence = event.presenceEvent { self.onPresence?(presence) }
+            default:
+                break
+            }
+        }
+    }
+    
+    private func startPing() {
+        pingTimer = Timer.scheduledTimer(withTimeInterval: 30, repeats: true) { [weak self] _ in
+            self?.webSocket?.sendPing { _ in }
+        }
+    }
+}
+```
+
+## End-to-End Encryption
+
+```swift
+class EncryptionService {
+    private let keychain = KeychainService.shared
+    
+    func generateKeyPair() throws -> (publicKey: Data, privateKey: Data) {
+        let attributes: [String: Any] = [
+            kSecAttrKeyType as String: kSecAttrKeyTypeECSECPrimeRandom,
+            kSecAttrKeySizeInBits as String: 256
+        ]
+        
+        var error: Unmanaged<CFError>?
+        guard let privateKey = SecKeyCreateRandomKey(attributes as CFDictionary, &error) else {
+            throw EncryptionError.keyGenerationFailed
+        }
+        
+        let publicKey = SecKeyCopyPublicKey(privateKey)!
+        
+        return (
+            SecKeyCopyExternalRepresentation(publicKey, nil)! as Data,
+            SecKeyCopyExternalRepresentation(privateKey, nil)! as Data
+        )
+    }
+    
+    func encrypt(_ message: String, for recipientPublicKey: Data) throws -> Data {
+        // Implement encryption
+    }
+    
+    func decrypt(_ data: Data) throws -> String {
+        // Implement decryption
+    }
+}
+```
+
+## Call Service (VoIP)
+
+```swift
+class CallService: NSObject, ObservableObject {
+    @Published var activeCall: Call?
+    @Published var callState: CallState = .idle
+    
+    private var callProvider: CXProvider?
+    private var callController: CXCallController?
+    
+    func startCall(to user: User, type: CallType) {
+        let uuid = UUID()
+        let handle = CXHandle(type: .generic, value: user.id)
+        
+        let startAction = CXStartCallAction(call: uuid, handle: handle)
+        startAction.isVideo = type == .video
+        
+        let transaction = CXTransaction(action: startAction)
+        callController?.request(transaction) { error in
+            if let error = error {
+                print("Call failed: \(error)")
+            }
+        }
+    }
+    
+    func answerCall(_ uuid: UUID) {
+        let answerAction = CXAnswerCallAction(call: uuid)
+        let transaction = CXTransaction(action: answerAction)
+        callController?.request(transaction)
+    }
+    
+    func endCall(_ uuid: UUID) {
+        let endAction = CXEndCallAction(call: uuid)
+        let transaction = CXTransaction(action: endAction)
+        callController?.request(transaction)
+    }
+}
+```
+
+## Persistence Strategy
+
+| Data | Storage | Sync |
+|------|---------|------|
+| Messages | CoreData | WebSocket + REST |
+| Conversations | CoreData | REST |
+| Contacts | CoreData | iCloud |
+| Media | FileManager | On-demand |
+| Keys | Keychain | N/A |
+
+## Testing Strategy
+
+| Test Type | Coverage |
+|-----------|----------|
+| Unit | Message parsing, encryption |
+| UI | Chat flow, input, attachments |
+| Integration | WebSocket, notifications |
+| Performance | Message rendering, scrolling |
+
+## Offline-First Data Layer
+
+The app includes a complete offline-first data architecture that makes CRUD operations functional without a backend.
+
+### Architecture
+
+```
+View Layer (SwiftUI)
+  ↓ observes
+ViewModel / Manager Layer
+  ↓ calls
+SyncManager (orchestrates mutations)
+  ↓              ↓
+MockDataProvider   OperationQueue
+(ObservableObject)  (persisted JSON)
+  ↓
+LocalPersistence (JSON files)
+
+NetworkMonitor (connectivity detection)
+```
+
+### Components
+
+| File | Purpose | Customized per app? |
+|------|---------|-------------------|
+| `Data/NetworkMonitor.swift` | Detects WiFi/cellular connectivity via NWPathMonitor | No |
+| `Data/LocalPersistence.swift` | JSON encode/decode to documents directory | No |
+| `Data/SyncManager.swift` | Orchestrates local mutations + sync queue | Yes (domain methods) |
+| `Components/OfflineBanner.swift` | Shows offline status banner | No |
+| `MockData/MockDataProvider.swift` | Mutable observable data store with CRUD | Yes (seed data) |
+
+### Data Flow
+
+1. **User action** (e.g., add to cart, create post) triggers ViewModel
+2. **ViewModel calls SyncManager** domain method
+3. **SyncManager applies locally** via MockDataProvider CRUD
+4. **SyncManager queues operation** for sync (persisted to JSON)
+5. **If online**, SyncManager processes queue (simulated sync)
+6. **If offline**, operation stays queued until connectivity returns
+7. **MockDataProvider publishes change** via `@Published` properties
+8. **Views automatically update** via SwiftUI observation
+
+### Persistence
+
+- User-mutated data (orders, favorites, reviews, etc.) persists to JSON files in the documents directory
+- On app launch, MockDataProvider loads from persistence or falls back to seed defaults
+- `reset()` method clears all persisted data and restores defaults
+
+### API Migration
+
+Replace the SyncManager's `processQueueIfOnline()` body with actual API calls. Each operation in the queue includes `entityType`, `action` (create/update/delete), and `entityId`. Look for `CUSTOMIZE:API` markers.