CCCT-2520 Start-Of-App Routing And Back Navigation Spec

[conroy-ricketts]

CCCT-2520

Technical Summary

Spec for the Connect redesign's start-of-app routing and app-wide back navigation. The plan is to create new tickets once it is approved.

Safety Assurance

Safety story

What gives me confidence:

• This PR is for a spec only — it changes no code and will not be merged.
• The spec was iterated over several review rounds with input from stakeholders.

[coderabbitai]

📝 Walkthrough

Walkthrough

The document defines a Connect UI navigation redesign. It adds run-once startup routing based on session and configuration state. It separates navigation surfaces from the CommCare runtime. It defines flag-free temporal back navigation, deep-link parent synthesis, session transitions, logout behavior, and PersonalID reset behavior. It also specifies persona flows, edge-case handling, interim and north-star implementation plans, testing, rollout, and approval requirements.

Estimated code review effort: 2 (Simple) | ~10 minutes

Possibly related PRs

• dimagi/commcare-android#3765: Covers related Connect launch orchestration and deferred back-stack handling.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Title check	✅ Passed	The title clearly identifies the ticket and the specification’s two main topics: startup routing and back navigation.
Description check	✅ Passed	The description explains the specification, links the related ticket, and provides a safety rationale for a documentation-only change. Automated test coverage and the Labels and Review checklist are n…

Full details: Description check

Explanation

The description explains the specification, links the related ticket, and provides a safety rationale for a documentation-only change. Automated test coverage and the Labels and Review checklist are not included, but these omissions are reasonable for a spec-only PR and do not make the description largely incomplete.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch CCCT-2520-app-navigation-changes-spec

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 8

🧹 Nitpick comments (1)

docs/superpowers/specs/2026-07-23-app-navigation-changes-design.md (1)

194-201: 🩺 Stability & Availability | 🔵 Trivial | ⚡ Quick win

Add regression scenarios for startup boundary cases.

Extend the test plan to cover:

• External app installation through ACTION_VIEW.
• Verification success with KEY_REQUIRE_REFRESH.
• Unlock cancellation during cold start.
• Session expiry while the app is backgrounded.
• Forget PersonalID while an app session remains active.
• Feature-flag-off behavior for traditional users.

These cases exercise the existing DispatchActivity boundary and the new session-routing rules.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/superpowers/specs/2026-07-23-app-navigation-changes-design.md` around
lines 194 - 201, Extend the “Testing & rollout” plan with regression scenarios
for the DispatchActivity startup boundary and session-routing rules: ACTION_VIEW
external app installation, verification success with KEY_REQUIRE_REFRESH,
cold-start unlock cancellation, session expiry while backgrounded, Forget
PersonalID with an active app session, and feature-flag-disabled behavior for
traditional users.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/superpowers/specs/2026-07-23-app-navigation-changes-design.md`:
- Around line 133-135: Update the Forget PersonalID flow centered on
forgetUser() so it resolves any active app session before returning to Intro.
Either clear the active session during de-registration or persist a one-shot
reset marker that the startup resolver consumes before applying the
active-session routing to StandardHomeActivity or OpportunityHomeActivity;
preserve the existing Intro/CLEAR_TASK behavior afterward.
- Around line 92-98: Define the dedicated navigation preferences store so all
last-accessed opportunity, last session context, and terminal-state
acknowledgment keys are scoped to the active PersonalID. Specify migration
behavior for any existing unscoped data, clear the scoped entries when switching
accounts or during forgetUser()/PersonalID removal, and ensure a new user cannot
inherit another user’s navigation state.
- Around line 66-73: Update the inputs table near the Installed apps present
entry so it has separate rows for Installed apps present, sourced from
MultipleAppsUtil.usableAppsPresent(), and Last accessed opportunity, sourced
from the new persistence described below. Ensure each row contains exactly two
cells and preserve the existing Last session context row.
- Around line 10-12: Clarify the navigation summary and corresponding interim
sections to distinguish the flag-free behavior as a north-star target only.
Document that the interim retains appLaunchedFromConnect, finishAffinity,
fragment pop logic, and REORDER_TO_FRONT, and define the accepted limitations or
defect criteria for that interim behavior.
- Around line 100-108: Define an explicit foreground-visible session-expiry
transition for StandardHomeActivity and OpportunityHomeActivity, including apps
resumed after background expiration. Route StandardHomeActivity expiry to the
CommCare Apps list and OpportunityHomeActivity expiry to Opp List, bypassing
login and avoiding reliance on Back or onResume() router re-dispatch.
- Around line 58-59: Update the startup router design to prioritize explicit
startup intents before configuration-based cold-start routing and before the
one-shot handoff. Preserve handling for CommCareSetupActivity launches after
external ACTION_VIEW installs and CommCareVerificationActivity launches carrying
KEY_REQUIRE_REFRESH, ensuring DispatchActivity receives and processes these
intent-driven states first.
- Around line 77-78: Clarify the cold-start behavior in the navigation
specification for PersonalID unlock cancellation or failure: define the explicit
destination among Intro, Opp List, or CommCare Apps list, rather than relying on
an unchanged underlying screen. Ensure the documented route does not fall back
to DispatchActivity or launch a partially initialized home without a valid
back-stack target.
- Around line 62-78: Update the active-session routing rule and related
session-establishment flow to persist or propagate login provenance,
distinguishing manual login from PersonalID login. Use that provenance when
selecting OpportunityHomeActivity versus
StandardHomeActivity/RootMenuHomeActivity, and explicitly define the tie-break
behavior when it conflicts with current evaluateAppState or getJobForSeatedApp
linkage.

---

Nitpick comments:
In `@docs/superpowers/specs/2026-07-23-app-navigation-changes-design.md`:
- Around line 194-201: Extend the “Testing & rollout” plan with regression
scenarios for the DispatchActivity startup boundary and session-routing rules:
ACTION_VIEW external app installation, verification success with
KEY_REQUIRE_REFRESH, cold-start unlock cancellation, session expiry while
backgrounded, Forget PersonalID with an active app session, and
feature-flag-disabled behavior for traditional users.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 0d5b0ab9-659b-4f7a-85b0-f10826b2634b

📥 Commits

Reviewing files that changed from the base of the PR and between e1c8ba8 and 0b6222c.

📒 Files selected for processing (1)

• docs/superpowers/specs/2026-07-23-app-navigation-changes-design.md

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 33.06%. Comparing base (78f482b) to head (dc8d7fa).
⚠️ Report is 52 commits behind head on master.

Additional details and impacted files

@@             Coverage Diff              @@
##             master    #3844      +/-   ##
============================================
+ Coverage     33.02%   33.06%   +0.04%     
- Complexity     5801     5815      +14     
============================================
  Files           995      996       +1     
  Lines         59288    59315      +27     
  Branches       7068     7070       +2     
============================================
+ Hits          19581    19615      +34     
+ Misses        37468    37454      -14     
- Partials       2239     2246       +7     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[conroy-ricketts]

Hi @ctsims @avazirna, this spec touches traditional CommCare so I requested your reviews as well. I also have a document here that covers these changes at a high-level and may be worth a read before diving deep into the spec

[shubham1g5]

@conroy-ricketts Flagging that this spec is overly verbose and think we should be able to simplify it greatly by deviating from text heavy approach to more use visualization techniques to explain the flow and just listing he new changes we need to make. The current text is also heavy on AI jargon and I would encourage re-writing most of this spec in a simplified manner (avoid use of AI if needed)

Also the user-facing requirements from the spec (eg. desired user flows ) needs to be defined first in the design doc for a product review and this doc should just explain the tech challeges and solution approach for achieving the desired flow.

[conroy-ricketts]

@shubham1g5

Agreed, that's a fair point. I added new diagrams to both the tech spec here and the design doc. Also, I trimmed down the tech spec and separated out the section that does not need to be reviewed now (i.e. can be deferred to later code review). The diagrams actually came out pretty good in GitHub's rich diff preview.

I believe what's left now in both the design doc and the tech spec is only the information/context necessary for review, with user flows laid out in the design doc.

[conroy-ricketts]

Hi @dimagi/connect-mobile-devs @avazirna @ctsims,

Bumping this for review - it has been updated to align with the design spec in the Google doc

[conroy-ricketts]

Converting this to a draft until the Google doc is finalized and approved

[conroy-ricketts]

Hey @Jignesh-dimagi, both the design doc and the tech spec have went through significant revision since you last reviewed, so I'm resolving your comments for now. Please let me know if I missed anything!

[conroy-ricketts]

Hi @shubham1g5 @Jignesh-dimagi @OrangeAndGreen,

This is ready for a fresh look!

I'm also hoping that y'all can let me know what you think about the AI verbosity on this (i.e. is it too much, just right, or too little?)

Note that only the first half of the spec (before the implementation notes) is necessary for review at this moment.

Thanks!

[shubham1g5]

Confirming that this doesn't mean user would go back to Opp List when clicking back from Opp Home given user never sees the screen in both these workflows, in 1. User move directly to Opp Home and in 2. to CC login/Intro page.

[conroy-ricketts]

Note: longer reply, but I think the reasoning is important

Yeah, users will see the Opp List when they tap back from Opp Home.

One note on the row you've commented on: that's the "no current opportunity" case, where Opp List is the landing screen and back exits in one press. The extra step is the row above, where they have a current opportunity and land straight into it.

The reason the list stays underneath is that it's also a sidebar destination. Open the sidebar → Opportunities → tap the wrong opportunity → back puts you on the list so you can pick again. If Opp Home were the bottom, that same back press exits the app.

And I don't think we can have both: either back from Opp Home always exits (so a mis-tap drops you out), or it sometimes returns to the list (so back depends on how you got there, which is the state-dependent behaviour we're trying to remove). The trade-off is one extra press on the way out versus an accidental exit, which often means unlocking PersonalID again.

This came up with Dave on the design doc and we went a few rounds on it. He landed on trying it this way. We also committed to measuring how often people pass through the list on the way out versus going there deliberately to switch, so we can revisit with data if it turns out to be friction.

[shubham1g5]

that's the "no current opportunity" case, where Opp List is the landing screen and back exits in one press.

In this case, Opp List page remains hidden and user would never land on Opp List but the CC Login or App Home as per the starting router logic.

The reason the list stays underneath is that it's also a sidebar destination. Open the sidebar → Opportunities → tap the wrong opportunity → back puts you on the list so you can pick again.

Opp home is a sidebar destination as well so having user go back to Opp List is not justified here given user never came to this page during forward nav.

If Opp Home were the bottom, that same back press exits the app.

Think that's exactly what we want. Do you have a different read from the design doc on this ? Think we should go back to design doc on this if so.

A primary goal of this work is to remove the Opp List page from user workflows given almost all our users don't have more than a single opprotunity today and it feels very weird to me if user sees a page they don't see in their natural app navigation suddently coming on pressing back and is a major bad smell in this design.

[conroy-ricketts]

@shubham1g5

Ah, that's the confusion I'm having. I didn't realize we wanted to remove the Opp List page, nor that the Opp Home would be the sidebar destination and not the Opp List. I think that changes the proposal here significantly.

Yeah, we may want to go back to the design doc on this one - it assumed the Opp List was still a major piece of the workflow, and the app nav design spec does not describe this behavior.

[conroy-ricketts]

@shubham1g5 @OrangeAndGreen @Jignesh-dimagi

Before I make further edits on these specs, I need to confirm some details:

If Opp Home will become a sidebar destination, how will the app sidebar accommodate it? For example, will it be a new dedicated button?

Relatedly, are we still keeping the "Opportunities" button?

[shubham1g5]

That's a good question and seems like a gap in redesign. Think it would be great to ask this to product/Ishwari on the design doc. My sense is it's alright to move user to the Opportunity List page on clicking Opportunities button in side drawer.

[shubham1g5]

I didn't realize we wanted to remove the Opp List page,

Also to be clear, the page is still there but won't part of the launch navigation for user as in most cases user would land on Opp Home page directly as per the app startup routing logic.

[shubham1g5]

Pressing back from App Home should exit as that's the first page user sees and user should only go back to login page when there is no active user session .

[conroy-ricketts]

The reason it's in the path is because the Login page has the app picker dropdown. That's what the design doc landed on in the near-term section ("back behaves against that Login Page as the home").

That said, I'm torn. Today, Back from App Home exits, so as written this changes Back behaviour for traditional CommCare users, and I'd rather not change their experience if we can avoid it.

Once the Login page becomes the CC Apps list, is "Back from App Home exits" still what we want?

If Back → CC Apps list is right at that point, the choice is between exiting now and changing later, or being consistent from the start.

[shubham1g5]

Once the Login page becomes the CC Apps list, is "Back from App Home exits" still what we want?

Yes. I see the Login and App Home on the same heirarchy with different states (signed in and signed out). Pressing back to login seems like pressing back to logout which will cause session disruptions and defeats the purpose of us keeping sessions alive deliberately for 24 hours since the user login.

[conroy-ricketts]

That makes sense to me. I'll revisit this. This also conflicts with the design spec and we may want to revisit/update that too

[shubham1g5]

This also conflicts with the design spec

Aplogies if I am oversee-ing something here but I am struggling to see where this information is surfaced on the design doc.

[shubham1g5]

drawerShownBefore is required since the logic to show drawer is 1. A personalID user OR 2. the drawer shown before on same app sandbox

[conroy-ricketts]

This reverts a decision made in the design doc. Just confirming that we no longer want to show the sidebar on every home screen for all users?

The original reason for this was that the sidebar is the only place in the app an established traditional CommCare user can discover PersonalID in the interim until the new CommCare App List page is implemented. Gating it on already being a PersonalID user makes that circular.

Please let me know if I'm missing something here

[shubham1g5]

This reverts a decision made in the design doc. Just confirming that we no longer want to show the sidebar on every home screen for all users?

I didn't realise we talked about this on desigc doc so think there is some confusion somewhere but I am unable to relate the 2 decisions here.

IMO, we want to show the side bar on all the home pages only if user is signed in as a Personal ID account or if the drawer has been shown before on that app sandox. We strictly do not want to show drawer for non-personal ID users on all pages.

the sidebar is the only place in the app an established traditional CommCare user can discover PersonalID in the interim until the new CommCare App List page is implemented.

We still have the "Sign up" option on the 3 dot menu on Login Page.

[conroy-ricketts]

That sounds good to me, I'll come back to this! I almost forgot about that 3 dot menu