Mobile App

Purpose

This page documents the mobile application layer of the Maqsafy platform at a high level, including responsibilities, authentication behavior, API communication, offline considerations, and security rules.

Scope

This page is for technical documentation only.
Detailed mobile product requirements should be documented separately if needed.

Mobile App Responsibilities

The mobile application may be responsible for:

• Parent login and authentication
• Student profile access
• Wallet balance display
• Wallet top-up flow
• Order creation
• Pre-order management
• Purchase history
• Notifications
• Student restrictions and spending limits
• Credential-related flows where applicable
• Communication with backend APIs

Main Users

User	Description
Parent	Manages children, wallet, limits, restrictions, orders, and payments
Student	May be represented through parent-managed profiles
School User	If applicable, accesses school-related mobile features
Seller / Cashier	If applicable, uses POS or operational mobile flow

API Communication

The mobile app communicates with backend APIs using HTTPS.

Example authorization header:

Authorization: Bearer <ACCESS_TOKEN>

Authentication Flow

1. User opens the mobile app.
2. User submits login credentials or mobile number.
3. OTP may be required depending on the configured flow.
4. Backend validates the request.
5. The mobile app receives an access token.
6. The mobile app uses the token for protected API requests.

Example Login Request

{
  "mobile": "05XXXXXXXX",
  "password": "********"
}

Example Login Response

{
  "token": "example-access-token",
  "user": {
    "id": 1,
    "name": "Example Parent"
  }
}

Wallet Features

The mobile app may include:

• Wallet balance
• Wallet top-up
• Transaction history
• Refund visibility
• Spending limits
• Student-specific restrictions

Order Features

The mobile app may include:

• Product browsing
• Cart
• Order placement
• Pre-order scheduling
• Order status tracking
• Purchase history

Notifications

The mobile app may receive notifications for:

• Successful top-up
• Order confirmation
• Refund status
• Student purchase activity
• Credential delivery or activation events
• School announcements, where applicable

Offline Considerations

If offline capabilities exist, document them here.

Area	Offline Behavior
Login	TBD
Wallet balance	TBD
Orders	TBD
POS / cashier flow	TBD
Sync behavior	TBD

Credential-Related Notes

If the mobile app handles card or bracelet issuance, sale, activation, or NFC-related flows, document the boundaries clearly.

Rules:

• Dashboard does not scan NFC.
• NFC scanning or tap-to-pay flows should be documented under the relevant mobile or POS component.
• Credential identifiers must not be exposed unnecessarily.
• Credential lifecycle events should be auditable.

Security Rules

• Do not store tokens insecurely.
• Do not expose tokens in logs.
• Do not log OTP values.
• Do not include real user data in examples.
• Use HTTPS for API communication.
• Backend authorization remains mandatory.
• Do not rely only on mobile-side checks.
• Sensitive data must be minimized on the device.

App Store / Release Notes

Document release-related information if applicable.

Item	Value
Platform	iOS / Android
Release Channel	App Store / Google Play / TestFlight / Internal Testing
Build Process	TBD
Versioning Rule	TBD
Responsible Owner	TBD

Testing Checklist

Before release:

• Login works.
• OTP works if enabled.
• Wallet balance loads.
• Student profiles load.
• Order flow works.
• Payment or top-up flow works if applicable.
• Notifications work.
• Role and permission restrictions work.
• App does not expose sensitive logs.