# Mobile App Integration Manual

## Overview
This document outlines the initialization flow for the mobile application, specifically focusing on the version check process ensuring users are on the latest or a supported version of the app.

## App Launch Flow

When the mobile application launches, it must perform a version check against the API to determine if an update is available or mandatory.

### Flow Logic
1.  **App Launch**: User opens the application.
2.  **Check Version**: The app sends a request to the API with its current version and operating system.
3.  **Handle Response**:
    *   **Update Required**: If the update is critical/mandatory, show a **blocking modal**. The user cannot dismiss it and must click a button to go to the App Store or Google Play Store.
    *   **Update Optional**: If a new version is available but not mandatory, show a **dismissible notification** or modal suggesting the user to update for a better experience.
    *   **Latest Version**: If the app is up-to-date, proceed to the app home screen silently.
    *   **Version Not Found**: If the version is not recognized (e.g., development build), do not show any update prompts.

## API Reference

### Check App Version

**Endpoint**
`POST /api/app-version`

**Description**
Checks if the provided app version is the latest, requires an update, or is optional.

**Headers**
- `Content-Type: application/json`
- `Accept: application/json`

**Request Body**

| Parameter | Type   | Required | Description                                      |
| :-------- | :----- | :------- | :----------------------------------------------- |
| `version` | string | Yes      | The current version of the mobile app (e.g., "1.0.0"). |
| `os`      | string | Yes      | The operating system. Values: `ios`, `android`.  |

**Example Request**
```json
{
    "version": "1.0.0",
    "os": "ios"
}
```

**Responses**

The API returns a JSON object with an `update` key indicating the status.

| Status Value | Meaning | Action Required |
| :--- | :--- | :--- |
| `latest` | App is up to date. | None. |
| `required` | A critical update is available. | **Block user**, redirect to store. |
| `optional` | A new version is available. | **Notify user**, allow optional update. |
| `version-not-found` | Version unknown. | None (treat as latest). |

**Response Examples**

*Latest Version:*
```json
{
    "update": "latest"
}
```

*Required Update:*
```json
{
    "update": "required"
}
```

*Optional Update:*
```json
{
    "update": "optional"
}
```