pos-system/apps/app-client-base-swift/docs/en/README.md

# App Client Base Swift

> Native iOS client application for GoodGo platform, built with Swift and SwiftUI following MVVM architecture.

## 📱 Features

| Feature | Description |
|---------|-------------|
| 🔐 Authentication | Login, Register, Forgot Password with form validation |
| 🏠 Home Dashboard | Dynamic greeting, Featured items, Activity feed |
| 🔍 Explore | Discover locations and services |
| 👤 Profile | User profile management and settings |
| 🌓 Dark Mode | Automatic dark mode support |
| 🌐 i18n | Multi-language support (Vietnamese & English) |

## 🛠️ Tech Stack

| Technology | Version | Purpose |
|------------|---------|---------|
| Swift | 5.9+ | Primary language |
| SwiftUI | iOS 15+ | Declarative UI framework |
| Xcode | 15.0+ | IDE development |
| URLSession | Native | HTTP networking |
| Keychain | Native | Secure token storage |
| Combine | Native | Reactive programming |

## 📋 Prerequisites

- **macOS**: 14.0+ (Sonoma)
- **Xcode**: 15.0+
- **iOS Target**: 15.0+
- **Apple Developer Account**: Required for device deployment

## 🚀 Quick Start

### 1. Clone and open project
```bash
cd apps/app-client-base-swift
open AppClientBaseSwift/AppClientBaseSwift.xcodeproj
```

### 2. Select Simulator
- Xcode menu: **Product > Destination > iPhone 15 Pro** (or another simulator)

### 3. Build and Run
```bash
# Using shortcut
⌘R (Command + R)

# Or from terminal
xcodebuild -project AppClientBaseSwift/AppClientBaseSwift.xcodeproj \
  -scheme AppClientBaseSwift \
  -destination 'platform=iOS Simulator,name=iPhone 15 Pro' \
  build
```

### 4. Mock Login (for testing)
```
Email: admin@goodgo.com
Password: 123456
```

## 📂 Project Structure

```
AppClientBaseSwift/
├── App/
│   └── AppClientBaseSwiftApp.swift     # @main entry point
│
├── Core/
│   ├── Constants/
│   │   └── Constants.swift              # API, App, Storage, DesignSystem
│   └── Extensions/
│       ├── View+Extensions.swift        # SwiftUI modifiers
│       └── String+Extensions.swift      # Validation, formatting
│
├── Models/
│   └── User.swift                       # User entity + extensions
│
├── ViewModels/                          # MVVM ViewModels
│   ├── AuthViewModel.swift              # Login/Register/ForgotPassword
│   ├── HomeViewModel.swift              # Home screen logic
│   └── ProfileViewModel.swift           # Profile management
│
├── Views/
│   ├── Auth/                            # Authentication screens
│   ├── Home/                            # Home components
│   └── Screens/                         # Main screens
│
├── Services/
│   ├── APIService.swift                 # HTTP client with URLSession
│   └── AuthManager.swift                # Auth state + Keychain
│
└── Resources/
    ├── Assets.xcassets/                 # Images & Colors
    ├── en.lproj/                        # English localization
    └── vi.lproj/                        # Vietnamese localization
```

## 🎨 Architecture

### MVVM Pattern

```
┌─────────────────────────────────────────────────────────────┐
│                      VIEW (SwiftUI)                          │
│  HomeView, ProfileView, AuthContainerView, LoginView...     │
├─────────────────────────────────────────────────────────────┤
│                @StateObject / @EnvironmentObject             │
├─────────────────────────────────────────────────────────────┤
│                    VIEWMODEL (ObservableObject)              │
│  HomeViewModel, AuthViewModel, ProfileViewModel              │
│  • @Published properties for reactive UI                     │
│  • async/await methods for data loading                      │
├─────────────────────────────────────────────────────────────┤
│                Protocol-based Dependency Injection           │
├─────────────────────────────────────────────────────────────┤
│                        SERVICES                              │
│  APIService (HTTP) • AuthManager (Auth State + Keychain)     │
└─────────────────────────────────────────────────────────────┘
```

## 📋 Coding Conventions

### File Structure
```swift
// MARK: - Imports
import SwiftUI

// MARK: - Type Definition
/// Description in English
struct/class/enum TypeName {
    // MARK: - Properties
    // MARK: - Init
    // MARK: - Public Methods
    // MARK: - Private Methods
}
```

### ViewModel Pattern
```swift
@MainActor
final class FeatureViewModel: ObservableObject {
    @Published var isLoading = false
    @Published var errorMessage: String?
    
    private let apiService: APIServiceProtocol
    
    init(apiService: APIServiceProtocol = APIService.shared) {
        self.apiService = apiService
    }
    
    func loadData() async {
        isLoading = true
        defer { isLoading = false }
        // ...
    }
}
```

## ⚙️ Configuration

### API Configuration
```swift
enum APIConfig {
    static let baseURL = "https://api.goodgo.vn"
    static let apiVersion = "/api/v1"
    static let timeout: TimeInterval = 30.0
}
```

## 🧪 Testing

```bash
xcodebuild test \
  -project AppClientBaseSwift/AppClientBaseSwift.xcodeproj \
  -scheme AppClientBaseSwift \
  -destination 'platform=iOS Simulator,name=iPhone 15 Pro'
```

## 🔐 Security

| Feature | Implementation |
|---------|----------------|
| Token Storage | Keychain Services (not UserDefaults) |
| Secure Requests | HTTPS only, Bearer token auth |
| Session Management | Auto token refresh, secure logout |
| Data Protection | Sensitive data encrypted at rest |

## 📱 Supported Devices

- **iPhone**: 8 and later (iOS 15+)
- **iPad**: All iPads with iOS 15+
- **Orientations**: Portrait (primary), Landscape (supported)

## 🔗 Related Projects

- [app-client-base-net](../app-client-base-net) - .NET MAUI cross-platform client
- [iam-service-net](../../services/iam-service-net) - Authentication backend

## 📚 Additional Documentation

- [Architecture Guide](./architecture.md) - Detailed architecture and design decisions

## 📄 License

Copyright © 2026 GoodGo. All rights reserved.