Documentation Master Plan
Tracking the progress of documenting every module, architecture pattern, and integration point in the Youll platform.
Overview
This master plan tracks the documentation effort for the entire Youll platform. Each item below represents a documentation page or section that needs to be written. The plan is ordered by dependency: foundational topics first, then modules that build on them.
Use this page as the single source of truth for what has been documented and what remains.
Status Legend
| Symbol | Meaning |
|---|---|
| Done | Page is written and reviewed |
| In Progress | Currently being worked on |
| Planned | Scoped and ready to write |
| Blocked | Waiting on another page or decision |
Phase 1: Foundation (Architecture)
These pages explain how the platform works at a structural level. They should be written first because every module page will reference them.
| # | Page | Status | Priority | Notes |
|---|---|---|---|---|
| 1.1 | Architecture Overview | Done | Critical | Three-layer model, dependency graph, how customer apps consume Bricks |
| 1.2 | Dependency Graph | Done | Critical | Visual module dependency map, which modules depend on which |
| 1.3 | Bootstrap Sequence | Done | Critical | AppDelegate and SceneDelegate setup flow, initialization order |
| 1.4 | Design Token System | Done | High | Figma export to runtime theming: ConfigParser, TypographyParser, UIConfigurator |
| 1.5 | Coordinator Pattern | Done | High | Navigation architecture, parent/child coordinators, coordinator flows |
| 1.6 | Module Interfaces | Done | High | How optional modules are defined in Core and injected at runtime |
| 1.7 | Communication Patterns | Done | Medium | Combine publishers, delegates, NotificationCenter, singletons |
Phase 2: Infrastructure (Technical Modules)
These are the foundational technical modules that all other modules depend on. Document them before the product modules.
| # | Page | Status | Priority | Notes |
|---|---|---|---|---|
| 2.1 | YoullNetwork | Done | Critical | GraphQL (Apollo) + REST dual transport, API classes, data models, token management |
| 2.2 | Core | Done | Critical | ~672 files. Foundation layer + screens for all core product modules (Home, Explore, Search, Library, Journeys, Events, Activity, Meals, Quiz, Favorites, Playlists). Also: coordinator protocol, settings, feature flags, UI infrastructure, theming, storage property wrappers, services |
| 2.3 | Client | Done | Critical | Orchestration layer: Config singleton, AppCoordinator, MainCoordinator, tab coordinators (Home, Explore, Library, Journeys, Events, Activity, Meals, etc.), screen config factory, analytics, notifications, tab selection via makeTabItems() |
Phase 3: Product Modules
Each product module gets documentation covering what it does, how to activate it, its configuration options, and integration points. Product modules that live in their own Swift packages (Timer, Biometrics, Community, Tuya) also document their technical module structure.
Content modules (screens live in Core, coordinators in Client):
| # | Page | Status | Priority | Notes |
|---|---|---|---|---|
| 3.1 | Home Screen | Done | High | Three home screen versions: Home v1 (UIKit/GraphQL), Showcase v2 (SwiftUI/GraphQL), Slices v3 (SwiftUI/REST). Home v1 fully documented; v2 and v3 at overview level |
| 3.2 | Explore | Done | High | Browse by categories, subcategories, facilitators, tagged content. Two modes: generic (tag-based grid) and custom (home-like feed) |
| 3.3 | Journeys | Planned | High | Structured multi-session programs, journey details, progress tracking, completion |
| 3.4 | Library | Planned | High | Saved content, favorites, user-created playlists, playlist management |
| 3.5 | Search | Planned | Medium | Content search with filters, advanced search, search pills |
| 3.6 | Events | Planned | Medium | Live and scheduled events, event details, agenda management |
| 3.7 | Activity | Planned | Medium | Activity history, workout tracking, session statistics |
| 3.8 | Meals | Planned | Low | Meal plans and nutrition content |
| 3.9 | Quiz | Planned | Low | Interactive quizzes and assessments |
Standalone product modules (own Swift packages, injected at runtime):
| # | Page | Status | Priority | Notes |
|---|---|---|---|---|
| 3.10 | Player | Planned | High | Audio/video playback, mini player, workout player, map routes, Now Playing integration |
| 3.11 | Profile | Planned | High | ~100 files. User profile, settings, subscriptions/paywall (including SuperPaywall), reminders, badges, Apple Health UI, sharing |
| 3.12 | Onboarding | Planned | High | Auth flows (email, Apple, Google, anonymous), onboarding screens (splash, slider, social proof, video), email verification |
| 3.13 | Timer | Planned | Medium | Meditation/session timer, bell intervals, background sounds, Tuya IoT integration during sessions, live activities |
| 3.14 | TimerShared | Planned | Medium | Shared types for Timer and widget extension, ActivityKit live activities, TimerLiveActivityManager |
| 3.15 | Biometrics | Planned | Medium | HealthKit integration, HRV, resting heart rate, sleep, steps, calories, workout data, period-based averages |
| 3.16 | Community | Planned | Medium | Social features: channels, posts, replies, reactions, post creation with attachments, admin moderation, report management |
| 3.17 | Tuya | Planned | Medium | IoT device integration: 5 device types, BLE/WiFi pairing, scheduling, settings, maintenance reminders |
| 3.18 | CoreWidget | Planned | Low | iOS home screen widgets: content recommendations, streak tracking, App Groups data sharing, image caching |
| 3.19 | UITests | Planned | Low | Shared UI test infrastructure, BaseTests, per-section test classes, accessibility identifiers |
Phase 4: Integration Guides
Practical guides for developers and agents working with the platform.
| # | Page | Status | Priority | Notes |
|---|---|---|---|---|
| 4.1 | Creating a New Customer App | Planned | High | Step-by-step guide: submodule setup, Keys, AppDelegate, SceneDelegate, screen configs |
| 4.2 | Screen Config Factory Guide | Planned | High | How to implement ScreenConfigFactoryType and all ~20 sub-factory protocols |
| 4.3 | Adding a New Module | Planned | Medium | How to create a new Bricks module with proper interface protocol and injection |
| 4.4 | Design Token Workflow | Planned | Medium | Figma export to JSON to runtime: end-to-end guide |
| 4.5 | Analytics Integration | Planned | Medium | Implementing AnalyticsManagerType and the ~15 analytics protocol conformances |
| 4.6 | Feature Flags | Planned | Low | FlaggingManager, FlagProvider, Firebase Remote Config integration |
| 4.7 | Push Notifications | Planned | Low | NotificationManager, local notifications, remote notification handling |
Product Module Catalog
Complete list of all product modules available to customers. Modules are activated via tab selection (makeTabItems()), feature flags, or runtime injection.
| Product Module | Activation | Technical Home | Description |
|---|---|---|---|
| Home Screen | Tab (.home / .showcase / .slices) | Core + Client | Personalized feed in three versions: Home v1 (UIKit/GraphQL), Showcase v2 (SwiftUI/GraphQL), Slices v3 (SwiftUI/REST) |
| Explore | Tab (.explore) | Core + Client | Browse by categories, subcategories, facilitators |
| Search | Settings + Tab | Core + Client | Content search with filters |
| Library | Tab (.library) + Flag | Core + Client | Saved content, favorites, playlists |
| Journeys | Tab (.journeys) + Flag | Core + Client | Multi-session structured programs |
| Events | Tab (.events) + Flag | Core + Client | Live and scheduled events |
| Activity | Tab (.activity) + Flag | Core + Client | Activity history, workout tracking |
| Meals | Tab (.meals) + Flag | Core + Client | Meal plans and nutrition |
| Quiz | Flag | Core + Client | Interactive assessments |
| Player | Always active | Player package | Audio/video playback |
| Profile | Always active | Profile package | User profile, settings, subscriptions |
| Onboarding | Always active | Onboarding package | Auth flows and onboarding screens |
| Timer | Runtime injection | Timer package | Session timer with sounds and live activities |
| Biometrics | Runtime injection + Tab | Biometrics package | HealthKit integration |
| Community | Runtime injection + Tab | Community package | Social features: channels, posts, moderation |
| Tuya | Runtime injection | Tuya package | IoT device control |
| Widgets | App extension | CoreWidget package | Home screen widgets |
Technical Module Inventory
The 13 Swift packages under Bricks/modules/ and their relationships.
| Swift Package | Files | Dependencies | Used by Reference App | Has Module Interface |
|---|---|---|---|---|
| YoullNetwork | ~130 | None (leaf) | Yes | No |
| Core | ~672 | YoullNetwork | Yes | Defines all interfaces |
| Client | ~65 | Core, Onboarding, Player, Profile | Yes | No |
| Player | ~80 | Core, YoullNetwork | Yes | No |
| Profile | ~100 | Core, YoullNetwork | Yes | No |
| Onboarding | ~60 | Core, YoullNetwork | Yes | No |
| Timer | ~17 | Core, TimerShared | Yes | Yes (TimerModuleInterface) |
| TimerShared | 5 | None (leaf) | Yes | No |
| Biometrics | ~24 | Core | Yes | Yes (BiometricsModuleInterface) |
| Community | ~47 | Core, YoullNetwork | No | Yes (CommunityModuleInterface) |
| Tuya | ~60 | Core, YoullNetwork | Yes | Yes (TuyaModuleInterface) |
| CoreWidget | ~23 | Core, YoullNetwork | No | No |
| UITests | ~20 | None (leaf) | Indirectly | No |
Dependency Graph
YoullNetwork (no deps)
|
v
Core (YoullNetwork)
|
+---> Biometrics (Core)
+---> Community (Core, YoullNetwork)
+---> CoreWidget (Core, YoullNetwork)
+---> Player (Core, YoullNetwork)
+---> Profile (Core, YoullNetwork)
+---> Onboarding (Core, YoullNetwork)
+---> Timer (Core, TimerShared)
+---> Tuya (Core, YoullNetwork)
+---> Client (Core, Onboarding, Player, Profile)
TimerShared (no deps, standalone)
UITests (no deps, standalone)How to Use This Plan
- Pick the next "Planned" item following the phase order (Phase 1 before Phase 2, etc.)
- Create a separate plan for that documentation page using the
/workflows:plancommand - Write the documentation following the plan
- Update this page by changing the status from "Planned" to "Done"
- Move to the next item
Each documentation page should follow this structure:
- Purpose: What the module does and why it exists
- Public API: Key types, protocols, and classes developers interact with
- Configuration: How to set up and configure the module
- Integration: How the module connects with other modules
- Usage Examples: Code snippets showing common usage patterns
- For Agents: Guidance for AI agents working with the module