If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/nalexn/clean-architecture-swiftui shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across all four use cases

• Last commit 10mo ago
• 11 active contributors
• MIT licensed
• CI configured
• Tests present
• ⚠ Slowing — last commit 10mo ago
• ⚠ Concentrated ownership — top contributor handles 78% of recent commits

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live nalexn/clean-architecture-swiftui repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/nalexn/clean-architecture-swiftui.

What it runs against: a local clone of nalexn/clean-architecture-swiftui — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in nalexn/clean-architecture-swiftui | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 329 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of nalexn/clean-architecture-swiftui. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/nalexn/clean-architecture-swiftui.git
#   cd clean-architecture-swiftui
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of nalexn/clean-architecture-swiftui and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "nalexn/clean-architecture-swiftui(\\.git)?\\b" \\
  && ok "origin remote is nalexn/clean-architecture-swiftui" \\
  || miss "origin remote is not nalexn/clean-architecture-swiftui (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "CountriesSwiftUI/Core/App.swift" \\
  && ok "CountriesSwiftUI/Core/App.swift" \\
  || miss "missing critical file: CountriesSwiftUI/Core/App.swift"
test -f "CountriesSwiftUI/DependencyInjection/DIContainer.swift" \\
  && ok "CountriesSwiftUI/DependencyInjection/DIContainer.swift" \\
  || miss "missing critical file: CountriesSwiftUI/DependencyInjection/DIContainer.swift"
test -f "CountriesSwiftUI/Utilities/Store.swift" \\
  && ok "CountriesSwiftUI/Utilities/Store.swift" \\
  || miss "missing critical file: CountriesSwiftUI/Utilities/Store.swift"
test -f "CountriesSwiftUI/Repositories/WebAPI/WebRepository.swift" \\
  && ok "CountriesSwiftUI/Repositories/WebAPI/WebRepository.swift" \\
  || miss "missing critical file: CountriesSwiftUI/Repositories/WebAPI/WebRepository.swift"
test -f "CountriesSwiftUI/Core/AppState.swift" \\
  && ok "CountriesSwiftUI/Core/AppState.swift" \\
  || miss "missing critical file: CountriesSwiftUI/Core/AppState.swift"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 329 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~299d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/nalexn/clean-architecture-swiftui"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

A production-ready SwiftUI reference app demonstrating Clean Architecture principles, built around a countries REST API client (restcountries.com). It showcases modern iOS patterns: async-await networking, SwiftData persistence, Redux-like centralized AppState, programmatic deep-link navigation, and comprehensive unit tests—all without external UI frameworks, relying on vanilla SwiftUI + Combine. Monolith single-app structure: Core/ houses AppState, AppDelegate, deep-linking, and system event handling; DependencyInjection/ holds DIContainer and AppEnvironment for native SwiftUI injection; Interactors/ contain business logic (CountriesInteractor, ImagesInteractor); Repositories/ split into WebAPI/ (async-await networking) and Database/ (SwiftData models); UI/ organized by feature (CountriesList, CountryDetails) with Common shared views.

iOS engineers learning or implementing Clean Architecture in SwiftUI apps; architects designing layered SwiftUI projects; developers building data-driven list-detail apps needing examples of dependency injection, state management, and testable UI patterns.

Actively maintained and production-grade. The repo received a major revamp in end-2024 to adopt modern iOS stack (SwiftData, async-await). It has full test coverage including UI tests via ViewInspector, CI/CD via Travis CI, and codecov integration. Multiple articles and MVVM branch variant exist, indicating maturity and intentional design.

Low risk. Single maintainer (nalexn) but the codebase is well-documented with blog articles and has been stable across iOS versions. No unusual dependency sprawl visible—core dependencies are minimal (SwiftUI, Combine, SwiftData all first-party Apple frameworks). Main risk is iOS version constraints if you're targeting older devices, but the modern 2024 revamp suggests forward-compatibility focus.

The repo was comprehensively updated at end-of-2024 to adopt modern iOS stack: SwiftData replaced previous persistence, async-await replaced Combine networking layers, and the architecture was refined. No open PRs or active roadmap visible in the snippet, but the MVVM branch exists as a parallel reference implementation. The project serves primarily as a reference/learning artifact rather than an actively-developed app.

Clone the repo, open CountriesSwiftUI.xcodeproj in Xcode 15+, and run the CountriesSwiftUI scheme on an iOS 15+ simulator or device. No external dependency managers (CocoaPods/SPM packages) are apparent from the file structure; all dependencies are first-party Apple frameworks.

Daily commands: Open CountriesSwiftUI.xcodeproj → select CountriesSwiftUI scheme → Cmd+R to build and run on simulator. No build script, environment setup, or external service configuration required beyond Xcode 15+.

• CountriesSwiftUI/Core/App.swift — SwiftUI app entry point that initializes the dependency injection container and sets up the root view hierarchy.
• CountriesSwiftUI/DependencyInjection/DIContainer.swift — Core dependency injection container that manages all service instantiation and lifetime; essential for understanding how the app wires together repositories, interactors, and views.
• CountriesSwiftUI/Utilities/Store.swift — Custom state management and subscription mechanism that replaces traditional ViewModel; critical for understanding data flow and reactive binding.
• CountriesSwiftUI/Repositories/WebAPI/WebRepository.swift — Base networking abstraction that all API repositories inherit from; defines the HTTP request/response protocol used throughout.
• CountriesSwiftUI/Core/AppState.swift — Global application state container that coordinates all feature states and actions; the single source of truth for app-wide data.
• CountriesSwiftUI/Interactors/CountriesInteractor.swift — Business logic layer that orchestrates repository calls and state mutations; demonstrates the clean architecture interactor pattern.
• CountriesSwiftUI/UI/CountriesList/CountriesListView.swift — Primary UI view demonstrating how SwiftUI views consume interactors and react to state changes without traditional ViewModels.

Add a new country API endpoint

1. Create a new method in CountriesSwiftUI/Repositories/WebAPI/CountriesWebRepository.swift that extends the existing WebRepository base class with your endpoint (CountriesSwiftUI/Repositories/WebAPI/CountriesWebRepository.swift)
2. Add corresponding action and state property to CountriesSwiftUI/Core/AppState.swift for the new data (CountriesSwiftUI/Core/AppState.swift)
3. Create a public method in CountriesSwiftUI/Interactors/CountriesInteractor.swift that calls the repository and updates AppState via the dispatch callback (CountriesSwiftUI/Interactors/CountriesInteractor.swift)
4. Add unit tests in UnitTests/Repositories/CountriesWebRepositoryTests.swift with mocked responses using RequestMocking.swift (UnitTests/Repositories/CountriesWebRepositoryTests.swift)

Add a new feature UI screen

1. Create a new feature state struct in CountriesSwiftUI/Core/AppState.swift to hold screen-specific state (CountriesSwiftUI/Core/AppState.swift)
2. Create a new SwiftUI View file in CountriesSwiftUI/UI/ that uses @EnvironmentObject to access AppState and calls interactor methods on user actions (CountriesSwiftUI/UI/RootViewModifier.swift)
3. Update CountriesSwiftUI/Core/DeepLinksHandler.swift to handle navigation to the new screen if deep-linkable (CountriesSwiftUI/Core/DeepLinksHandler.swift)
4. Add UI tests in UnitTests/UI/ folder using mocked interactors from UnitTests/Mocks/MockedInteractors.swift (UnitTests/UI/CountriesListTests.swift)

Add a new repository for a different data source

1. Create a new file in CountriesSwiftUI/Repositories/Database/ or WebAPI/ inheriting from WebRepository (for APIs) or implementing a custom protocol for database (CountriesSwiftUI/Repositories/Database/CountriesDBRepository.swift)
2. Define your data model in CountriesSwiftUI/Repositories/Models/ with appropriate persistence annotations (SwiftData @Model, Codable) (CountriesSwiftUI/Repositories/Models/Country.swift)
3. Register the repository in CountriesSwiftUI/DependencyInjection/DIContainer.swift as a singleton or factory depending on state requirements (CountriesSwiftUI/DependencyInjection/DIContainer.swift)
4. Create mocks in UnitTests/Mocks/MockedWebRepositories.swift or MockedDBRepositories.swift for testing dependent interactors (UnitTests/Mocks/MockedWebRepositories.swift)

Implement async data loading with proper state management

1. Use the Loadable<T> enum in your AppState to represent loading, loaded, and failure states for async operations (CountriesSwiftUI/Utilities/Loadable.swift)
2. In your interactor, call the repository method and dispatch state changes for .loading -> .loaded/.failed states via the AppState dispatch callback (CountriesSwiftUI/Interactors/CountriesInteractor.swift)
3. In your SwiftUI view, use @EnvironmentObject to observe AppState and conditionally render ErrorView, progress indicator, or content based on the Loadable state (CountriesSwiftUI/UI/CountriesList/CountriesListView.swift)

• SwiftUI — Modern declarative UI framework for iOS/macOS with tight Combine integration for reactive state binding
• Combine — Apple's reactive framework for handling asynchronous events and state changes without third-party dependencies
• SwiftData — Modern local persistence framework (iOS 17+) replacing Core Data; simpler syntax and better Swift integration
• Clean Architecture + Repository Pattern — Separates business logic (interactors), data access (repositories), and UI (views) for testability and maintainability
• undefined — undefined

No hidden environment variables or external service setup required—restcountries.com API is public and free. SwiftData requires iOS 17+; if supporting older OS versions, check model container initialization in Repositories/Database/ModelContainer.swift. The .swiftlint.yml config expects SwiftLint to be installed for CI; local builds work without it but CI/pre-commit checks may fail. Deep link handling in Core/DeepLinksHandler.swift requires proper AppDelegate integration—changes to entry point logic could break navigation.

• Clean Architecture Layers (Presentation/Business Logic/Data) — This repo is a canonical example of Clean Architecture applied to SwiftUI; understanding the separation between Views, Interactors, and Repositories is the foundation of the entire design.
• Redux-like Centralized State Management — AppState.swift is the single source of truth (like Redux store), avoiding scattered @State across views; critical for testability and predictability in complex apps.
• Programmatic Navigation with Deep Linking — DeepLinksHandler chains deep links (e.g., from push notifications) through AppState to drive navigation; prevents tight coupling between navigation logic and UI.
• Protocol-Based Repository Pattern — WebRepository base class and CountriesWebRepository/CountriesDBRepository implementations decouple data sources from business logic, enabling easy mocking in tests.
• Async-Await Networking — Modern async-await replaces older Combine-based networking in this 2024 revision; essential for clean error handling and sequential API call chaining.
• SwiftData Persistence — Replaces Core Data in this 2024 update; demonstrates modern Apple framework for on-device data persistence with model containers and query predicates.
• Native SwiftUI Dependency Injection — AppEnvironment uses @Environment to inject Interactors and Repositories directly into the view hierarchy without external DI frameworks; lightweight and Xcode-integrated.
• Separation of Concerns in Software Design — Core principle motivating the entire architecture; keeping Presentation, Business Logic, and Data layers separate prevents monolithic view logic and enables independent testing.

• nalexn/uikit-swiftui — Sibling project by the same author demonstrating authentication state handling using locks-and-keys principle in a UIKit-SwiftUI hybrid app.
• nalexn/ViewInspector — Used in this repo's test suite for UI testing; essential library for testing SwiftUI views without XCTest framework constraints.
• pointfreeco/swift-composable-architecture — More sophisticated TCA alternative to the AppState pattern shown here; relevant for engineers exploring Redux-style state management in SwiftUI at scale.
• raywenderlich/swift-style-guide — Pairs with the .swiftlint.yml config in this repo; establishes Swift code style conventions the project enforces.

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add unit tests for WebRepository and HTTP error handling

The file CountriesSwiftUI/Repositories/WebAPI/WebRepository.swift is a critical base class for all API communication, but there are no corresponding test files in UnitTests/Mocks for testing HTTP error scenarios, request/response handling, and retry logic. This is a high-value addition since all three web repositories (CountriesWebRepository, ImagesWebRepository, PushTokenWebRepository) depend on this base class.

• [ ] Create UnitTests/Mocks/Repositories/WebRepositoryTests.swift to test WebRepository HTTP methods
• [ ] Add tests for URLSession error handling, timeouts, and network failures
• [ ] Test response decoding with invalid JSON and malformed API responses
• [ ] Verify retry logic and request cancellation behavior
• [ ] Add mock URLSession implementation if not already present in test infrastructure

Add GitHub Actions workflow for SwiftLint and Build Validation

The repo includes .swiftlint.yml configuration file but no corresponding GitHub Actions workflow to enforce linting on PRs. Currently .travis.yml is present but Travis CI is deprecated. Adding a modern GitHub Actions workflow will catch code style violations early and prevent merge of non-compliant code.

• [ ] Create .github/workflows/swiftlint.yml to run SwiftLint on every push and PR
• [ ] Create .github/workflows/build.yml to validate that the Xcode project builds successfully
• [ ] Configure both workflows to block PRs if linting fails or build fails
• [ ] Test workflows locally using act or by pushing to a branch
• [ ] Update README.md to document the CI/CD setup

Add integration tests for CountriesInteractor data flow and caching

The CountriesInteractor is the core business logic orchestrator that combines database and web repositories. Currently only basic mock tests exist in UnitTests/Mocks/Interactors/CountriesInteractorTests.swift, but there are no integration tests verifying the complete flow: cache miss → API fetch → database persist → cached read. This is critical for validating the data persistence strategy using SwiftData.

• [ ] Create UnitTests/Interactors/CountriesInteractorIntegrationTests.swift
• [ ] Add test for initial data fetch from API and storage in CountriesDBRepository
• [ ] Add test for subsequent reads returning cached data without API call
• [ ] Add test for cache invalidation and refresh scenarios
• [ ] Verify SwiftData model container is properly initialized in test environment (reference CountriesSwiftUI/Repositories/Database/ModelContainer.swift)
• [ ] Test error scenarios where API fails but cache has stale data

• Add unit test coverage for ImagesWebRepository.swift and ImagesInteractor.swift—currently only the core countries flow has comprehensive tests visible; image fetching tests are missing.
• Expand MockedData.swift with more Country fixtures and edge cases (countries with no currencies, special characters in names, etc.) to improve test comprehensiveness and serve as examples for new contributors.
• Document the programmatic navigation flow: create a guide in README or wiki explaining how DeepLinksHandler.swift chains with AppState and view .navigationDestination modifiers, with a concrete example of adding a new deep link route.

The codebase demonstrates good architectural practices with clean separation of concerns, proper dependency injection, and comprehensive unit testing. However, there are notable security gaps primarily around API communication security, local data protection, and input validation. The application lacks certificate pinning, data encryption at rest, and comprehensive input validation for external API responses. These are typical concerns for mobile applications that interact with external APIs and store local data. No critical vulnerabilities were identified, but implementing the recommended mitigations would significantly improve the security posture, particularly for handling sensitive data and protecting against network-based attacks.

• Medium · External API Dependency on restcountries.com — CountriesSwiftUI/Repositories/WebAPI/CountriesWebRepository.swift. The application relies on an external REST API (restcountries.com) without apparent validation of SSL/TLS certificates or request signing. If the API endpoint is compromised or if man-in-the-middle attacks occur, malicious country data could be injected into the application. Fix: Implement certificate pinning for the restcountries.com API, validate SSL/TLS certificates, and consider implementing request integrity checks. Use URLSessionDelegate to enforce security policies.
• Medium · Potential Unsafe Deserialization — CountriesSwiftUI/Repositories/WebAPI/WebRepository.swift, CountriesSwiftUI/Repositories/Models/. The application uses Codable to deserialize JSON from external APIs. Without proper validation, malicious JSON payloads could lead to application crashes or unexpected behavior. No visible schema validation or size limits are apparent. Fix: Implement input validation on deserialized objects, set maximum size limits for API responses, use try-catch blocks with proper error handling, and validate all nested objects.
• Medium · SwiftData Persistence Without Encryption — CountriesSwiftUI/Repositories/Database/ModelContainer.swift, CountriesSwiftUI/Repositories/Database/CountriesDBRepository.swift. The application uses SwiftData for local persistence (as indicated by ModelContainer.swift). There is no evidence of data encryption at rest. Sensitive country data or user information could be accessed if the device is compromised. Fix: Enable file protection on SwiftData containers using FileProtectionType.complete, or implement field-level encryption for sensitive data. Use Keychain for storing sensitive credentials.
• Low · No Apparent API Rate Limiting — CountriesSwiftUI/Repositories/WebAPI/WebRepository.swift. The WebAPI repositories do not show rate limiting implementation, which could allow excessive API calls leading to service disruption or DoS vulnerabilities. Fix: Implement client-side rate limiting with request throttling and backoff strategies. Monitor API usage and implement local caching to reduce unnecessary requests.
• Low · Missing Security Headers Documentation — CountriesSwiftUI/Repositories/WebAPI/WebRepository.swift. No evidence of custom security headers configuration or validation of API responses for security-related headers (CSP, HSTS, etc.). Fix: Validate security headers in HTTP responses from the API. Implement URLSessionConfiguration with appropriate security settings.
• Low · Potential Information Disclosure via Error Messages — CountriesSwiftUI/UI/Common/ErrorView.swift. ErrorView.swift may display detailed error information to users that could reveal internal implementation details or API structure. Fix: Implement sanitized error messages for end users while logging detailed errors server-side. Avoid exposing stack traces or technical details in UI.
• Low · No Visible HTTPS Enforcement — CountriesSwiftUI/Repositories/WebAPI/WebRepository.swift. The codebase does not show explicit enforcement of HTTPS-only connections for all network requests. Fix: Set URLSessionConfiguration to enforce HTTPS only by implementing NSExceptionDomains empty and allowsArbitraryLoads set to false in Info.plist or URLSessionConfiguration.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.