LasTelemetry

A premium, open-source Android application built with React Native and Expo (SDK 54). LasTelemetry securely synchronizes your entire historical Last.fm scrobble timeline (benchmarked for 133,000+ tracks) into a local SQLite repository and enriches your continuous background playbacks with native hardware device telemetry (battery level changes and network connectivity profiles).

Key Architecture Enhancements

• Direct Native Auth Pipeline: Bypasses legacy web browser deep-linking redirect issues via the secure, native Last.fm Mobile Session API over HTTPS.
• Resilient Delta Sync: Dynamically reads local database state checkpoints to resume data transfers via chronological time boundaries (from queries), skipping up to thousands of legacy pages in under 1 second.
• Fault-Tolerant Engine: Implements an atomic rate-limiting throttle (400ms delay) integrated with an exponential backoff retry handler to absorb and recover from remote server HTTP 500 drops.
• Visual Telemetry Analytics: Features a modern 3-tab layout containing fluid client-rendered histograms mapping 24-hour listening density curves and custom horizontal CSS progress blocks visualizing your implicit geographical lifestyle footprint.

Prerequisites

• Node.js: v20 or higher (LTS recommended)
• Package Manager: npm (v10+) or yarn
• Expo Go Application: Installed on your Android device from the Play Store
• Last.fm Developer Credentials: An active API Key and Shared Secret (Acquire yours at last.fm/api/account/create)

Getting Started

1. Extract and Install Dependencies

Clone the repository, enter the workspace directory, and execute a legacy-peer-compliant dependency tree installation pass:

cd lastelemetry
npm install --legacy-peer-deps

2. Environment Configuration

Create a .env file directly inside the root directory of the workspace and include your explicit Expo-public developer keys:

EXPO_PUBLIC_LASTFM_API_KEY=your_32_char_api_key_here
EXPO_PUBLIC_LASTFM_SECRET=your_32_char_shared_secret_here

3. Clear Caches and Fire the Bundler

Run the Metro transformation engine server, forcing a complete reload of environmental and package cache layers:

npx expo start --clear

Scan the resulting terminal QR Code directly inside the Expo Go application on your smartphone to begin interactive debugging.

Repository Worktree

lastelemetry/
├── .env                  # Local environment API keys (gitignored)
├── .gitignore            # Git exclusion rules
├── app.json              # Main Expo config (Identities, package strings, and permissions)
├── eas.json              # Production and local cloud building profile targets
├── App.tsx               # Root component entrypoint orchestrating the bottom tab navigation tray
├── package.json          # Node dependencies, versions, and automation scripts
└── src/
    ├── api/
    │   └── lastfm.ts     # Axios client configuration with cryptographic MD5 signing methods
    ├── config/
    │   └── constants.ts  # Central global endpoints, synchronization constants, and parameters
    ├── database/
    │   ├── sqlite.ts     # SQLite storage initializers, bulk transaction inserts, and pagination data
    │   ├── analytics.ts  # Timeline metric queries matching top lists and chronological hour filters
    │   └── geo.ts        # Advanced SQL conditional scripts computing geographic profiles
    ├── hooks/
    │   └── useTelemetry.ts # Hardware reader wrapper mapping live network types and battery level drops
    ├── services/
    │   ├── auth.ts       # Secure native mobile authentication session persistence manager
    │   ├── background.ts # Persistent Android background task worker and boot managers
    │   └── sync.ts       # Optimized delta-tracking streaming history pagination worker
    └── screens/
        ├── HomeScreen.tsx   # Tab 1: Card dashboard with fluid progress meters and live history streams
        ├── AnalyticsScreen.tsx # Tab 2: Dynamic time-framed selector grids filtering top tracks/artists
        └── ChartsScreen.tsx # Tab 3: Metric histogram dashboards and telemetry lifestyle bars

Production Building, Secrets, and Packaging

LasTelemetry uses the EAS CLI (Expo Application Services) engine to run automated native Android Gradle compilations securely in the cloud.

1. Global Setup and Authentication

Ensure the EAS toolchain is correctly mapped onto your Linux workstation:

# Install the EAS builder binary suite globally
sudo npm install -g eas-cli

# Log into your remote managed cloud account
eas login

2. Remote Secret Provisioning (Mandatory)

Because .env files are gitignored for absolute cloud safety, you must inject your credentials as encrypted production environment variables inside the Expo dashboard. Execute these parameters from your root workspace terminal:

# Provision the api key token
eas secret:create --scope project --name EXPO_PUBLIC_LASTFM_API_KEY --value "YOUR_REAL_API_KEY"

# Provision the secret verification hash
eas secret:create --scope project --name EXPO_PUBLIC_LASTFM_API_SECRET --value "YOUR_REAL_API_SECRET"

3. Initialize EAS Configuration Layout

Generate the core cloud properties profiles block if missing:

eas build:configure

4. Compilation Profiles Execution

Profile A: Generate Local Installer Binary (.APK Build)

To compile a standalone independent file to install directly onto your device (Ad-Hoc / Sideloading) without compiling the Android Studio SDK locally, run the preview target mapping our custom buildType: "apk" profile configuration:

eas build --platform android --profile preview

When finished, the terminal outputs a direct clickable web download link and a QR Code. Scan it with your phone to download, install the .apk package file, and run it locally with its own customized launcher app icons.

Profile B: Production Bundle Generation (.AAB Play Store Build)

To output a modern compressed production bundle file optimized for distribution upload keys inside the Google Play Console, execute the production target chain:

eas build --platform android --profile production

This profile leverages strict bundle compression rules to split and compile individual optimized .apk packages on Google's side depending on the downloading end-user phone's native hardware processor architecture.