Explore

The Explore module is the content discovery screen where users browse the full content catalog. Unlike the Home Screen, which shows a personalized feed of recommended content, Explore provides structured browsing through categories, subcategories, facilitators, and tags.

Explore has two operational modes controlled by feature flags:

Like all core content modules, Explore's screens live in the Core package and its coordinator lives in the Client package. For the underlying patterns, see:

• Coordinator Pattern for the coordinator hierarchy and deep link routing
• Communication Patterns for Combine publishers and delegate patterns
• Design Token System for how screen config values flow from Figma exports to runtime theming

Activation

Explore is activated by including .explore in the customer app's tab selection:

func makeTabItems() -> [TabItem] {
    [.showcase, .explore, .library, .journeys, .profile]
}

The view type is determined automatically at coordinator creation time based on feature flags:

private func createExploreCoordinator() -> Coordinator {
    var exploreType: ExploreViewType = .generic
    if !config.flagManager.isActive(flag: .isLightVersion) &&
       config.flagManager.isActive(flag: .exploreEnabled) {
        exploreType = .custom
    }

    let exploreCoordinator = ExploreCoordinator(
        config: config,
        timerModuleInterface: timerModuleInterface,
        type: exploreType)
    exploreCoordinator.start()
    addChildCoordinator(exploreCoordinator, flow: .explore)
    return exploreCoordinator
}

Architecture

Explore spans three packages in the Bricks dependency graph:

YoullNetwork
  └── GenericExploreService / ExploreService    ← GraphQL queries
       │
Core   │
  ├── ExploreFeedViewController                 ← UIViewController hosting SwiftUI
  ├── ExploreFeedViewModel (228 lines)          ← Data + navigation delegates
  ├── ExploreFeedDataProvider (192 lines)        ← Pagination + state machine
  ├── ContentItem                               ← Shared content model
  ├── Tag / ExploreTag                          ← Tag models
  ├── CategoryViewController + ViewModel + View  ← Category details
  ├── SubcategoryViewController + ViewModel + View ← Subcategory details
  └── Facilitator screens                        ← Facilitator details + content list
       │
Client │
  └── ExploreCoordinator (218 lines)            ← Navigation + mode selection

ExploreCoordinator

ExploreCoordinator is 218 lines, significantly simpler than HomeCoordinator's 1,146 lines. It manages the Explore tab's navigation and handles the dual view type logic.

The coordinator receives one optional module interface:

• TimerModuleInterface: if injected, the Explore screen can show a timer button and navigate to timer screens

On start(), the coordinator branches based on ExploreViewType:

enum ExploreViewType {
    case generic    // Tag-based content grid
    case custom     // Home-like sectioned feed
}

• Generic: calls createExploreFeedController() which creates ExploreFeedViewController with ExploreFeedViewModel
• Custom: calls createHomeController() which creates HomeViewController with HomeViewModel configured as isUsedForExploreFeed: true

ExploreFeedViewController

ExploreFeedViewController (169 lines) is a UIViewController that hosts a SwiftUI view (ExploreFeedView). It uses ExploreBaseView as its root view, which provides the navigation bar, and embeds the SwiftUI content grid below.

ExploreFeedViewModel

ExploreFeedViewModel (228 lines) manages the generic Explore feed. It holds:

• ExploreFeedDataProvider for data loading and pagination
• TagsBarDataProvider for tag selection state
• screenConfig: ExploreFeedScreenConfig for visual configuration

The ViewModel communicates user actions to the coordinator through the ExploreFeedDelegate protocol.

View Types

Generic Mode

The default mode shows a tag-filtered content grid.

Tags bar. A horizontal scrollable bar at the top displays available tags. When the user selects a tag, the content grid filters to show only items matching that tag. The .all tag shows all categories. Tags are loaded via ExploreTagsAPI.getExploreTags() and cached in Settings.exploreTags (UserDefaults) for offline display.

Content grid. Below the tags bar, a grid displays ContentItem objects. Each item can be a category, subcategory, or session. Items show a thumbnail, title, lock status (for subscription-gated content), and viewed percentage.

Pagination. The data provider uses offset-based pagination. When the user scrolls near the bottom, ExploreFeedDataProvider requests the next page. New items are deduplicated against existing items to prevent duplicates during rapid scrolling.

State machine. The data provider follows a state pattern:

Custom Mode

When exploreEnabled is active and isLightVersion is not, Explore uses the same HomeViewModel that powers the Home Screen (v1). The coordinator creates a HomeViewController with isUsedForExploreFeed: true, which tells the ViewModel to fetch data via ExploreService instead of HomeFeedService.

The custom mode provides a home-like sectioned feed with featured content, tagged collections, and promotional sections. Data is fetched via FeedAPI.getExploreFeedSections() and cached in Core Data through DataApiCache.

For details on the feed section types, data flow, and configuration available in custom mode, see the Home Screen documentation.

Screens

Explore Feed

Category Details

When a user taps a category in the Explore feed, the coordinator pushes the category details screen. This screen shows a grid of subcategories within that category.

Subcategory Details

Tapping a subcategory shows its sessions. This screen also displays user reviews with star ratings.

Facilitators

Facilitator screens show instructor/teacher profiles and their content. There are two screens: a details view and a content list.

Data Flow

Generic Mode

User opens Explore tab
    │
    ▼
ExploreFeedDataProvider.loadData()
    │
    ├──▸ TagsBarDataProvider loads tags
    │    ├── ExploreTagsAPI.getExploreTags() (GraphQL)
    │    └── Cache tags in Settings.exploreTags
    │
    ├──▸ If tag == .all:
    │    └── ExploreContentAPI.getAllCategories() → [BNCategory]
    │
    ├──▸ If tag == .tag(Tag):
    │    └── ExploreContentAPI.getContent(with: tag, offset:) → [ContentItem]
    │
    └──▸ Emit state update → ExploreFeedView renders grid

Pagination adds more items when the user scrolls:

User scrolls near bottom
    │
    ▼
ExploreFeedDataProvider.loadMore()
    │
    ├── Increment offset
    ├── ExploreContentAPI.getContent(with: tag, offset:)
    ├── Deduplicate against existing items
    └── Append to content list

Custom Mode

User opens Explore tab (custom mode)
    │
    ▼
HomeFeedDataProvider.loadData()
    │
    ├──▸ ExploreService.getExploreFeedSections() (GraphQL)
    │    └── FeedAPI.getExploreFeedSections()
    │
    ├──▸ Cache in Core Data via DataApiCache
    │
    └──▸ Return sectioned feed (same structure as Home v1)

Data Models

Tag:

@frozen public struct Tag: Codable, Hashable, Sendable {
    public let id: String
    public let name: String
    public let imageUrl: URL?
    public let sortBy: SliceSortBy?
    public let sortDirection: SliceSortDirection?
}

public enum ExploreTag: Hashable, Equatable {
    case all
    case tag(Tag)
}

ContentItem:

public struct ContentItem: Hashable, Sendable {
    public enum ContentType: String, Sendable {
        case category, subcategory, session
    }

    // Key properties: id, title, thumbnail, contentType,
    // lock status, viewed percentage, content metadata
}

ContentItem is the shared model used across all Explore screens (feed grid, category details, subcategory details).

ExploreFeedAPI protocols:

public typealias ExploreFeedAPI = ExploreContentAPI & ExploreTagsAPI

public protocol ExploreContentAPI {
    var pageSize: Int { get }
    func getAllCategories() -> AnyPublisher<[BNCategory], Error>
    func getContent(with tag: Tag, offset: Int, sortInfo: ...) -> AnyPublisher<[ContentItem], Error>
    func getSubcategories(forCategory categoryId: String, ...) -> AnyPublisher<[ContentItem], Error>
}

public protocol ExploreTagsAPI {
    func getExploreTags() -> AnyPublisher<[Tag], Error>
}

Configuration

ExploreScreenConfigFactoryType

Customer apps implement this protocol to configure the Explore screen's visual appearance:

protocol ExploreScreenConfigFactoryType {
    func makeExploreFeedScreenConfig(bgUrl: URL?) -> ExploreFeedScreenConfig
}

ExploreFeedScreenConfig

The ExploreFeedScreenConfig struct controls the visual appearance of the generic Explore feed:

Other Screen Configs

Each detail screen has its own configuration struct:

Navigation and Integration

ExploreFeedDelegate

The ExploreFeedDelegate protocol bridges ExploreFeedViewModel (in Core) with ExploreCoordinator (in Client):

Additional navigation from the Explore screen:

Deep Link Support

Explore supports deep linking for content-related destinations:

Cross-Module Integration

Explore does not directly integrate with Tuya, Biometrics, or Community modules.

For Agents

Reading Order

When working with the Explore module, read files in this order:

1. Client/Coordinators/Tabs/ExploreCoordinator.swift (218 lines) for the dual mode logic, navigation, and delegate handling
2. Core/Screens/Explore/Feed/ExploreFeedViewModel.swift (228 lines) for the ViewModel, ExploreFeedDelegate protocol, and data provider usage
3. Core/Screens/Explore/Feed/ExploreFeedDataProvider.swift (192 lines) for pagination, deduplication, and state machine
4. Core/Screens/Explore/Feed/ExploreFeedAPI.swift (80 lines) for the API protocol definitions
5. Core/Screens/Explore/Feed/ExploreFeedScreenConfig.swift (195 lines) for the configuration structure
6. Client/App/Screen Config/FactoryTypes.swift (search for ExploreScreenConfigFactoryType) for the configuration protocol

Key Files

Tips

• To understand the two modes: check ExploreCoordinator.start() which branches on ExploreViewType. Generic creates ExploreFeedViewController, custom creates HomeViewController with isUsedForExploreFeed: true.
• Tags are cached in Settings.exploreTags (UserDefaults) so they display immediately on next launch while fresh tags load from the server.
• ContentItem is shared across all Explore screens. It uses a ContentType enum (.category, .subcategory, .session) to differentiate item types.
• ExploreCoordinator is only 218 lines, much simpler than HomeCoordinator's 1,146 lines. Most navigation delegates to ContentDetailsCoordinator.shared.
• Custom mode is essentially Home v1 in a different tab. If you understand the Home feed, you understand custom Explore. The only difference is data source (ExploreService vs HomeFeedService).
• To add a new content type to the grid: update ContentItem.ContentType, add handling in ItemCellController, and update ExploreFeedDelegate if navigation differs.

What's Next