Architect unified state restoration across QR scans, deep links, and (future) push notifications

[Lakes41]

Difficulty: Expert
Type: refactor

Background
The app has three distinct entry-point mechanisms into specific screens with associated data: QR access-check scans (in-app, camera-driven), deep links (custom scheme and universal link, with explicit cold-start support), and, if the push-notifications roadmap item is implemented, notification taps that also deep-link into the app — each currently handled somewhat independently.

Problem
As more entry points are added (push notifications, and potentially wallet-connect callback deep links from the Native Wallet Integration work), the risk of inconsistent behavior grows: cold start vs. warm start, navigation state clobbering an in-progress flow (e.g., a deep link arriving while the user is mid-way through a QR scan or wallet-connect flow), and duplicate/competing validation logic across each entry point.

Expected outcome
A single, unified "external entry" handling layer normalizes QR scans, deep links, and notification taps into one internal event shape, applies consistent validation and error handling (reusing the existing QR/deep-link validators rather than duplicating logic), and defines explicit, tested precedence/interruption rules for what happens when a new external entry arrives while the user is mid-flow in another one (e.g., a deep link arriving during onboarding, or a notification tap arriving during an active QR scan).

Suggested implementation

• Design a common ExternalEntryEvent type (source: qr | deep_link | notification, target screen, params) that all three entry mechanisms normalize into, reusing the existing per-source validation logic (QR payload validator, deep-link param validator) rather than rewriting it.
• Implement a single navigation-arbitration function that decides, given the current app/navigation state and an incoming ExternalEntryEvent, whether to navigate immediately, queue the navigation until the current flow completes, or discard it with user notification (e.g., "switched away from QR scan due to an incoming link") — document and test the exact precedence rules chosen.
• Cover cold-start and warm-start cases for all three sources through this same arbitration layer, eliminating any duplicated cold-start-specific logic.
• Add unit tests for the arbitration logic covering realistic interruption scenarios (link during onboarding, notification during QR scan, QR scan result while a deep link navigation is still pending) and Maestro E2E coverage for at least one real interruption scenario end-to-end.
• Document the full architecture, including the precedence rules and rationale, in docs/.

Acceptance criteria

• All three entry mechanisms funnel through one normalized event type and shared validation logic
• Explicit, tested precedence rules exist for competing/interrupting external entries
• Cold-start behavior is handled identically across all three sources via the shared layer
• Unit tests cover the arbitration logic's key interruption scenarios
• At least one interruption scenario is covered end-to-end via Maestro
• Architecture documented in docs/

Likely affected files/directories

• src/ (new unified entry-handling module)
• app/ (routing/layout integration)
• docs/
• .maestro/

[panditdhamdhere]

Can I work on this ?

[pedro-aldana]

Hi! I'm a full-stack software engineer with experience building applications using TypeScript, React/Next.js, Python (Django/FastAPI), PostgreSQL, and modular software architectures.

I've reviewed this issue and my approach would be to introduce a unified ExternalEntryEvent model that normalizes QR scans, deep links, notifications, and future entry sources into a single processing pipeline. From there, I would separate responsibilities into validation, arbitration, and navigation layers, reusing the existing validators instead of duplicating logic. The arbitration layer would define clear precedence rules for competing events (queue, interrupt, discard, or execute) while ensuring identical behavior for both cold and warm starts. I would also include unit tests covering interruption scenarios, an end-to-end Maestro test, and architecture documentation explaining the design decisions.

This kind of architectural refactoring is the type of work I enjoy, and I'd be happy to contribute.

[grantfox-oss]

🦊 GrantFox — @pedro-aldana has been assigned to this issue as part of the Official Campaign | FWC26 campaign!

Next steps:

1. Open a Pull Request referencing this issue (e.g., Closes #250)
2. Your PR will be reviewed by the Adamantine-guild maintainers

Good luck! Track your progress on GrantFox.