# Android App Integration Guide Dashboard Proxy

This document outlines how to build an Android application that consumes the data provided by your AC Infinity Proxy API.

## Base Configuration

*   **Base URL**: `https://dev.seedheads.de/ac/`
*   **Protocol**: HTTPS

## API Endpoints

The proxy server exposes two main endpoints that return JSON data.

### 1. Get All Devices
Retrieves a list of all devices and their ports currently stored in the database.

*   **Endpoint**: `GET /api/devices`
*   **Full URL**: `https://dev.seedheads.de/ac/api/devices`
*   **Response Format**: JSON Array
*   **Example Response**:
    ```json
    [
        {
            "dev_name": "Tent Controller",
            "port": 1,
            "port_name": "Fan Inline"
        },
        {
            "dev_name": "Tent Controller",
            "port": 2,
            "port_name": "Light Top"
        }
    ]
    ```

### 2. Get Historical Data
Retrieves historical sensor readings for a specific device and port.

*   **Endpoint**: `GET /api/history`
*   **Full URL**: `https://dev.seedheads.de/ac/api/history`
*   **Query Parameters**:
    *   `devName` (string, required): The name of the controller (e.g., "Tent Controller"). URL-encoded.
    *   `port` (integer, required): The port number (e.g., `1`).
    *   `range` (string, optional): The time range. Defaults to `day`.
        *   `day`: Last 24 hours.
        *   `week`: Last 7 days.
        *   `month`: Last 30 days.

*   **Example Request**:
    `GET https://dev.seedheads.de/ac/api/history?devName=Tent%20Controller&port=1&range=day`

*   **Response Format**: JSON Array of objects
*   **Example Response**:
    ```json
    [
        {
            "timestamp": "2023-10-27T10:00:00Z",
            "temp_c": 24.5,
            "humidity": 60.2,
            "vpd": 1.1,
            "fan_speed": 5,
            "on_speed": 0,
            "off_speed": 0
        },
        ...
    ]
    ```
    *Note: Timestamps are returned in UTC (ending in 'Z'). You must convert them to the local timezone within the Android app.*

## Android Implementation Recommendations

### Networking Library
Use **Retrofit** with **OkHttp** for robust networking. It simplifies URL handling, parameter encoding, and JSON parsing.

**Dependencies (`build.gradle`):**
```groovy
implementation 'com.squareup.retrofit2:retrofit:2.9.0'
implementation 'com.squareup.retrofit2:converter-gson:2.9.0'
```

### Data Models (Kotlin)

```kotlin
data class Device(
    @SerializedName("dev_name") val devName: String,
    @SerializedName("port") val port: Int,
    @SerializedName("port_name") val portName: String
)

data class Reading(
    val timestamp: String,
    @SerializedName("temp_c") val tempC: Float,
    @SerializedName("humidity") val humidity: Float,
    @SerializedName("vpd") val vpd: Float,
    @SerializedName("fan_speed") val fanSpeed: Int
)
```

### Retrofit Service Interface

```kotlin
interface AcApi {
    @GET("api/devices")
    suspend fun getDevices(): List<Device>

    @GET("api/history")
    suspend fun getHistory(
        @Query("devName") devName: String,
        @Query("port") port: Int,
        @Query("range") range: String = "day"
    ): List<Reading>
}
```

### Handling Timezones
Since the API returns UTC timestamps (e.g., `2023-10-27T10:00:00Z`), use `java.time` (API 26+) to format them for the user's local device time.

```kotlin
val instant = Instant.parse(reading.timestamp)
val localDateTime = LocalDateTime.ofInstant(instant, ZoneId.systemDefault())
```

## Security Considerations

*   **Authentication**: Currently, the proxy at `https://dev.seedheads.de/ac/` is publicly accessible (if not protected by Basic Auth in Nginx). If you add Basic Auth to Nginx, you will need to add an `Authorization` header to your Retrofit client.
*   **HTTPS**: Ensure your Android app allows HTTPS connections (default behavior).

## Future Enhancements
*   **Push Notifications**: The current API is poll-based. For real-time alerts (e.g., high temp), you would need to implement a background worker in Android (`WorkManager`) to poll the API periodically, or implement Firebase Cloud Messaging (FCM) on the Node.js server.