Sports Hub iOS

A starter project for iOS engineers who want to improve their skills according to company processes. This project serves as a learning playground for SwiftUI, navigation patterns, localization, design implementation, and AI-assisted code generation with tools like Cursor, Claude Code, GitHub Copilot, and others.

📱 Overview

Sports Hub is a sports news application built with SwiftUI targeting iOS 26+. It demonstrates modern iOS development practices including:

• Modern Swift Concurrency with @Observable (Swift 5.9+)
• Clean Architecture (Domain, Data, Presentation layers)
• Protocol-oriented design for testability
• Generic navigation system
• Environment-based configuration

🚀 Getting Started

Prerequisites

• Xcode 26.0+
• iOS 26.0+ deployment target
• Backend server running locally

Backend Setup

Before running the app, you need to set up the backend server. Follow the instructions at:

👉 Sports Hub Launcher

The launcher provides a unified CLI tool to bootstrap the backend services using Podman.

git clone https://github.com/dark-side/sports_hub_launcher.git
cd sports_hub_launcher
chmod +x setup.sh
./setup.sh

Running the App

1. Clone this repository
2. Open Sports-Hub.xcodeproj in Xcode
3. Ensure backend is running at http://127.0.0.1:3002
4. Build and run (⌘R)

🎨 Design Resources

Resource	Link
Figma Prototype	Sports Hub General Prototype
Feature Roadmap	Mobile Application Features List

📁 Project Structure

Sports-Hub/
├── Source/
│   ├── Application/           # App entry point & root navigation
│   │   ├── Sports_HubApp.swift
│   │   ├── AppFlowModel.swift      # Global app state & navigation
│   │   ├── AppRootView.swift
│   │   └── MainAppFlowContentContainerView.swift
│   │
│   ├── Common/                # Shared code across features
│   │   ├── Articles/
│   │   │   ├── Domain/             # Domain models
│   │   │   │   ├── Article.swift
│   │   │   │   └── Comment.swift
│   │   │   └── Data/
│   │   │       ├── DTO/            # Network response models
│   │   │       ├── Repositories/   # Data access layer
│   │   │       └── Services/       # Network services
│   │   ├── UserProfile/
│   │   │   ├── Domain/
│   │   │   └── Data/
│   │   ├── Views/                  # Reusable UI components
│   │   └── NetworkError.swift
│   │
│   ├── Features/              # Feature modules
│   │   ├── Home/              # Home feed & article details
│   │   ├── SideMenu/          # Side navigation menu
│   │   ├── UserProfile/       # Login, SignUp, Logout flows
│   │   ├── Navigation/        # Navigation models & routes
│   │   ├── NBA/               # NBA section (placeholder)
│   │   └── NFL/               # NFL section (placeholder)
│   │
│   └── Utilities/
│       └── AppConfig.swift
│
├── Resources/
│   └── Assets.xcassets/
│
└── Preview Content/           # SwiftUI preview helpers

🏗️ Architecture

Main Entities

Entity	Description
AppFlowModel	Global app state manager handling navigation, side menu, user authentication state, and modal presentations
NavigationModel<Route>	Generic navigation coordinator for each feature flow (Home, NBA, NFL)
UserProfileManager	Manages user authentication state and creates auth-related ViewModels
Article	Domain model representing a sports article
User	Domain model representing authenticated user

Data Flow

View → ViewModel → Repository → NetworkService → API
                       ↓
                    Mapper
                       ↓
                 Domain Model

Key Patterns

Pattern	Implementation
Observation	@Observable macro (Swift 5.9+)
Dependency Injection	Protocol-based repositories
Navigation	NavigationStack with typed routes
State Management	Enum-based view states (idle, loading, loaded, error)
Main Actor Isolation	Project-level SWIFT_DEFAULT_ACTOR_ISOLATION = MainActor

✅ Possible Next Tasks

UI Development

• Develop screens according to Figma prototypes
• Implement NBA and NFL feature screens
• Add pull-to-refresh functionality
• Implement infinite scroll/pagination

Data & Persistence

• Develop cache system (URLCache, custom disk cache)
• Add persistence layer (SwiftData, CoreData, or UserDefaults)
• Implement offline mode support

Localization

• Add String Catalogs for localization
• Support English and Ukrainian languages
• Localize date/number formatters

Architecture Experiments

• Reimplement using TCA (The Composable Architecture)
• Reimplement using MV (Model-View) pattern
• Reimplement using MVVM-C (Coordinator pattern)
• Extract feature modules into Swift Packages

Testing

• Add unit tests for ViewModels
• Add unit tests for Repositories and Mappers
• Add UI tests for critical user flows
• Implement snapshot testing

AI-Assisted Development

• Define Cursor rules (.cursorrules) for code generation context
• Experiment with Claude Code for feature generation
• Create custom prompts for consistent code style

🛠️ Configuration

Build Settings

Setting	Value
Deployment Target	iOS 26.0
Swift Version	5.0
Default Actor Isolation	MainActor
Supported Orientations	Portrait only

Environment Variables

Set API_URL environment variable to override the default backend URL:

# Default: http://127.0.0.1:3002
API_URL=http://your-backend-url

📚 Learning Resources

• SwiftUI Documentation
• Swift Concurrency
• Observation Framework
• NavigationStack

---

Happy coding! 🚀