System Requirements Document for virtual-phone-numbers

1. Introduction

FreeConnect is a modern, interactive Android communication app that lets people access virtual phone numbers, make and receive internet-based (VoIP) calls, and place calls to regular mobile and landline numbers through a compatible telecom provider. The product is built for a global, mobile-first, price-aware audience across South Asia, the Gulf, the United Kingdom and the United States — people who need a reachable number in another country, who want to talk over Wi-Fi or mobile data, and who need to see real provider pricing and verification obligations before committing to a paid telecom service.

The product's defining intent is truthful telecom: it shows only numbers the selected provider can legally supply, labels every simulated call and message unmistakably, never invents real-world phone numbers, and never advertises real international calling as free unless the provider explicitly offers it for free. Users can explore the entire app without creating an account; an anonymous user ID is generated for the initial session and demo preferences are stored locally.

This document is the authoritative specification for the current delivery: the Android app, its backend API structure, demo mode, telecom integration interfaces, and the seven supported destinations — India (+91), Pakistan (+92), Bangladesh (+880), the United Kingdom (+44), the United States (+1), Dubai/United Arab Emirates (+971), and Iran (+98).

2. System Overview

FreeConnect is delivered as an Android application (Kotlin + Jetpack Compose) backed by a Node.js + TypeScript API service with a PostgreSQL database. Internet calling uses WebRTC or a compatible SIP/VoIP service; calls to ordinary phone numbers and inbound calls to provisioned virtual numbers route through a compatible PSTN/SIP telecom provider. Firebase Cloud Messaging delivers push notifications for incoming calls and messages. All telecom API credentials live on the backend and are never shipped inside the Android application.

Actors. The accepted active-human catalog is closed and consists of three personas: the Anonymous Explorer, the Virtual Number Subscriber, and the Caller. Non-human actors are the telecom provider (number inventory, PSTN/SIP routing, charges, verification mandates), Firebase Cloud Messaging (push delivery), and the Android native phone service (SIM-based cellular calls and emergency-call handling).

Accepted behavior. Users browse the seven supported countries with dialing codes and truthful provider availability; review per-country number details (available numbers, incoming/outgoing/SMS support, pricing, verification requirements, expiration); select, activate, manage, or release numbers (multiple numbers where the provider permits); place and receive app-to-app audio calls and calls to regular mobile and landline numbers; use the dial pad, contacts, call history, voicemail, call forwarding, call blocking, conference calling, and messaging where supported; and manage usage/credit, privacy and security settings, and dark/light mode. Demo mode provides demo numbers and clearly labeled simulated calls and messages.

Ownership. The application owns the user-facing surfaces listed in §2c. The telecom provider owns number inventory, legal supply confirmation, PSTN/SIP routing, charge amounts, and any identity-verification mandate. The Android native phone service owns SIM-based cellular calls and emergency-call handling. Firebase Cloud Messaging owns push delivery.

Narrow exclusions. FreeConnect does not generate fake real-world phone numbers or claim unsupported availability; does not promise number availability or SMS verification for WhatsApp or other third-party platforms; does not route emergency calls through an unsupported VoIP system; does not pretend that demo calls connect to real telephone networks; and does not advertise real international calling as free unless the provider explicitly offers it for free.

2a. Product Interpretation and Delivery Boundary

Delivery. The current delivery is the complete Android project with source code, UI components, backend API structure, demo mode, telecom integration interfaces, installation instructions, and a testing guide. The Android app is the primary client; the backend is the single shared service that holds telecom credentials, mediates provider calls, and persists durable state.

Access ownership. FreeConnect has no mandatory login. The Landing surface is anonymous and public. Home, the country selector, Keypad, Contacts, Messages, the incoming-call screen, the active-call screen, call history, the voicemail inbox, and Settings are reachable without an account. The virtual-number dashboard and the number-management page require an established identity because they bind durable, provider-committed state (an activated number, its charges, its expiration, and its verification obligations) to a specific person who must be able to resume and manage it. Account Recovery is the optional surface where a user chooses to protect that durable state; identity verification is required only when the provider or applicable law mandates it.

Current vs. future. Everything in §3 is current. No future-horizon requirements are asserted in the authoritative thread; anything not stated there is out of scope rather than deferred.

2b. Source Content Inventory

Not applicable — no reference directive in this project declares content_source.

2c. Page Content and Component Coverage

Landing

• Information/state: Product name FreeConnect; a plain-language explanation of virtual numbers, internet-based calling, and calling regular mobile and landline numbers; the seven supported destinations with their dialing codes; a clear statement that the prototype is free to explore without login; a clear statement that demo calls and messages are simulated and do not connect to real telephone networks; a clear statement that real international calling is not advertised as free unless the provider explicitly offers it for free.
• Primary action: Enter the app (Get a number / Explore FreeConnect) — anonymous, no account required.
• Supporting actions: View the supported-country list; read the demo-mode disclosure; read the no-mandatory-login disclosure.
• Domain entities: Supported country (name, flag, dialing code), demo-mode disclosure, provider-availability disclaimer.
• Component responsibilities: Hero stage with the wireframe globe and seven labeled country nodes; flush-left headline; cyan-outlined primary CTA; magenta "Demo mode — simulated calls" pill; glass status panel with HUD micro-labels.
• States: Loading — globe field and country nodes render progressively. Empty — not applicable (static entry content). Success — user enters Home anonymously. Error — if the country list cannot be fetched, show the static seven-country list with dialing codes and a "availability will be confirmed in-app" note; never fabricate availability. Recovery — retry fetch; the entry CTA remains usable.

Home

• Information/state: The user's active virtual number (or a prompt to get one); credit gauge; recent calls; the seven supported countries as ruled rows with flag, name, dialing code, and a status pill; a three-dot HUD capability strip (IN · OUT · SMS) per country where each dot is lit cyan, struck through, or replaced by the literal text "Currently unavailable"; a permanent right-aligned call-state chip reading IDLE / CONNECTING / LIVE mm:ss in tabular mono.
• Primary action: Open the country selector to browse availability.
• Supporting actions: Open the virtual-number dashboard; open the number-management page; open call history; open the Keypad; open Settings.
• Domain entities: Supported country, virtual number, credit balance, call record, capability flags (incoming, outgoing, SMS).
• Component responsibilities: Wireframe globe hero with seven labeled nodes and cyan signal arcs; country rows as ruled horizontal bands (horizontally scrollable snapping chips on mobile); floating glass panels for active number, credit gauge, and recent calls; floating glass bottom-nav dock with a cyan live-indicator notch.
• States: Loading — skeleton rows and a dimmed globe. Empty — no active number: show "Get a number" prompt and demo-mode disclosure. Success — active number, credit, and recent calls render. Error — provider availability fetch fails: show "Currently unavailable" for affected countries and a retry affordance; never substitute fabricated numbers. Recovery — retry; cached last-known availability is shown with a stale marker.

country selector

• Information/state: The seven supported destinations — India (+91), Pakistan (+92), Bangladesh (+880), United Kingdom (+44), United States (+1), Dubai/United Arab Emirates (+971), Iran (+98) — each with flag, name, and international dialing code; per-country provider availability; the literal text "Currently unavailable" where the provider cannot legally supply numbers.
• Primary action: Select a country to view its virtual-number details.
• Supporting actions: Search/filter the country list; return to Home.
• Domain entities: Supported country, dialing code, provider availability status.
• Component responsibilities: Ruled country bands with flag glyphs and dialing codes; availability status pill; three-dot HUD capability strip; empty/unavailable treatment.
• States: Loading — skeleton bands. Empty — no countries returned: show the static seven-country list with dialing codes and "Currently unavailable" for each, plus retry. Success — availability renders per country. Error — fetch failure: show "Currently unavailable" and retry; never generate fake numbers. Recovery — retry fetch; last-known availability shown with a stale marker.

virtual-number dashboard

• Information/state: For the selected country: available numbers from the provider; whether incoming calls, outgoing calls, and SMS are supported; pricing; verification requirements; number expiration; the user's currently held numbers for that country.
• Primary action: Proceed to select a number (opens the number-management page).
• Supporting actions: Switch country; review pricing and verification requirements; review expiration; return to the country selector.
• Domain entities: Virtual number, capability flags (incoming, outgoing, SMS), price/tariff, verification requirement, expiration date, provider availability.
• Component responsibilities: Per-country detail panel; capability strip; pricing and tariff block in tabular mono; verification-requirement block; expiration block; "Currently unavailable" treatment; provider-charge disclosure.
• States: Loading — skeleton detail panel. Empty — no numbers available for the country: show "Currently unavailable" and the reason category if the provider supplies one. Success — numbers, capabilities, pricing, verification, and expiration render. Error — provider detail fetch fails: show "Currently unavailable" with retry; never fabricate numbers or prices. Recovery — retry; last-known detail shown with a stale marker.

number-management page

• Information/state: The user's held virtual numbers with country, number in tabular mono, capability flags, activation status, expiration, and applicable provider charges; the provider's actual charges displayed before any paid activation; verification requirements where the provider or applicable law mandates them; the multiple-number allowance as permitted by the provider.
• Primary action: Activate a selected number after reviewing the displayed provider charges.
• Supporting actions: Select a number; manage an active number (rename/label, view details); release a number; add an additional number where the provider permits; complete provider-mandated identity verification.
• Domain entities: Virtual number, activation status, provider charge, verification requirement, expiration, multiple-number allowance.
• Component responsibilities: Held-number list; activation confirmation panel showing actual provider charges before confirmation; verification step; release action with destructive magenta treatment; multiple-number affordance gated by provider permission.
• States: Loading — skeleton list. Empty — no held numbers: prompt to browse the country selector. Success — activation confirmed, number appears as active with expiration and charges recorded. Error — activation rejected by the provider (unavailable, verification failed, charge declined): show the provider's reason and leave the number unactivated. Recovery — retry activation; complete verification; choose a different number.

Keypad

• Information/state: Composed number in IBM Plex Mono with its detected country flag and dialing code resolved live; call-type indicator distinguishing internet-based (app-to-app / VoIP) from regular mobile/landline (PSTN) calling; a clear indication when the composed destination is a demo/simulated call.
• Primary action: Place the call.
• Supporting actions: Enter digits; delete a digit; paste a number; pick a contact; switch between internet-based and regular calling; trigger the native phone service for emergency numbers.
• Domain entities: Dialed number, detected country and dialing code, call type (VoIP / PSTN / simulated), validation result.
• Component responsibilities: 64px circular dial keys with monospace numerals and a 90ms inner glow on press; composed-number display with live country resolution; number validation feedback; call-type selector; emergency-call handoff to the native phone service.
• States: Loading — not applicable (local input). Empty — no digits entered: show the dial pad and the last-dialed number. Success — number validated and the call is placed, opening the active-call screen. Error — invalid number for the selected country: show a validation message and keep the composed digits editable. Recovery — correct the digits and retry; emergency numbers hand off to the native phone service instead of the VoIP path.

Contacts

• Information/state: The user's contact list with names and numbers; an indicator of which contacts are reachable app-to-app.
• Primary action: Call a contact.
• Supporting actions: Search contacts; open a contact's detail; start a message to a contact; add or edit a contact.
• Domain entities: Contact (name, number, app-to-app reachability).
• Component responsibilities: Contact list rows; search field; call and message actions per row; contact detail panel.
• States: Loading — skeleton rows. Empty — no contacts: prompt to add a contact or dial a number directly. Success — contacts render and a call or message starts. Error — contact load failure: show retry. Recovery — retry; dial the number manually from the Keypad.

Messages

• Information/state: Message threads with the user's virtual numbers as the sending/receiving identity where SMS is supported; a clear "SIMULATED — no PSTN connection" label on any simulated message; a clear indication when SMS is not supported for a given number or country.
• Primary action: Send a message.
• Supporting actions: Open a thread; compose a new message; select the sending virtual number; view delivery status.
• Domain entities: Message thread, message, sending virtual number, SMS support flag, simulated flag.
• Component responsibilities: Thread list; conversation view; composer; sending-number selector; simulated-message hatch band and HUD label; unsupported-SMS treatment.
• States: Loading — skeleton threads. Empty — no threads: prompt to start a message. Success — message sent and delivery status shown. Error — SMS unsupported for the selected number or country: show the unsupported state and offer an app-to-app message instead where available. Recovery — retry send; switch sending number.

incoming-call screen

• Information/state: Caller identity or number; the receiving virtual number; whether the call is a real PSTN/SIP-routed call or a simulated demo call; a pulsing magenta ring for the incoming state.
• Primary action: Answer the call.
• Supporting actions: Decline the call; send to voicemail; block the caller.
• Domain entities: Incoming call, caller identity, receiving virtual number, simulated flag.
• Component responsibilities: Full-screen incoming-call treatment; pulsing magenta ring at 1.4s; answer/decline controls; block action; simulated-call hatch band and "SIMULATED — no PSTN connection" label where applicable.
• States: Loading — not applicable. Empty — not applicable. Success — call answered and the active-call screen opens. Error — call setup fails or the network drops: show the failure and return to Home. Recovery — the caller may retry; the missed call appears in call history.

active-call screen

• Information/state: Call duration in tabular mono counting up; call status (CONNECTING / LIVE / ON HOLD); applicable charges; the active virtual number; mute, speaker, and hold states.
• Primary action: End the call.
• Supporting actions: Mute; toggle speaker; hold; resume; add a participant for conference calling; start call forwarding; view the running charge.
• Domain entities: Active call, duration, status, applicable charge, mute/speaker/hold state, conference participants.
• Component responsibilities: Duration and status display in IBM Plex Mono tabular; mute/speaker/hold/end controls; charge readout; conference-calling control; call-forwarding control; simulated-call hatch band where applicable; reconnection indicator.
• States: Loading — CONNECTING state with a live-indicator. Empty — not applicable. Success — LIVE with duration counting up and charges accruing. Error — network interruption: show a reconnecting state and attempt reconnection; if reconnection fails, end the call and record it in call history. Recovery — automatic reconnection after network interruptions; the user may also end and redial.

call history

• Information/state: Chronological call records with direction (incoming/outgoing/missed), counterparty, the virtual number used, duration, status, and applicable charges; missed calls marked in magenta; simulated calls marked with the hatch band and HUD label.
• Primary action: Call back from a history entry.
• Supporting actions: Filter by direction or number; open a record's detail; block a number; delete a record.
• Domain entities: Call record (direction, counterparty, virtual number, duration, status, charge, simulated flag).
• Component responsibilities: Ruled history bands; direction and missed-call markers; duration and charge in tabular mono; call-back action; block action; simulated-call treatment.
• States: Loading — skeleton bands. Empty — no calls: show an empty state with a prompt to place a first call. Success — records render and call-back works. Error — history load failure: show retry. Recovery — retry; records remain available offline from local cache where present.

voicemail inbox

• Information/state: Voicemail messages with caller, receiving virtual number, timestamp, and duration; playback state; simulated voicemail marked with the hatch band and HUD label.
• Primary action: Play a voicemail.
• Supporting actions: Call back the caller; delete a voicemail; mark as read; configure call forwarding to voicemail.
• Domain entities: Voicemail message (caller, receiving number, timestamp, duration, playback state).
• Component responsibilities: Voicemail list; playback control; call-back action; delete action; call-forwarding configuration entry point.
• States: Loading — skeleton list. Empty — no voicemail: show an empty state. Success — voicemail plays and its state updates. Error — playback failure: show the error and allow retry. Recovery — retry playback; call back the caller directly.

Settings

• Information/state: Usage and credit dashboard (balance, usage, applicable charges); privacy and security settings; dark mode / light mode toggle; the notice that reinstalling the app or clearing its data may remove locally stored anonymous settings; the anonymous user ID for the current session; the optional secure backup and account recovery entry point; call-forwarding and call-blocking configuration.
• Primary action: Toggle dark/light mode.
• Supporting actions: Open the usage and credit dashboard; open privacy and security settings; open Account Recovery; configure call forwarding; manage blocked numbers; read the local-data-loss notice.
• Domain entities: Credit balance, usage record, theme preference, privacy/security setting, anonymous user ID, blocked number, forwarding rule.
• Component responsibilities: Settings sections; credit gauge; theme toggle; privacy and security controls; local-data-loss notice; Account Recovery entry point; call-forwarding and call-blocking controls.
• States: Loading — skeleton sections. Empty — no usage yet: show a zeroed credit gauge and a prompt to explore demo mode. Success — settings apply immediately and persist locally. Error — settings persistence failure: show the error and keep the previous value. Recovery — retry; the local-data-loss notice explains that clearing data removes locally stored anonymous settings.

Account Recovery

• Information/state: A plain-language explanation of optional secure backup and account recovery; what durable state is protected (held virtual numbers, call history, preferences); the statement that identity verification is required only when mandated by the provider or applicable law; the current verification status.
• Primary action: Enable optional secure backup and account recovery.
• Supporting actions: Recover an existing backed-up state; complete provider-mandated identity verification; decline backup and continue anonymously.
• Domain entities: Backup enrollment, recovery credential, identity-verification requirement, durable state reference.
• Component responsibilities: Backup enrollment flow; recovery flow; verification step shown only when mandated; decline path that returns the user to anonymous use.
• States: Loading — skeleton. Empty — no backup configured: show the enrollment prompt and the decline option. Success — backup enabled or state recovered. Error — verification or recovery failure: show the provider's reason and allow retry. Recovery — retry verification; continue anonymously without backup.

3. Functional Requirements

Each requirement is a distinct story point with provenance, lifecycle facts, and observable acceptance.

FR-1 — Explore without an account (explicit) As an Anonymous Explorer, I should be able to open FreeConnect and explore it without creating an account, so that I can understand the app before committing to anything.

• Trigger: app launch. Input: none. Observable result: the Landing surface renders and the user can enter Home anonymously.
• Access state: anonymous, no account required.
• Failure/recovery: if the country list cannot be fetched, the static seven-country list with dialing codes is shown and the entry CTA remains usable.
• Continuation: the user proceeds to Home or the country selector.

FR-2 — Anonymous user ID for the initial session (required_inference) As an Anonymous Explorer, I should receive an anonymous user ID for my initial session, so that my session state is coherent without an account.

• Trigger: first entry into the app. Input: none. Observable result: an anonymous user ID exists for the session and is visible in Settings.
• Access state: anonymous.
• Failure/recovery: if ID generation fails, the session continues with a locally generated identifier and the user is informed.
• Continuation: the ID is used for the session's local state.

FR-3 — Local storage of demo preferences (required_inference) As an Anonymous Explorer, I should have my demo preferences stored locally, so that my exploration choices persist between sessions on the same device.

• Trigger: changing a demo preference. Input: preference change. Observable result: the preference persists locally and is restored on next launch.
• Access state: anonymous.
• Failure/recovery: if local persistence fails, the preference applies for the current session and the user is informed.
• Continuation: preferences continue to apply.

FR-4 — Local-data-loss notice (required_inference) As an Anonymous Explorer, I should be told that reinstalling the app or clearing its data may remove locally stored anonymous settings, so that I understand the durability of my anonymous state.

• Trigger: viewing Settings or the anonymous-state explanation. Input: none. Observable result: the notice is displayed in plain language.
• Access state: anonymous.
• Failure/recovery: not applicable (static disclosure).
• Continuation: the user may choose optional secure backup.

FR-5 — Optional secure backup and account recovery (required_inference) As an Anonymous Explorer, I should be able to optionally enable secure backup and account recovery, so that my durable state survives reinstall or data clearing.

• Trigger: choosing to enable backup from Account Recovery. Input: backup enrollment and, where mandated, identity verification. Observable result: durable state is backed up and recoverable.
• Access state: anonymous entry to Account Recovery; identity verification only when mandated by the provider or applicable law.
• Failure/recovery: if verification or recovery fails, the provider's reason is shown and the user may retry or continue anonymously.
• Continuation: the user continues with protected durable state, or declines and continues anonymously.

FR-6 — Identity verification only when mandated (explicit) As a Virtual Number Subscriber, I should be asked for identity verification only when the provider or applicable law mandates it, so that I am not burdened with unnecessary verification.

• Trigger: provider or legal mandate for a specific number or country. Input: the mandated verification evidence. Observable result: verification is requested only in the mandated case and its outcome is shown.
• Access state: the user's current identity state; verification is scoped to the mandated requirement.
• Failure/recovery: if verification fails, the provider's reason is shown and the number is not activated.
• Continuation: the user completes verification and proceeds, or chooses a different number.

FR-7 — Country availability display (explicit) As a Virtual Number Subscriber, I should see virtual number availability for India (+91), Pakistan (+92), Bangladesh (+880), the United Kingdom (+44), the United States (+1), Dubai/United Arab Emirates (+971), and Iran (+98), so that I know which destinations are offered.

• Trigger: opening the country selector. Input: none. Observable result: the seven destinations render with flag, name, and international dialing code.
• Access state: anonymous.
• Failure/recovery: if availability cannot be fetched, the static seven-country list renders with dialing codes and "Currently unavailable" for each, with retry.
• Continuation: the user selects a country.

FR-8 — Truthful provider availability (explicit) As a Virtual Number Subscriber, I should see only numbers that the selected telecom provider can legally supply, and "Currently unavailable" where numbers for a country are unavailable, so that I am never misled.

• Trigger: viewing a country or its number details. Input: provider availability response. Observable result: available numbers are shown only when the provider supplies them; otherwise the literal text "Currently unavailable" is shown.
• Access state: anonymous for browsing; identity required for the dashboard and management surfaces.
• Failure/recovery: on provider fetch failure, "Currently unavailable" is shown with retry; no fabricated numbers are ever substituted.
• Continuation: the user browses another country or retries.

FR-9 — No fabricated real-world numbers (explicit) As a Virtual Number Subscriber, I should never be shown generated fake real-world phone numbers or unsupported availability claims, so that I can trust the inventory.

• Trigger: any number display. Input: provider inventory. Observable result: every displayed number originates from the provider; demo numbers are labeled as demo.
• Access state: any.
• Failure/recovery: if inventory is unavailable, "Currently unavailable" is shown instead of any substitute.
• Continuation: the user proceeds with provider-supplied numbers only.

FR-10 — Per-country number details (explicit) As a Virtual Number Subscriber, I should see, for each country, the available numbers from the provider and whether incoming calls, outgoing calls, and SMS are supported, so that I can judge fitness for my needs.

• Trigger: selecting a country. Input: provider detail response. Observable result: available numbers and the incoming/outgoing/SMS capability flags render.
• Access state: identity required (virtual-number dashboard).
• Failure/recovery: on fetch failure, "Currently unavailable" with retry.
• Continuation: the user proceeds to select a number.

FR-11 — Pricing, verification requirements, and expiration (explicit) As a Virtual Number Subscriber, I should see pricing, verification requirements, and number expiration for virtual numbers, so that I understand the cost and obligations before committing.

• Trigger: viewing a country's number details. Input: provider pricing and requirement data. Observable result: pricing, verification requirements, and expiration render in tabular mono.
• Access state: identity required (virtual-number dashboard).
• Failure/recovery: on fetch failure, the detail is shown as unavailable with retry; no invented prices.
• Continuation: the user proceeds to select or declines.

FR-12 — Select, activate, manage, or release numbers (explicit) As a Virtual Number Subscriber, I should be able to select, activate, manage, or release virtual numbers, so that I control which numbers I hold.

• Trigger: choosing a number and an action. Input: number selection and action choice. Observable result: the number's state changes to active, managed, or released, and the change is reflected in the held-number list.
• Access state: identity required (number-management page).
• Failure/recovery: if the provider rejects the action, the provider's reason is shown and the number's state is unchanged.
• Continuation: the user manages another number or returns to the dashboard.

FR-13 — Multiple numbers where permitted (explicit) As a Virtual Number Subscriber, I should be able to hold multiple virtual numbers if the provider permits it, so that I can serve several destinations.

• Trigger: adding an additional number. Input: provider multiple-number allowance. Observable result: an additional number is added when the provider permits; otherwise the allowance limit is shown.
• Access state: identity required (number-management page).
• Failure/recovery: if the provider does not permit another number, the limit and its reason are shown.
• Continuation: the user manages the held numbers.

FR-14 — Provider charges before activation (explicit) As a Virtual Number Subscriber, I should see the actual provider charges before I activate a paid telecom service, so that I consent to the real cost.

• Trigger: initiating activation. Input: provider charge data. Observable result: the actual provider charges are displayed before the activation is confirmed.
• Access state: identity required (number-management page).
• Failure/recovery: if charges cannot be retrieved, activation is blocked until they are shown.
• Continuation: the user confirms or cancels activation.

FR-15 — No WhatsApp or third-party platform promises (explicit) As a Virtual Number Subscriber, I should not be promised number availability or SMS verification for WhatsApp or other third-party platforms, so that I am not misled about third-party support.

• Trigger: any number or SMS presentation. Input: none. Observable result: no availability or SMS-verification claim is made for WhatsApp or any third-party platform.
• Access state: any.
• Failure/recovery: not applicable (prohibition).
• Continuation: the user relies only on the stated provider capabilities.

FR-16 — Internet-based voice calls over Wi-Fi or mobile data (explicit) As a Caller, I should be able to make and receive voice calls over Wi-Fi or mobile data, so that I can talk without cellular minutes.

• Trigger: placing or receiving a call. Input: dialed number or incoming call. Observable result: the call connects over the data network and the active-call screen shows LIVE with duration counting up.
• Access state: anonymous for placing and receiving; the receiving virtual number must be provisioned for inbound calls.
• Failure/recovery: on network interruption, a reconnecting state is shown and reconnection is attempted; if it fails, the call ends and is recorded in call history.
• Continuation: the user continues the call or redials.

FR-17 — App-to-app audio calls (explicit) As a Caller, I should be able to make app-to-app audio calls, so that I can talk to other FreeConnect users directly.

• Trigger: calling a contact reachable app-to-app. Input: contact selection. Observable result: the app-to-app call connects and the active-call screen shows LIVE.
• Access state: anonymous.
• Failure/recovery: if the peer is unreachable, the failure is shown and the call is recorded as failed in call history.
• Continuation: the user retries or calls a regular number instead.

FR-18 — Interactive dial pad and contact list (explicit) As a Caller, I should have an interactive dial pad and a contact list, so that I can place calls quickly.

• Trigger: opening the Keypad or Contacts. Input: digits or contact selection. Observable result: the composed number appears in tabular mono with its detected country flag and dialing code resolved live; selecting a contact populates the call target.
• Access state: anonymous.
• Failure/recovery: invalid numbers show a validation message and remain editable.
• Continuation: the user places the call.

FR-19 — Incoming-call notifications and call history (explicit) As a Caller, I should receive incoming-call notifications and have a call history, so that I do not miss calls and can review them.

• Trigger: an inbound call or a completed call. Input: provider/FCM event. Observable result: the incoming-call screen appears with a pulsing magenta ring; the call is recorded in call history with direction, counterparty, duration, status, and charge.
• Access state: anonymous.
• Failure/recovery: if the notification cannot be delivered, the missed call still appears in call history.
• Continuation: the user answers, declines, or calls back from history.

FR-20 — Mute, speaker, hold, and end-call controls (explicit) As a Caller, I should have mute, speaker, hold, and end-call controls during a call, so that I can manage the conversation.

• Trigger: an active call. Input: control taps. Observable result: the corresponding state changes and is reflected on the active-call screen.
• Access state: anonymous.
• Failure/recovery: if a control cannot be applied, the previous state is retained and the failure is shown.
• Continuation: the call continues with the applied state.

FR-21 — WebRTC or compatible SIP/VoIP service (explicit) As a Caller, I should have internet calling delivered through WebRTC or a compatible SIP/VoIP service, so that the calling path is a real, supported VoIP implementation.

• Trigger: any internet-based call. Input: none. Observable result: the call is carried over WebRTC or the compatible SIP/VoIP service.
• Access state: anonymous.
• Failure/recovery: if the VoIP service is unavailable, the call fails with a clear message and is recorded.
• Continuation: the user retries.

FR-22 — Background calls and reconnection (explicit) As a Caller, I should have background calls and reconnection after network interruptions, so that a call survives leaving the app or a brief network drop.

• Trigger: backgrounding the app or a network interruption during a call. Input: none. Observable result: the call continues in the background and reconnects after an interruption, with a reconnecting indicator.
• Access state: anonymous.
• Failure/recovery: if reconnection fails, the call ends and is recorded in call history.
• Continuation: the user continues the call or redials.

FR-23 — Call regular mobile and landline numbers (explicit) As a Caller, I should be able to call regular mobile and landline numbers, so that I can reach people who are not on FreeConnect.

• Trigger: dialing a regular number. Input: dialed number. Observable result: the call routes through the compatible PSTN/SIP telecom provider and the active-call screen shows duration, status, and applicable charges.
• Access state: anonymous for dialing; a provider with outgoing PSTN connectivity is required for calls from a virtual number to ordinary phone numbers.
• Failure/recovery: if the provider lacks outgoing PSTN connectivity for the route, the call fails with a clear reason and is recorded.
• Continuation: the user retries or chooses another number.

FR-24 — International dialing codes and number validation (explicit) As a Caller, I should have international dialing code support and number validation, so that I dial correctly across countries.

• Trigger: entering a number. Input: digits. Observable result: the detected country flag and dialing code resolve live and the number is validated before the call is placed.
• Access state: anonymous.
• Failure/recovery: invalid numbers show a validation message and remain editable.
• Continuation: the user corrects the number and places the call.

FR-25 — Incoming calls to provisioned virtual numbers (explicit) As a Virtual Number Subscriber, I should receive incoming calls to my provisioned virtual numbers, so that my numbers are genuinely reachable.

• Trigger: an inbound call to a provisioned number. Input: provider/SIP event. Observable result: the incoming-call screen appears showing the caller and the receiving virtual number.
• Access state: the receiving number must be provisioned and active.
• Failure/recovery: if the number is not provisioned or the route fails, the call does not connect and the missed call is recorded.
• Continuation: the user answers, declines, or sends to voicemail.

FR-26 — PSTN/SIP routing (explicit) As a Caller, I should have calls routed through a compatible PSTN/SIP telecom provider, so that regular phone numbers are reachable.

• Trigger: placing a call to a regular number. Input: none. Observable result: the call is routed through the compatible PSTN/SIP provider.
• Access state: anonymous; provider connectivity required.
• Failure/recovery: if the provider route is unavailable, the call fails with a clear reason.
• Continuation: the user retries.

FR-27 — Call duration, status, and applicable charges (explicit) As a Caller, I should see call duration, call status, and applicable charges, so that I know what the call costs and how it is progressing.

• Trigger: an active call. Input: none. Observable result: duration counts up in tabular mono, status shows CONNECTING/LIVE/ON HOLD, and applicable charges are displayed.
• Access state: anonymous.
• Failure/recovery: if charge data is unavailable, the charge readout shows unavailable rather than a fabricated amount.
• Continuation: the call continues and the final charge is recorded in call history.

FR-28 — Emergency-call handling through the native phone service (explicit) As a Caller, I should have emergency calls handled through the appropriate native phone service, so that emergency calls are never routed through an unsupported VoIP system.

• Trigger: dialing an emergency number. Input: emergency digits. Observable result: the call is handed off to the Android native phone service; it is not placed over VoIP.
• Access state: anonymous.
• Failure/recovery: if the native phone service is unavailable, the user is told to use the device's phone app.
• Continuation: the native phone service handles the call.

FR-29 — Normal cellular calls use the device SIM and Android phone services (explicit) As a Caller, I should have normal cellular calls use the device's SIM and Android phone services, so that ordinary cellular calling behaves natively.

• Trigger: placing a normal cellular call. Input: dialed number. Observable result: the call is placed through the device SIM and Android phone services.
• Access state: anonymous.
• Failure/recovery: if the SIM or phone service is unavailable, the user is informed and may use the VoIP path where supported.
• Continuation: the native call proceeds.

FR-30 — SMS and messaging where supported (explicit) As a Caller, I should be able to send and receive SMS and messages where supported, so that I can message from my virtual numbers.

• Trigger: composing a message. Input: recipient, body, sending virtual number. Observable result: the message is sent where SMS is supported and its delivery status is shown; unsupported cases are clearly indicated.
• Access state: anonymous; the sending number must support SMS.
• Failure/recovery: if SMS is unsupported for the selected number or country, the unsupported state is shown and an app-to-app message is offered where available.
• Continuation: the user sends another message or switches sending number.

FR-31 — Voicemail (explicit) As a Caller, I should have voicemail, so that callers can leave messages when I do not answer.

• Trigger: an unanswered call or opening the voicemail inbox. Input: none. Observable result: the voicemail appears in the inbox with caller, receiving number, timestamp, and duration, and can be played.
• Access state: anonymous.
• Failure/recovery: if playback fails, the error is shown and playback can be retried.
• Continuation: the user calls back or deletes the voicemail.

FR-32 — Call forwarding (explicit) As a Caller, I should have call forwarding, so that calls to my numbers can be directed elsewhere.

• Trigger: configuring forwarding. Input: forwarding target and rule. Observable result: the forwarding rule is saved and applied to subsequent calls.
• Access state: anonymous.
• Failure/recovery: if the rule cannot be applied, the previous rule is retained and the failure is shown.
• Continuation: the user adjusts or removes the rule.

FR-33 — Call blocking (explicit) As a Caller, I should have call blocking, so that I can stop unwanted callers.

• Trigger: blocking a number from a call, history, or Settings. Input: the number to block. Observable result: the number is added to the blocked list and subsequent calls from it are blocked.
• Access state: anonymous.
• Failure/recovery: if the block cannot be saved, the previous state is retained and the failure is shown.
• Continuation: the user manages the blocked list.

FR-34 — Conference calling (explicit) As a Caller, I should have conference calling, so that I can talk with more than one participant.

• Trigger: adding a participant during an active call. Input: participant selection. Observable result: the participant joins the call and the active-call screen shows the conference state.
• Access state: anonymous.
• Failure/recovery: if a participant cannot join, the failure is shown and the existing call continues.
• Continuation: the conference continues or the user ends it.

FR-35 — Contacts and call history (explicit) As a Caller, I should have contacts and call history, so that I can reach people and review past calls.

• Trigger: opening Contacts or call history. Input: none. Observable result: contacts and call records render with their details.
• Access state: anonymous.
• Failure/recovery: on load failure, retry is offered.
• Continuation: the user calls a contact or calls back from history.

FR-36 — Dark mode and light mode (explicit) As a Caller, I should have dark mode and light mode, so that the app is comfortable in any lighting.

• Trigger: toggling the theme in Settings. Input: theme choice. Observable result: the theme switches immediately and persists locally.
• Access state: anonymous.
• Failure/recovery: if the preference cannot be persisted, the theme applies for the session and the user is informed.
• Continuation: the chosen theme continues to apply.

FR-37 — Push notifications for incoming calls and messages (explicit) As a Caller, I should receive push notifications for incoming calls and messages, so that I am alerted when the app is not in the foreground.

• Trigger: an inbound call or message. Input: FCM event. Observable result: a push notification is delivered and opens the relevant surface.
• Access state: anonymous.
• Failure/recovery: if the notification cannot be delivered, the event still appears in call history or the message thread.
• Continuation: the user opens the notification and responds.

FR-38 — Usage and credit dashboard (explicit) As a Virtual Number Subscriber, I should have a usage and credit dashboard, so that I can track my balance and consumption.

• Trigger: opening the dashboard from Settings. Input: none. Observable result: balance, usage, and applicable charges render, with the credit gauge.
• Access state: anonymous.
• Failure/recovery: if usage data cannot be fetched, the last-known values are shown with a stale marker and retry.
• Continuation: the user reviews usage and returns to Settings.

FR-39 — Privacy and security settings (explicit) As a Virtual Number Subscriber, I should have privacy and security settings, so that I can control my data and account protection.

• Trigger: opening privacy and security settings. Input: setting changes. Observable result: the settings apply and persist.
• Access state: anonymous.
• Failure/recovery: if a setting cannot be saved, the previous value is retained and the failure is shown.
• Continuation: the user continues using the app with the applied settings.

FR-40 — Demo numbers and simulated calls (explicit) As an Anonymous Explorer, I should have demo numbers and simulated calls, so that I can explore the app's calling experience without a paid telecom service.

• Trigger: entering demo mode. Input: none. Observable result: demo numbers are available and simulated calls can be placed.
• Access state: anonymous.
• Failure/recovery: if demo mode is unavailable, the user is informed and may still browse countries and number details.
• Continuation: the user explores further or exits demo mode.

FR-41 — Clear labeling of simulated calls and messages (explicit) As an Anonymous Explorer, I should have simulated calls and messages clearly labeled, so that I never mistake them for real connections.

• Trigger: any simulated call or message. Input: none. Observable result: a magenta diagonal-hatch band and the HUD label "SIMULATED — no PSTN connection" appear on the call or message card in both light and dark mode.
• Access state: anonymous.
• Failure/recovery: not applicable (mandatory labeling).
• Continuation: the user continues exploring.

FR-42 — Demo calls do not pretend to connect to real networks (explicit) As an Anonymous Explorer, I should never be led to believe that demo calls connect to real telephone networks, so that my expectations stay accurate.

• Trigger: any simulated call. Input: none. Observable result: the simulated state is unmistakable and no real-network connection is implied.
• Access state: anonymous.
• Failure/recovery: not applicable (prohibition).
• Continuation: the user explores further.

FR-43 — No free-international-calling claim (explicit) As a Virtual Number Subscriber, I should not see real international calling advertised as free unless the provider explicitly offers it for free, so that pricing expectations are honest.

• Trigger: any pricing or marketing presentation. Input: provider pricing. Observable result: real international calling is presented with its actual provider charges unless the provider explicitly offers it free.
• Access state: any.
• Failure/recovery: not applicable (prohibition).
• Continuation: the user reviews actual charges before activating.

FR-44 — Telecom API credentials on the backend (explicit) As a Virtual Number Subscriber, I should have telecom API credentials kept on the backend and never in the Android application, so that provider access is not exposed on the device.

• Trigger: any provider interaction. Input: none. Observable result: the Android app calls the backend, which holds the credentials and mediates the provider request.
• Access state: any.
• Failure/recovery: if the backend cannot reach the provider, the failure is surfaced to the user without exposing credentials.
• Continuation: the user retries.

FR-45 — Bottom navigation (explicit) As a Caller, I should have bottom navigation with Home, Keypad, Contacts, Messages, and Settings, so that I can move between the main areas quickly.

• Trigger: tapping a navigation item. Input: tab selection. Observable result: the selected destination opens and the cyan live-indicator notch slides to the active tab.
• Access state: anonymous.
• Failure/recovery: not applicable (navigation).
• Continuation: the user continues in the selected destination.

FR-46 — Complete deliverables (explicit) As a Virtual Number Subscriber, I should receive the complete Android project, source code, UI components, backend API structure, demo mode, telecom integration interfaces, installation instructions, and testing guide, so that the product can be built, run, and verified.

• Trigger: project delivery. Input: none. Observable result: all listed artifacts are present and the installation instructions and testing guide are usable.
• Access state: not applicable.
• Failure/recovery: missing artifacts are reported and supplied.
• Continuation: the project can be installed and tested.

4. User Personas

Anonymous Explorer

Product context. The Anonymous Explorer opens FreeConnect for the first time with no account and no commitment. They may have heard about virtual numbers and want to understand what the app actually offers before spending anything. They are the persona the no-mandatory-login constraint exists for.

Primary goal. Understand FreeConnect's virtual-number and calling capabilities without creating an account, and explore demo numbers and simulated calls safely.

Distinct accepted responsibilities. Entering the app anonymously; receiving an anonymous user ID for the initial session; storing demo preferences locally; exploring demo numbers and simulated calls; reading the local-data-loss notice; optionally enabling secure backup and account recovery.

Relevant inputs or decisions. Whether to enter the app; which country to browse; whether to try a demo call; whether to enable optional backup; whether to accept that clearing data removes locally stored anonymous settings.

Interactions with other accepted participants. The Anonymous Explorer interacts with the telecom provider only indirectly (availability and pricing are provider-supplied); with Firebase Cloud Messaging for push notifications; and with the Android native phone service only if they dial an emergency number. They may later become a Virtual Number Subscriber or Caller.

Observable success. The app opens without an account, an anonymous user ID exists for the session, demo preferences persist locally, simulated calls and messages are unmistakably labeled, and the local-data-loss notice is understood.

What makes this role different. The Anonymous Explorer's work is evaluation without commitment: every action must be possible with zero identity, and the app must be honest that anonymous state is local and fragile. This is a different job from holding a number or completing a call.

Virtual Number Subscriber

Product context. The Virtual Number Subscriber wants a reachable number in one or more of the seven supported countries. They care about whether the number can receive calls, make calls, and handle SMS, what it costs, what verification is required, and when it expires. They are price-aware and expect to see real provider charges before committing.

Primary goal. Hold working virtual numbers with clear provider charges and verification obligations.

Distinct accepted responsibilities. Browsing country availability for India, Pakistan, Bangladesh, the UK, the USA, Dubai/UAE, and Iran; reviewing dialing codes, provider-supplied numbers, incoming/outgoing/SMS support, pricing, verification requirements, and expiration; selecting, activating, managing, or releasing numbers; holding multiple numbers where the provider permits; completing identity verification only when mandated; reviewing the usage and credit dashboard; managing privacy and security settings.

Relevant inputs or decisions. Which country and number to choose; whether to accept the displayed provider charges; whether to complete mandated verification; whether to add another number; whether to release a number; whether to enable optional backup.

Interactions with other accepted participants. The Virtual Number Subscriber depends on the telecom provider for inventory, legal supply, charges, and verification mandates; on the backend for credential-safe provider mediation; and on the Caller persona's activity when their provisioned numbers receive inbound calls.

Observable success. Numbers are activated with the actual provider charges shown beforehand, capability flags and expiration are visible, mandated verification is completed only when required, and the usage and credit dashboard reflects consumption.

What makes this role different. The Virtual Number Subscriber's work is procurement and stewardship of a regulated asset: it is governed by provider legality, pricing, verification, and expiration in a way that neither anonymous exploration nor call handling is.

Caller

Product context. The Caller uses FreeConnect to actually talk to people — app-to-app over the internet, or to regular mobile and landline numbers through the PSTN/SIP provider. They may be on Wi-Fi or mobile data, may move in and out of coverage, and need the call to survive that.

Primary goal. Complete calls with visible duration, status, and applicable charges, with emergency calls handled through the native phone service.

Distinct accepted responsibilities. Placing and receiving internet-based app-to-app audio calls; calling regular mobile and landline numbers; using the dial pad, contacts, and international dialing codes with number validation; managing mute, speaker, hold, and end-call controls; receiving incoming-call notifications; reviewing call history; using voicemail, call forwarding, call blocking, and conference calling; sending and receiving SMS and messages where supported; relying on background calls and reconnection; handing emergency calls to the native phone service.

Relevant inputs or decisions. Which number to dial; whether to call app-to-app or over PSTN; whether to answer, decline, or send to voicemail; whether to mute, hold, or add a participant; whether to block a caller; whether to call back from history.

Interactions with other accepted participants. The Caller interacts with the telecom provider for PSTN/SIP routing and charges; with Firebase Cloud Messaging for incoming-call and message notifications; with the Android native phone service for SIM-based cellular calls and emergency calls; and with the Virtual Number Subscriber's provisioned numbers when receiving inbound calls.

Observable success. Calls connect and show LIVE with duration counting up; applicable charges are visible; interruptions trigger reconnection; missed calls appear in history; voicemail is reachable; emergency calls go to the native phone service.

What makes this role different. The Caller's work is real-time session management under network and regulatory constraints: the value is in the live call state, the controls, and the honest charge readout, not in inventory or exploration.

5. Core User Flows

Flow 1 — Anonymous exploration (Anonymous Explorer)

1. The Anonymous Explorer launches FreeConnect. The Landing surface renders with the product explanation, the seven supported destinations and their dialing codes, the no-mandatory-login statement, and the "Demo mode — simulated calls" pill.
2. They tap the cyan-outlined primary CTA. No account is requested. An anonymous user ID is generated for the session.
3. Home opens on the dark stage with the wireframe globe, the seven labeled country nodes, and the country rows with their three-dot HUD capability strips.
4. They open the country selector and browse India (+91), Pakistan (+92), Bangladesh (+880), the United Kingdom (+44), the United States (+1), Dubai/United Arab Emirates (+971), and Iran (+98). Countries the provider cannot legally supply show the literal text "Currently unavailable."
5. They return to Home and start a demo call. The call is presented with the magenta diagonal-hatch band and the HUD label "SIMULATED — no PSTN connection."
6. They open Settings, see the anonymous user ID, toggle dark or light mode, and read the notice that reinstalling the app or clearing its data may remove locally stored anonymous settings.
7. Failure/recovery: if the country list cannot be fetched, the static seven-country list with dialing codes renders and the entry CTA remains usable; if demo mode is unavailable, they are informed and can still browse countries and number details.
8. Continuation: they may open Account Recovery to optionally enable secure backup, or continue exploring anonymously.

Flow 2 — Browsing country availability and number details (Virtual Number Subscriber)

1. The Virtual Number Subscriber opens the country selector from Home.
2. They select a country, for example the United Kingdom (+44). The virtual-number dashboard opens for that country.
3. The dashboard shows the available numbers from the provider, whether incoming calls, outgoing calls, and SMS are supported, the pricing, the verification requirements, and the number expiration.
4. Failure/recovery: if the provider cannot supply numbers for that country, the dashboard shows "Currently unavailable" with a retry; no fabricated numbers or prices are ever substituted.
5. Continuation: they proceed to the number-management page to select a number, or return to the country selector to compare another destination.

Flow 3 — Selecting, activating, and managing a virtual number (Virtual Number Subscriber)

1. From the virtual-number dashboard, the Virtual Number Subscriber opens the number-management page.
2. They select a number. The page displays the actual provider charges before any paid activation, along with the verification requirements and expiration.
3. If the provider or applicable law mandates identity verification for that number, the verification step is shown; otherwise it is not requested.
4. They confirm activation. The number becomes active and appears in the held-number list with its capability flags, expiration, and recorded charges.
5. Participant response: the telecom provider returns the activation result and the charge; the backend records the durable state bound to the subscriber's identity.
6. Failure/recovery: if the provider rejects the activation (unavailable, verification failed, charge declined), the provider's reason is shown and the number remains unactivated; the subscriber may retry, complete verification, or choose a different number.
7. Continuation: they may add another number where the provider permits, manage an existing number, or release a number. Releasing a number uses the destructive magenta treatment and removes it from the held list.

Flow 4 — Placing an internet-based app-to-app call (Caller)

1. The Caller opens Contacts and selects a contact reachable app-to-app, or opens the Keypad and enters the number.
2. On the Keypad, the composed number appears in IBM Plex Mono with its detected country flag and dialing code resolved live, and the number is validated.
3. They place the call. The active-call screen opens showing CONNECTING, then LIVE with the duration counting up in tabular mono.
4. They use mute, speaker, and hold as needed; each control changes the corresponding state on screen.
5. Failure/recovery: if the network is interrupted, a reconnecting state is shown and reconnection is attempted; if reconnection fails, the call ends and is recorded in call history.
6. Continuation: they end the call; the final duration and applicable charges are recorded in call history.

Flow 5 — Calling a regular mobile or landline number (Caller)

1. The Caller opens the Keypad and enters a regular mobile or landline number, including its international dialing code.
2. The number is validated and the detected country flag and dialing code resolve live. The call-type indicator shows that this is a regular (PSTN) call.
3. They place the call. It routes through the compatible PSTN/SIP telecom provider, and the active-call screen shows duration, status, and applicable charges.
4. Failure/recovery: if the provider lacks outgoing PSTN connectivity for the route, the call fails with a clear reason and is recorded in call history.
5. Continuation: they end the call and review the charge in call history, or redial.

Flow 6 — Receiving an incoming call to a provisioned virtual number (Virtual Number Subscriber and Caller)

1. An inbound call arrives at the Virtual Number Subscriber's provisioned number and is routed through the compatible PSTN/SIP telecom provider.
2. The incoming-call screen appears with the caller identity or number, the receiving virtual number, and a pulsing magenta ring at 1.4s. A push notification is delivered through Firebase Cloud Messaging if the app is not in the foreground.
3. The subscriber answers, declines, or sends the call to voicemail.
4. Participant response: the Caller on the other end experiences the answered call, the decline, or the voicemail greeting.
5. Failure/recovery: if the number is not provisioned or the route fails, the call does not connect and the missed call is recorded in call history.
6. Continuation: if answered, the active-call screen opens; if sent to voicemail, the message appears in the voicemail inbox.

Flow 7 — Managing an active call (Caller)

1. During an active call, the Caller uses mute, speaker, and hold controls on the active-call screen.
2. They may add a participant for conference calling; the participant joins and the conference state is shown.
3. They may configure call forwarding or block the caller.
4. Failure/recovery: if a control cannot be applied, the previous state is retained and the failure is shown; if a conference participant cannot join, the existing call continues.
5. Continuation: they end the call; duration, status, and applicable charges are recorded in call history.

Flow 8 — Emergency call handling (Caller)

1. The Caller dials an emergency number on the Keypad.
2. FreeConnect hands the call off to the Android native phone service. The call is not placed over VoIP.
3. Failure/recovery: if the native phone service is unavailable, the user is told to use the device's phone app.
4. Continuation: the native phone service handles the call.

Flow 9 — Messaging where supported (Caller)

1. The Caller opens Messages and composes a message, selecting the sending virtual number.
2. If SMS is supported for that number and country, the message is sent and its delivery status is shown.
3. Failure/recovery: if SMS is unsupported for the selected number or country, the unsupported state is shown and an app-to-app message is offered where available.
4. Continuation: they send another message or switch the sending number. Any simulated message carries the magenta hatch band and the "SIMULATED — no PSTN connection" label.

Flow 10 — Voicemail, call forwarding, and call blocking (Caller)

1. The Caller opens the voicemail inbox and plays a voicemail, seeing the caller, receiving number, timestamp, and duration.
2. They call back the caller or delete the voicemail.
3. From Settings, they configure call forwarding to a target and manage the blocked-numbers list.
4. Failure/recovery: if playback fails, the error is shown and playback can be retried; if a forwarding rule or block cannot be saved, the previous state is retained and the failure is shown.
5. Continuation: subsequent calls follow the forwarding and blocking rules.

Flow 11 — Reviewing usage, credit, and settings (Virtual Number Subscriber)

1. The Virtual Number Subscriber opens Settings and then the usage and credit dashboard.
2. The dashboard shows the balance, usage, and applicable charges, with the credit gauge.
3. They adjust privacy and security settings and toggle dark or light mode.
4. Failure/recovery: if usage data cannot be fetched, the last-known values are shown with a stale marker and retry; if a setting cannot be saved, the previous value is retained and the failure is shown.
5. Continuation: they return to Settings and continue using the app.

Flow 12 — Optional secure backup and account recovery (Anonymous Explorer / Virtual Number Subscriber)

1. The user opens Account Recovery from Settings.
2. They read what durable state is protected (held virtual numbers, call history, preferences) and that identity verification is required only when mandated by the provider or applicable law.
3. They enable optional secure backup and account recovery, completing verification only if it is mandated.
4. Failure/recovery: if verification or recovery fails, the provider's reason is shown and they may retry or continue anonymously.
5. Continuation: they continue with protected durable state, or decline and continue anonymously with the local-data-loss notice in effect.

6. Visuals Colors and Theme

Muse and headline. The visual direction is Cinematic future-comms — a glowing globe of live lines, after Gleb Kuznetsov. The headline is "Your number, everywhere." The product's real subject matter — signals travelling between countries — is inherently luminous, dark, and three-dimensional, and dark mode is the product's own default request, so the dark ground is a product requirement rather than a stylistic imposition.

Dark mode (default) tokens

Light mode (warm-paper inversion). Ground #F4F6FB, text #0B1020, same cyan #22D3EE and magenta #FF4FD8 accents, so the identity survives the theme switch.

Contrast rules. Never place #22D3EE text on #0E1424 at body size for long copy — cyan is for short labels, numerals, and strokes. Muted #7C8BA8 is used only at 14px+ for labels.

Typography. Headings: Space Grotesk 500/700, tight −0.02em tracking, sentence case for page titles, and ALL-CAPS 11px micro-labels at +0.18em tracking for HUD chrome ("ACTIVE NUMBER", "PER MIN", "PSTN ROUTE"). Headlines are large and wide-set, never centred as a stack of three lines. Body: IBM Plex Sans. Numerals (durations, tariffs, dial codes) always in IBM Plex Mono tabular. Scale: 1.25 modular on a 4px baseline — display 44px mobile → 96px desktop; h1 28/40; h2 20/26; body 15/16; micro-label 11; mono data 13.

Shape language. Thin 1px luminous strokes at 18% white and 40% cyan; panels with 20px radii and a 1px top-edge highlight to read as glass; dial pad keys are perfect circles at 64px with a soft inner glow on press; country rows are ruled horizontal bands, not cards. Circular gauges for credit balance and call duration. No blobs, no soft offset shadows — depth comes from glow and blur, not from drop shadows.

Layout. Full-bleed dark canvas with a persistent bottom navigation dock (Home | Keypad | Contacts | Messages | Settings) rendered as a floating glass bar with a cyan live-indicator notch that slides to the active tab. Home is a country-routed number dashboard: a left column of ruled country rows (flag, name, +code, status pill) and a right column of floating glass panels for the active number, credit gauge, and recent calls. On mobile the columns stack and the country rows become horizontally scrollable chips that snap. Every row is a label/value pair on a visible baseline grid.

Imagery. No stock photography. The visual subject is a generative signal field: a dark globe of thin cyan arcs connecting the seven supported countries, with faint magenta arcs marking unavailable routes. Country rows carry circular flag glyphs and a small HUD capability strip (IN / OUT / SMS) drawn as three tiny labelled dots. Demo/simulated calls carry a magenta diagonal hatch band across the call card.

Readable text and controls. Headlines, wordmarks, labels, numbers, cards' text, and controls stay entirely inside the viewport and their container at 375px, 768px, and 1280px, wrapping or scaling (for example font-size: clamp(...) with its mobile size) to fit. No other element covers any part of them. Imagery, decoration, and motion may be cropped, bled off an edge, rotated, overlapped, or cut as the direction asks, as long as they cover no readable text or control.

7. Signature Design Concept

The live wireframe globe hero. Home opens on a 100vh dark stage (#070A14). The dominant element is a slowly rotating wireframe globe built from layered 2D arcs (canvas/CSS-3D, not WebGL) with seven labelled nodes at India, Pakistan, Bangladesh, the UK, the US, UAE, and Iran. Cyan #22D3EE arcs pulse outward from the user's active number; faint magenta #FF4FD8 arcs mark unavailable routes. The globe bleeds off the right and top edges.

Over it, at the lower-left, an oversized Space Grotesk headline sits flush-left at 44px mobile → 96px desktop reading "Your number, everywhere.", occupying roughly nine columns. A single cyan-outlined CTA "Get a number" is pinned directly beneath it, and a magenta "Demo mode — simulated calls" pill sits above the headline. A glass status panel sits at the lower-right showing the active number in IBM Plex Mono, a credit gauge, and three HUD micro-labels. No text or control is ever overlapped by the globe.

The concept recomposes only accepted content, states, and controls: the seven supported countries, their dialing codes, provider availability, the active number, the credit balance, and the demo-mode disclosure. It introduces no new behavior, page, or destination.

8. Interaction Model & Motion Direction

Interaction Model: Animated Motion Tempo: expressive Hero Dimensionality: layered_2d

Landing Hero Motion Brief

• Focal subject: the generative signal field — a dark globe of thin cyan arcs connecting the seven supported countries, with faint magenta arcs marking unavailable routes.
• Input → transformation → outcome thesis: as the user enters the app and their active number is established, the globe's cyan arcs pulse outward from that number's country node; the outcome is a visible, honest picture of which routes are live and which are unavailable, using only accepted availability and active-number state.
• Motion vocabulary: continuous slow drift of the signal field; a light sweep across glass panels on focus; digits count up when a duration or tariff updates; the cyan live-indicator notch slides between nav tabs with a 240ms cubic-bezier(0.22,1,0.36,1) ease; the incoming-call screen pulses the magenta ring at 1.4s. Nothing bounces.
• Composed first frame: the globe bleeding off the top-right edge, the flush-left 44→96px headline fully inside the viewport, the cyan-outlined CTA directly beneath it, the magenta demo pill above the headline, and the glass status panel at the lower-right with the active number in IBM Plex Mono, a credit gauge, and three HUD micro-labels.
• Reduced-motion state: all decorative motion is disabled under prefers-reduced-motion, leaving a static field and instant state changes. The globe renders as a still composed frame; the nav notch moves without animation; the incoming-call ring is a static magenta ring.

9. Non-Functional Requirements

NFR-1 — HTTPS and secure transport (explicit) All client–backend communication uses HTTPS. Rationale: the source requires HTTPS for security.

NFR-2 — Secure authentication tokens (explicit) Authentication tokens are handled securely, including for the anonymous session and for optional backup/recovery. Rationale: the source requires secure authentication tokens.

NFR-3 — Encrypted sensitive data (explicit) Sensitive data is encrypted at rest and in transit. Rationale: the source requires encrypted sensitive data.

NFR-4 — Abuse prevention (explicit) The system includes abuse prevention controls. Rationale: the source requires abuse prevention.

NFR-5 — Telecom credentials on the backend only (explicit) Telecom API credentials are kept on the backend and never shipped in the Android application. Rationale: explicit source constraint.

NFR-6 — Background calls and reconnection (explicit) Calls continue in the background and reconnect after network interruptions. Rationale: explicit source requirement.

NFR-7 — Push notification delivery (explicit) Firebase Cloud Messaging delivers push notifications for incoming calls and messages. Rationale: explicit source technology choice.

NFR-8 — Truthful availability and pricing (explicit) The system never generates fake real-world phone numbers, never claims unsupported availability, and never advertises real international calling as free unless the provider explicitly offers it for free. Rationale: explicit source constraints.

NFR-9 — Emergency-call safety (explicit) Emergency calls are never routed through an unsupported VoIP system; they are handled through the appropriate native phone service. Rationale: explicit source constraint.

NFR-10 — Readable text and controls at all viewports (required_inference) Headlines, labels, numbers, cards' text, and controls remain entirely inside the viewport and their container at 375px, 768px, and 1280px. Rationale: required for the accepted UI to be usable across the mobile-first audience.

NFR-11 — Theme support (explicit) Dark mode and light mode are both supported, with dark mode as the product's default. Rationale: explicit source requirement plus the creative direction's dark ground.

10. Tech Stack

• Android app: Kotlin + Jetpack Compose (explicit).
• Internet calling: WebRTC or a compatible SIP/VoIP service (explicit).
• Virtual numbers and normal phone network connectivity: a compatible telecom provider with outgoing PSTN connectivity (explicit).
• Backend: Node.js + TypeScript (explicit), delivered as a single shared backend service that holds telecom credentials and mediates provider calls.
• Database: PostgreSQL (explicit).
• Notifications: Firebase Cloud Messaging (explicit).
• Security: HTTPS, secure authentication tokens, encrypted sensitive data, and abuse prevention (explicit).
• Native phone integration: Android native phone service for SIM-based cellular calls and emergency-call handling (explicit).
• Containerization: Docker / docker-compose for the backend and database (Default — not specified by user).

11. Assumptions and Constraints

Assumptions

1. A compatible telecom provider is available for the seven supported destinations and exposes number inventory, capability flags, pricing, verification requirements, expiration, and PSTN/SIP routing through an API the backend can call. (Assumption — provider availability is a source-stated dependency.)
2. Provider availability, pricing, and verification requirements are dynamic and are fetched at runtime rather than hardcoded. (Assumption — required by the truthful-availability constraint.)
3. The Android device has a SIM and Android phone services available for normal cellular calls and emergency-call handling. (Assumption — required by the source constraint.)
4. Demo mode is a first-class, clearly labeled mode that never implies a real network connection. (Assumption — required by the source constraints.)
5. The anonymous user ID is generated on first entry and is sufficient for session coherence without an account. (Assumption — required by the no-mandatory-login constraint.)

Constraints

1. Show only numbers that the selected telecom provider can legally supply; if numbers for a country are unavailable, display "Currently unavailable." (explicit)
2. Do not generate fake real-world phone numbers or claim unsupported availability. (explicit)
3. Do not promise number availability or SMS verification for WhatsApp or other third-party platforms. (explicit)
4. Do not route emergency calls through an unsupported VoIP system; emergency-call handling must go through the appropriate native phone service. (explicit)
5. Normal cellular calls must use the device's SIM and Android phone services. (explicit)
6. Calls from a virtual number to ordinary phone numbers require a provider with outgoing PSTN connectivity. (explicit)
7. Require identity verification only when mandated by the provider or applicable law. (explicit)
8. Do not pretend that demo calls connect to real telephone networks; simulated calls and messages must be clearly labeled. (explicit)
9. Display actual provider charges before users activate paid telecom services. (explicit)
10. Do not advertise real international calling as free unless the provider explicitly offers it for free. (explicit)
11. Keep telecom API credentials on the backend, not in the Android application. (explicit)
12. No mandatory login: users must be able to explore the app without creating an account. (explicit)

12. Glossary

• Anonymous user ID — the identifier generated for a user's initial session so that session state is coherent without an account.
• App-to-app call — an audio call between two FreeConnect users carried over the internet (WebRTC or compatible SIP/VoIP).
• Capability strip (IN · OUT · SMS) — the three-dot HUD indicator on a country row showing whether incoming calls, outgoing calls, and SMS are supported; each dot is lit cyan, struck through, or replaced by the literal text "Currently unavailable."
• Demo mode — the free, no-login exploration mode providing demo numbers and simulated calls and messages, always clearly labeled.
• Dialing code — the international country calling code shown for each supported destination (for example +91 for India).
• HUD micro-label — an ALL-CAPS 11px label at +0.18em tracking used for instrument chrome such as "ACTIVE NUMBER", "PER MIN", "PSTN ROUTE".
• PSTN — the public switched telephone network; calls to regular mobile and landline numbers route through a compatible PSTN/SIP telecom provider.
• Provisioned virtual number — a virtual number that has been activated with the provider and can receive inbound calls.
• Simulated call/message — a demo-mode call or message that does not connect to a real telephone network, marked with a magenta diagonal-hatch band and the HUD label "SIMULATED — no PSTN connection."
• SIP — Session Initiation Protocol; the signaling protocol used by the compatible VoIP/PSTN provider.
• Telecom provider — the external service that supplies virtual numbers, confirms legal supply, routes PSTN/SIP calls, sets charges, and may mandate identity verification.
• Virtual number — a phone number supplied by the telecom provider for one of the seven supported destinations, with its own incoming/outgoing/SMS capabilities, pricing, verification requirements, and expiration.
• VoIP — voice over IP; internet-based calling over Wi-Fi or mobile data.