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/sergdort/ModernCleanArchitectureSwiftUI 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.

AVOID — Stale and unlicensed — last commit 1y ago

• 22+ active contributors
• CI configured
• ⚠ Stale — last commit 1y ago
• ⚠ Concentrated ownership — top contributor handles 58% of recent commits
• ⚠ No license — legally unclear to depend on
• ⚠ No test directory detected

_{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 sergdort/ModernCleanArchitectureSwiftUI repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/sergdort/ModernCleanArchitectureSwiftUI.

What it runs against: a local clone of sergdort/ModernCleanArchitectureSwiftUI — 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 sergdort/ModernCleanArchitectureSwiftUI | Confirms the artifact applies here, not a fork | | 2 | Default branch master exists | Catches branch renames | | 3 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 4 | Last commit ≤ 482 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of sergdort/ModernCleanArchitectureSwiftUI. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/sergdort/ModernCleanArchitectureSwiftUI.git
#   cd ModernCleanArchitectureSwiftUI
#
# 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 sergdort/ModernCleanArchitectureSwiftUI and re-run."
  exit 2
fi

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

# 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 "Projects/Example/Sources/ModernCleanArchitectureApp.swift" \\
  && ok "Projects/Example/Sources/ModernCleanArchitectureApp.swift" \\
  || miss "missing critical file: Projects/Example/Sources/ModernCleanArchitectureApp.swift"
test -f "Projects/Example/Sources/Navigation/AppCoordinator.swift" \\
  && ok "Projects/Example/Sources/Navigation/AppCoordinator.swift" \\
  || miss "missing critical file: Projects/Example/Sources/Navigation/AppCoordinator.swift"
test -f "Projects/Domain/MoviesDomain/Gateway/DiscoverMoviesGateway.swift" \\
  && ok "Projects/Domain/MoviesDomain/Gateway/DiscoverMoviesGateway.swift" \\
  || miss "missing critical file: Projects/Domain/MoviesDomain/Gateway/DiscoverMoviesGateway.swift"
test -f "Projects/Core/HTTPClient/HTTPClient.swift" \\
  && ok "Projects/Core/HTTPClient/HTTPClient.swift" \\
  || miss "missing critical file: Projects/Core/HTTPClient/HTTPClient.swift"
test -f "Projects/Domain/AnimeDomain/UseCases/DiscoverAnimeUseCase.swift" \\
  && ok "Projects/Domain/AnimeDomain/UseCases/DiscoverAnimeUseCase.swift" \\
  || miss "missing critical file: Projects/Domain/AnimeDomain/UseCases/DiscoverAnimeUseCase.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 482 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~452d)"
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/sergdort/ModernCleanArchitectureSwiftUI"
  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-grade Swift example demonstrating Domain-Driven Design (DDD) and Clean Architecture applied to iOS apps using SwiftUI. It's a dual-API app (TMDB Movies + AniList Anime) showcasing modularized feature development with inverted dependencies, custom Apollo extensions, and SwiftData integration across multiple domains. Tuist-managed monorepo (Projects/ root) with strict layering: Domain/ contains business logic (AnimeDomain/, MoviesDomain/ with UseCases, Entities, Gateways); Core/ houses shared infrastructure (HTTPClient, FileCache, SwiftDataHelpers, custom DependenciesMacro); Features/ (inferred, not fully listed) implements UI screens invoking domain UseCases. Each domain (Anime, Movies) is independently modularized with Gateway/Repository pattern for data access.

iOS engineers learning to structure large apps with DDD principles; architects designing modular SwiftUI codebases; teams migrating from monolithic iOS projects to domain-driven modules with clear separation of concerns.

Actively maintained reference implementation (not a production library). Uses Tuist for project generation, has CI/CD via GitHub Actions (ios.yml workflow), minimal external dependency count (Swift-focused), and demonstrates patterns from two foundational architecture books. Verdict: actively developed learning resource, production-ready as architectural reference but not a shipped product.

Single-maintainer risk (author: sergdort). No visible open issues/PRs data, but appears to be a reference repo rather than a library consumed by others—low risk for version churn. Dependency risk is low: hand-written HTTP client (Projects/Core/HTTPClient), custom Apollo extensions (Projects/Core/ApolloExtensions), minimal third-party deps. Breaking changes unlikely since scope is teaching, not API stability.

No recent commit metadata provided in file listing, but project structure is stable and complete: GraphQL (Apollo) integration for Anime, REST (TMDB) for Movies, custom macro-based dependency injection (DependenciesMacro/InvertedDependency), and SwiftData persistence layer are all implemented. CI workflow exists (ios.yml) indicating active validation.

Clone, install Tuist, then run: git clone https://github.com/sergdort/ModernCleanArchitectureSwiftUI.git && cd ModernCleanArchitectureSwiftUI && tuist install && tuist generate && open ModernCleanArchitectureSwiftUI.xcworkspace

Daily commands: tuist generate creates xcworkspace; build/run via Xcode or tuist build command. No npm/brew dependencies visible—pure Swift toolchain after Tuist install.

• Projects/Example/Sources/ModernCleanArchitectureApp.swift — Application entry point and root coordinator setup; defines the dependency injection bootstrapping for the entire app
• Projects/Example/Sources/Navigation/AppCoordinator.swift — Main navigation coordinator that orchestrates all feature modules (Movies, Anime, Watchlist); critical for understanding routing architecture
• Projects/Domain/MoviesDomain/Gateway/DiscoverMoviesGateway.swift — Core domain gateway abstraction defining the contract for movies data access; demonstrates the Domain-Driven Design pattern used throughout
• Projects/Core/HTTPClient/HTTPClient.swift — Foundational HTTP networking layer used by all data repositories; single point of network abstraction across features
• Projects/Domain/AnimeDomain/UseCases/DiscoverAnimeUseCase.swift — Exemplar use case implementation showing how domain logic is organized and injected into features
• Projects/Core/DependenciesMacros/InvertedDependency.swift — Macro-based dependency injection annotation; enables the inverted dependency pattern that decouples domain from infrastructure
• Projects/Features/Movies/MovieDetails/MovieDetailViewModel.swift — Feature-layer view model demonstrating SwiftUI integration with domain use cases and state management

• Domain Layer (Use Cases + Gateways + Entities) (Swift language primitives only; no iOS frameworks) — Pure business logic independent of frameworks; defines contracts via gateway protocols that infrastructure must implement
  • Failure mode: Invalid business rules or entity mutations; domain errors propagate to ViewModels as failure states
• Infrastructure Layer (HTTPClient, FileCache, SwiftDataHelpers) (URLSession, Foundation FileManager, SwiftData) — Implements gateway contracts; handles networking, caching, and persistence
  • Failure mode: Network timeouts, I/O errors, or cache misses; caught in repository implementations and transformed to domain errors
• Feature ViewModels — undefined

Add a new Movie Use Case

1. Create domain entity if needed (Projects/Domain/MoviesDomain/Entities/[EntityName].swift)
2. Create gateway interface in domain (defines data contract) (Projects/Domain/MoviesDomain/Gateway/[UseCaseName]Gateway.swift)
3. Create use case in domain layer (Projects/Domain/MoviesDomain/UseCases/[UseCaseName]UseCase.swift)
4. Add dependency injection extension in Example app to wire concrete implementation (Projects/Example/Sources/Dependencies+App/[UseCaseName]UseCase+App.swift)
5. Create ViewModel in feature layer to expose use case to SwiftUI (Projects/Features/Movies/[FeatureName]/[FeatureName]ViewModel.swift)

Add a new API endpoint via HTTPClient

1. Define request/response entities in domain (e.g., MovieDetail.swift) (Projects/Domain/MoviesDomain/Entities/[EntityName].swift)
2. Create Resource conforming to HTTPClient protocol (Projects/Core/HTTPClient/Resource.swift)
3. Implement gateway with HTTPClient call in infrastructure (wired via DI macro) (Projects/Example/Sources/Dependencies+App/[Gateway]Gateway+App.swift)

Add a new SwiftUI feature module

1. Create feature coordinator for navigation (Projects/Features/[FeatureName]/[FeatureName]Coordinator.swift)
2. Create SwiftUI View (Projects/Features/[FeatureName]/[ViewName]/[ViewName]View.swift)
3. Create ViewModel wrapping domain use cases (Projects/Features/[FeatureName]/[ViewName]/[ViewName]ViewModel.swift)
4. Integrate into AppCoordinator navigation (Projects/Example/Sources/Navigation/AppCoordinator.swift)

• SwiftUI — Modern iOS declarative UI framework; primary presentation layer for views
• Domain-Driven Design (DDD) with Gateway pattern — Separates business logic (Domain) from infrastructure; enables independent testing and framework-agnostic domain code
• Swift Macros (@InvertedDependency) — Enables compile-time dependency injection with inverted control; domain depends only on protocol abstractions, not concrete implementations
• Apollo GraphQL (for Anime API) + REST HTTPClient (for Movies API) — Dual API support: GraphQL for flexible anime data, REST for traditional movie database; demonstrates multi-protocol architecture
• SwiftData for persistence — Modern Apple data persistence framework; used for local caching and watchlist storage

• Gateway abstraction layer between domain and infrastructure

  • Why: Enforces domain independence and testability
  • Consequence: Additional abstraction layer adds slight overhead; requires explicit dependency wiring in Example app

• Feature modules in separate folders (Movies, Anime, Watchlist) with individual coordinators

  • Why: Enables independent feature development and reduces coupling
  • Consequence: Requires central AppCoordinator to orchestrate cross-feature navigation; some shared state must cross module boundaries

• Use macros for dependency injection instead of service locator

  • Why: Compile-time safety and eliminates runtime reflection
  • Consequence: Requires macro definitions; dependency resolution code must be written explicitly in Dependencies+App extensions

• Does not implement authentication or user session management
• Does not include real-time synchronization or WebSocket support
• Does not provide offline-first architecture (uses simple file cache, not full sync engine)
• Not a production app; example focuses on architecture patterns, not complete feature parity

Tuist version lock: Project uses .mise.toml for tool versioning; requires Tuist CLI installed and matching version before tuist generate works. Apollo code generation: Anime domain expects Apollo schema; TMDB Movies uses custom REST HTTPClient—mixing patterns, ensure correct API type per domain. SwiftData ModelContext: SwiftDataHelpers uses @Environment(ContextStore); Features must inject ContextStore into SwiftUI views correctly or persistence fails. Macro plugin build: DependenciesMacro requires Swift 5.9+ and macro support enabled in build phases; older Xcode versions will fail silently.

• Domain-Driven Design (DDD) — This entire repo is built around DDD principles (Entities, UseCases, Gateways, Bounded Contexts); understanding Ubiquitous Language, Aggregates, and Value Objects is foundational to navigating the codebase
• Gateway / Repository Pattern — Data access in this repo is abstracted via Gateway protocols (DiscoverMoviesGateway.swift); this decouples domain logic from infrastructure, allowing easy swapping of REST/GraphQL/database implementations
• Inverted Dependency Injection — Projects/Core/DependenciesMacros implements compile-time DI via Swift macros; this inverts the typical service-locator pattern, making dependencies explicit and type-safe at compile time
• UseCase / Interactor Pattern — Core application logic lives in UseCases (e.g., DiscoverMoviesUseCase.swift, AnimeDetailUseCase.swift); understanding how UseCases orchestrate domain entities and gateway calls is key to extending features
• Bounded Contexts (DDD) — AnimeDomain and MoviesDomain are separate bounded contexts with their own entities and gateways; this repo demonstrates how to model and isolate distinct business domains to avoid coupling
• Protocol-Based Abstraction — Gateways, HTTPClient, URLSessionProtocol, and DataStore are all protocol-driven; this pattern enables testability via mocks and swappable implementations without changing domain code
• Swift Macros (Compile-Time Code Generation) — InvertedDependencyMacro.swift generates dependency registration code at compile time; this is a modern Swift 5.9+ technique replacing runtime reflection, reducing boilerplate and enabling static type checking

• pointfreeco/swift-composable-architecture — Alternative DDD-inspired architecture using reducers and effects; shows state management approach vs. this repo's UseCase pattern
• nalexn/clean-architecture-swiftui — Similar Clean Architecture reference for SwiftUI; compares presenter/interactor layer organization with this repo's UseCase/Gateway split
• Carthage/Carthage — Dependency manager alternative to native SPM; this repo uses Tuist, but Carthage is relevant for modular iOS projects
• realm/realm-swift — Persistence alternative; this repo uses SwiftData, but Realm is a common choice for domain-layer data abstraction
• apollographql/apollo-ios — Official Apollo iOS client used in AnimeDomain; understanding its generated code and CachePolicy is essential for Anime feature modifications

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 Core/HTTPClient module

The HTTPClient module (HTTPClient.swift, HTTPMethod.swift, Resource.swift, URLComponentsInterceptor.swift) lacks visible test coverage. This is critical infrastructure code that handles all network requests. Adding comprehensive unit tests would demonstrate testing patterns for DDD-based architecture and provide confidence in the HTTP abstraction layer.

• [ ] Create Projects/Core/HTTPClient/Tests directory with HTTPClientTests.swift
• [ ] Add tests for HTTPClient.swift covering different HTTPMethod cases and request building
• [ ] Add tests for URLComponentsInterceptor.swift verifying query parameter and path manipulation
• [ ] Add tests for Resource.swift validating generic resource creation and encoding/decoding
• [ ] Add mock URLSessionProtocol implementation in tests for network isolation

Add integration tests for Domain layer UseCases

The Domain layer contains multiple UseCases (DiscoverMoviesUseCase, MovieDetailUseCase, DiscoverAnimeUseCase, etc.) but no visible test files. These are core business logic layers that should have integration tests demonstrating how they orchestrate repositories and gateways. This would serve as both validation and documentation.

• [ ] Create Projects/Domain/MoviesDomain/UseCases/Tests directory
• [ ] Add DiscoverMoviesUseCaseTests.swift with mock DiscoverMoviesGateway and DiscoverMoviesRepository
• [ ] Add MovieDetailUseCaseTests.swift testing error handling and data transformation
• [ ] Create Projects/Domain/AnimeDomain/UseCases/Tests directory with similar coverage
• [ ] Add DiscoverAnimeUseCaseTests.swift and AnimeDetailUseCaseTests.swift

Add GitHub Actions workflow for SwiftUI Preview snapshots

The repo contains .github/workflows/ios.yml but likely only covers build/test. Given this is a SwiftUI-focused example architecture with visual gifs in the README, adding a snapshot testing workflow would ensure UI consistency and provide visual regression detection. This is especially valuable for demonstrating modern SwiftUI testing patterns in a DDD context.

• [ ] Extend .github/workflows/ios.yml or create ios-snapshots.yml with SwiftUI snapshot testing step
• [ ] Add dependencies for snapshot testing library (e.g., swift-snapshot-testing) to Projects/Example/Project.swift
• [ ] Create snapshot tests in Projects/Example/Tests for key screens (MoviesList, MovieDetail, AnimeList, MyLists views)
• [ ] Configure workflow to fail on snapshot mismatches and generate diff reports
• [ ] Document snapshot testing approach in README.md for contributors

• Add comprehensive unit tests for Projects/Core/HTTPClient/HTTPClient.swift—currently no test files visible; create URLSessionProtocol mock tests covering success/failure/timeout paths
• Document the Gateway/Repository distinction: create a markdown guide explaining when to use DiscoverMoviesGateway vs. DicoverMoviesRepository (typo in filename suggests confusion); include a diagram
• Extend FileCache.swift with TTL (time-to-live) support and write integration tests; cache keys currently have no expiration policy

This modern iOS clean architecture project demonstrates good structural practices with proper separation of concerns. However, several security considerations need attention: API credential management requires hardening with secure storage mechanisms, network security headers should be explicitly configured, and input validation from external APIs should be formalized. The codebase lacks visible security-focused documentation and configuration files (.env examples, security guidelines). No critical vulnerabilities were detected, but medium-priority improvements around API key handling and network security configuration should be addressed before production deployment. The modular architecture is well-suited for implementing security controls at each layer.

• Medium · Potential API Key Exposure in HTTPClient — Projects/Core/HTTPClient/HTTPClient.swift, Projects/Core/HTTPClient/URLComponentsInterceptor.swift. The HTTPClient component handles API requests to external services (TheMovieDB and AniList). Without visible authentication abstraction, API keys may be hardcoded or improperly managed. The file structure shows HTTPClient.swift and URLComponentsInterceptor.swift, but the actual implementation details are not visible. Fix: Implement secure credential management using Keychain for storing API keys. Use environment-based configuration for different build schemes. Avoid committing API keys to version control. Consider using a dedicated secrets management solution.
• Medium · Missing Security Headers Configuration — Projects/Core/HTTPClient/URLSessionProtocol.swift. The codebase implements network communication but there is no visible configuration for security headers (Content-Security-Policy, X-Frame-Options, etc.) in the URLSessionProtocol or HTTPClient implementation. Fix: Implement security headers in network request interceptors. Add certificate pinning for API communications. Validate SSL/TLS certificates properly.
• Low · SwiftData Integration Security Considerations — Projects/Core/SwiftDataHelpers/DataStore.swift, Projects/Core/SwiftDataHelpers/ContextStore.swift. The codebase uses SwiftData for local persistence (DataStore.swift, ContextStore.swift). While SwiftData provides some protection, there's no visible indication of encryption for sensitive user data stored locally. Fix: Ensure sensitive data (watchlists, user preferences) is encrypted at rest. Implement proper access controls for SwiftData containers. Use FileProtection classes appropriately.
• Low · CancellableHolder Pattern - Potential Memory Management Risk — Projects/Core/ApolloExtensions/CancellableHolder.swift. The CancellableHolder.swift utility for managing cancellable operations may introduce memory leaks if not properly implemented, especially with circular references in async operations. Fix: Verify CancellableHolder uses weak references appropriately. Implement proper cleanup in deinit. Use Swift's built-in Combine framework cancellation mechanisms where applicable.
• Low · No Visible Input Validation Framework — Projects/Domain/MoviesDomain/UseCases/, Projects/Domain/AnimeDomain/UseCases/. The UseCases and Repositories handle data from external APIs but there's no visible input validation or sanitization framework to prevent injection attacks or malformed data processing. Fix: Implement input validation for all data received from external APIs. Validate data types, ranges, and formats. Use Codable with strict decoding strategies. Sanitize data before using in UI rendering.
• Low · Missing Error Handling for Network Errors — Projects/Core/ApolloExtensions/NoDataError.swift. The NoDataError.swift and error handling patterns may not comprehensively cover network security errors such as certificate validation failures or man-in-the-middle scenarios. Fix: Implement comprehensive error handling for network security issues. Distinguish between network errors, validation errors, and business logic errors. Never expose raw error details to users.

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.