[Advanced] Build a complete NFC write + deep link system with environment-aware URL generation, card-specific payloads, and mobile NFC write support

[MehtabSandhu11]

Summary

The NFC feature is incomplete and broken. The payload URL is hardcoded
to a specific domain, points to a non-existent route, has no support
for card-specific deep links, and the mobile app has no NFC write
implementation at all. This issue covers building the full NFC feature
end-to-end: a correct backend payload API, a mobile NFC write screen,
and analytics tracking for NFC-sourced visits.

Context

Problem 1 — Hardcoded broken URL:
apps/backend/src/routes/nfc.ts line 87:

const payloadUrl = `https://dev-card.vercel.app/${username}${
  cardId ? `?card=${cardId}` : ''
}`;

Two bugs: hardcoded domain ignores PUBLIC_APP_URL, and the path
/:username doesn't match the web app's actual route /u/:username.
Every NFC tag written with the current code points to a broken URL.

Problem 2 — No mobile NFC write implementation:
The backend returns a payload URL but the mobile app has no screen or
logic to actually write that URL to an NFC tag. react-native-nfc-manager
is not installed. Users have no way to write their DevCard to a physical
NFC tag from the app.

Problem 3 — No analytics for NFC scans:
The source field on CardView supports 'qr' | 'link' | 'web' | 'app'
but 'nfc' is not handled. NFC-sourced visits are indistinguishable
from other sources in the analytics dashboard.

Problem 4 — No fallback for NFC-unsupported devices:
When a receiver taps an NFC tag on a device without NFC or on iOS
without the required entitlement, there is no graceful fallback
documented or implemented.

Tasks

• Fix the payload URL to use process.env.PUBLIC_APP_URL and
  correct the path to /u/:username
• Add startup validation — if PUBLIC_APP_URL is unset, return
  500 with a descriptive error rather than producing a malformed URL
• Add 'nfc' as a valid source value in the CardView model and
  update the analytics overview endpoint to break out NFC views
  separately
• Install and configure react-native-nfc-manager in
  apps/mobile
• Build a NFCWriteScreen in the mobile app that: fetches the
  payload from GET /api/nfc/payload, checks NFC hardware
  availability, writes the NDEF URI record to the tag, and shows
  clear success/error states
• Add the NFC write option to the existing share flow in
  HomeScreen or DevCardViewScreen
• Document the iOS NFC entitlement setup required in
  apps/mobile/README.md
• Add unit tests for the fixed payload URL generation

Acceptance Criteria

• NFC payload uses PUBLIC_APP_URL and correct /u/:username path
• source: 'nfc' tracked in CardView analytics
• Mobile app can write a DevCard URL to a physical NFC tag
• NFC unavailability handled gracefully with a clear user message
• iOS entitlement setup documented
• Unit tests for payload URL generation pass

Area

backend, mobile

Difficulty

Advanced

[Kawshikk-Shrii]

Hello there!!
I would like to work on this issue. Can you please assign it to me.

[Harxhit]

@MehtabSandhu11 I have assigned this issue to you.

[Pcmhacker-piro]

Hi @Harxhit,

I’m interested in contributing to this project and would love to work on this issue. I have experience working on open-source contributions and would be happy to implement the required changes.

Could you please assign this issue to me? Thanks!

[github-actions]

Hey @ShantKhatri (Project Admin) and @Harxhit (Maintainer),

This issue (previously assigned to @MehtabSandhu11) has been automatically unassigned because no linked pull request was found after the scheduled check.

If work is in progress, please open a PR and link it to this issue to keep the assignment.

[Harxhit]

@Pcmhacker-piro I have assigned this issue to you.