Rationale: The app follows the MVVM pattern, organized in three layers with one-way dependencies: View → ViewModel → Model. Each layer only knows the one below it.

• View: the screens only draw the state they observe from their ViewModel and report what the user does. They never access data directly. The design system keeps colors, typography and components in one place, so all screens look consistent.
• ViewModel: there is one per screen. It holds the screen's state and survives configuration changes such as rotation, so the View can be rebuilt at any time without losing data.
• Model: repositories are the only entry point to the data. They hide whether it comes from Supabase (remote data sources) or from the local Room database. Mappers convert the backend's format into domain models, so a change in the backend does not reach the ViewModels or the screens.
• Local database (Room / SQLite): the app must keep working without a connection and keep the user's quest progress. Saving the data on the device makes that possible.
• Supabase as backend: it provides authentication, a REST API over PostgreSQL and file storage, so the team does not need to build and host its own server. All communication goes over HTTPS.
• Core: connectivity, location, fetch strategies, the event bus, dependency injection and telemetry are needed by several features. Keeping them in one module avoids repeating them and keeps the device's sensors (GPS, network state) behind a single access point.

This separation lets the team work on screens and data access in parallel, test the logic without a device, and replace a part (for example, the map provider or the backend SDK) without changing the rest.

flowchart LR
    User((User))

    subgraph iOS["iOS app – MVVM"]
        View[ProfileView]
        VM[ProfileViewModel]
        Service[StreakService]
        DTO[(StreakDTO)]
    end

    subgraph Supabase["Supabase backend"]
        RPC[get_streak_summary RPC]
        subgraph DB["PostgreSQL"]
            Users[(users)]
            QC[(quest_completions)]
            Badges[(badges / user_badges)]
        end
    end

    User -- opens Profile --> View
    View -- observes --> VM
    VM -- asks for data --> Service
    Service -- calls via HTTPS --> RPC
    RPC -- reads --> Users
    RPC -- reads --> QC
    RPC -- reads --> Badges
    RPC -- JSON --> Service
    Service -- decodes into --> DTO
    VM -- holds --> DTO

Rationale: The iOS side follows MVVM. The view only observes the ViewModel, the ViewModel holds the screen state and the BQ4 comparison logic, and the Service is the only component that knows about Supabase. On the backend, a single RPC function reads the three tables and returns the summary already aggregated, so the phone makes one request instead of several and the Android app can reuse exactly the same calculation.

%%{init: {"flowchart": {"curve": "linear"}}}%%
flowchart LR
    User((User))

    subgraph iOS["iOS app – MVVM"]
        HV[HomeView]
        RV[RecommendedQuestsView]
        VM[DiscoveryViewModel]
        QR[QuestRepository]
        SR[SupabaseQuestRepository]
        Strategy[HistoryRecommendationStrategy]
    end

    subgraph Supabase["Supabase backend"]
        subgraph DB["PostgreSQL"]
            Q[(quests)]
            QC[(quest_completions)]
            P[(places)]
        end
    end

    User -->|opens Home| HV
    HV -->|observes| VM
    VM -->|requests recommendations| QR
    QR -->|implemented by| SR

    SR -->|reads| Q
    SR -->|reads| QC
    SR -->|reads| P

    SR -->|returns quests, history and ratings| VM
    VM -->|applies| Strategy
    Strategy -->|filters and orders completed quests| VM

    VM -->|updates recommendation state| HV
    HV -->|shows recommended quests| RV
    RV -->|observes| VM

Rationale: The iOS side follows MVVM. HomeView and RecommendedQuestsView display the recommendation state, while DiscoveryViewModel manages the loading and screen state. The SupabaseQuestRepository retrieves the available quests, the user's completed quests, and the corresponding place ratings from Supabase. The HistoryRecommendationStrategy contains the recommendation logic, excluding completed quests and prioritizing quests whose categories match the user's previous activity, with ratings used to further order the results. This separation keeps the recommendation logic independent from the views and repository and allows the strategy to be changed without modifying the UI.

sequenceDiagram
    box View
        participant UI as HomeScreen
    end
    box ViewModel
        participant VM as HomeViewModel
    end
    box Model
        participant D as TelemetryQuestRepository
        participant R as QuestRepositoryImpl
        participant S as FetchStrategy
        participant DB as Room
    end
    participant API as Supabase
    participant Bus as AppEventBus

    UI->>VM: observes uiState
    VM->>D: nearbyQuests(location)
    D->>R: nearbyQuests(location)
    R->>S: select(policy).fetch(local, refresh)
    alt online (NetworkFirst)
        S->>API: nearby_quests RPC + quest_tags
        API-->>S: DTOs (JSON)
        S->>DB: mappers → entities, replaceNearby()
    else offline (CacheOnly)
        Note over S: skips the network
    end
    DB-->>VM: Flow of quests (isStale = true when offline)
    VM-->>UI: new UiState
    D->>Bus: RequestTimed(quest_recommendations_load)
    Bus->>Bus: TelemetryCollector saves it, uploads a batch later

Rationale: The app uses Supabase to store user interests, favorite places, and quest history. When a user opens the app, it uses their phone's GPS to show nearby quests that match their chosen energy level and interests. As users complete quests, the app learns their preferences and recommends new activities they might like. Users can also save places as favorites and see them on a nearby map based on their current location.

flowchart LR
    User((User))

    subgraph Android["Android app – MVVM"]
        QS[QuestDetail / ActiveQuest screens]
        QVM[Quest ViewModels]
        FS[QuestDropoffScreen]
        FVM[QuestDropoffViewModel]
        QR[QuestRepository]
        AR[AnalyticsRepository]
        Bus[AppEventBus]
        Tracker[QuestFunnelTracker]
        Tel[TelemetryCollector]
    end

    subgraph Supabase["Supabase backend"]
        QRPC[start_quest / complete_objective / abandon_quest]
        DRPC[get_quest_dropoff RPC]
        subgraph DB["PostgreSQL"]
            QC[(quest_completions)]
            QOC[(quest_objective_completions)]
            TE[(telemetry_events)]
        end
    end

    User -- views, accepts, checks steps --> QS
    QS -- observes --> QVM
    QVM -- calls --> QR
    QR -- HTTPS --> QRPC
    QRPC -- writes --> QC
    QRPC -- writes --> QOC
    QVM -- publishes quest events --> Bus
    Bus -- notifies --> Tracker
    Tracker -- funnel events --> Tel
    Tel -- batch upload --> TE
    FS -- observes --> FVM
    FVM -- asks for report --> AR
    QVM -- asks for drop-off hint --> AR
    AR -- HTTPS --> DRPC
    DRPC -- reads --> QC
    DRPC -- reads --> QOC

Rationale: The screens never call the analytics code. The ViewModels only publish quest events to the event bus, and the QuestFunnelTracker (Observer) listens to them and saves them as telemetry, so new metrics can be added without changing the screens. The abandonment count is calculated on the server by one RPC, because row-level security only lets each user read their own rows, and that way the phone makes a single request. The same report feeds the internal funnel view and the drop-off hint in Active Quest; if it fails, the quest still works without the hint.

flowchart LR
    U((User))

    subgraph IOS["iOS app · MVVM"]
        V["DiscoveryMapView<br/>SwiftUI + MapKit"]
        VM["DiscoveryMapViewModel"]
        LOC["MapLocationService<br/>CoreLocation"]
        F["MapDataFacade"]
        R["SupabaseMapRemote"]
        M["MapQuest / NeighborhoodActivityReport"]

        V -->|user actions| VM
        VM -->|publishes screen state| V
        LOC -->|GPS and permission state| VM
        VM -->|requests geography and analytics| F
        F -->|requests backend data| R
        R -->|decoded responses| F
        F -->|joins coordinates and sorts results| M
        M -->|map-ready data| VM
    end

    subgraph BACK["Supabase backend"]
        N["nearby_quests / nearby_places RPCs"]
        A["neighborhood_quest_activity RPC"]
        Q[("quests / places")]
        C[("quest_completions")]
        B[("neighborhoods")]

        N -->|reads| Q
        A -->|counts completed quests<br/>and distinct participants| C
        A -->|groups activity by place| Q
        A -->|reads neighborhood assignments| B
    end

    U -->|opens Map| V
    R -->|authenticated HTTPS| N
    R -->|authenticated HTTPS| A

Rationale: The iOS Map follows MVVM. DiscoveryMapView renders nearby quests, distances, and neighborhood activity, while DiscoveryMapViewModel manages screen state, filtering, loading, and retries. MapLocationService provides GPS and permission updates; when location is denied or unavailable, the screen explains the situation and uses Bogotá as a fallback.

The Facade pattern is implemented in MapDataFacade. It combines nearby quest data with place coordinates and returns sorted, map-ready models. SupabaseMapRemote handles authentication, RPC calls, and response decoding, keeping backend details outside the View and ViewModel.

The backend aggregates completed quests per neighborhood over the last 30 days, including distinct participants and active places. The screen ranks neighborhoods and highlights those with the most activity to answer BQ11: where should we prioritize local business partnerships?

Rationale: To make sure the app works offline, we use a local database called Room as our main source of truth, the Strategy pattern to switch between the internet and local storage, and the Observer pattern to update the screen automatically. To measure how fast the app responds without draining the battery or slowing down the user, we use a Decorator to time actions and group the tracking data in the background. Since the server code is still changing, we use DTOs, mappers, and facades to protect the main app code from breaking when those updates happen. Finally, we handle all security on the server side, meaning the app is treated as untrusted and can only do exactly what the database rules allow.

List all features implemented in this sprint and who is responsible for each, per app/platform.

Coverage check at minimum, one functionality per item below must be present:

Ethics Video: https://youtu.be/Iug1vyR6aBw Sprint Board: https://github.com/users/jdgutierrezr/projects/3

⬅️ Go to Sprint 2