Architecture Specification

Engineering Architecture & System Design

Hearth is architected specifically for resource-constrained 10-foot devices. Here is how we achieve 60 FPS fluid D-pad navigation under a 25 MB resident memory footprint.

1. Platform Baseline & Technology Stack

Android TV hardware spans a massive spectrum: from flagship Apple TV-grade Nvidia Shield Pro units to sub-$20 Fire TV Stick Lite devices equipped with just 1 GB of shared system RAM. To run reliably across all devices, Hearth is built on strict platform baselines:

Component	Technology	Architectural Rationale
Language	Kotlin 2.0+	Type safety, Coroutines, Flow-based state streams
UI Toolkit	Jetpack Compose for TV	Native 10-foot focus management, lean composables
Local Database	AndroidX Room 2.6+ SQLite	Persists app categorization, order, and visibility offline
Key-Value Store	Jetpack DataStore	Thread-safe async preferences (clock format, UI scale)
Image Pipeline	Coil 3 (Compose)	Downscaling to 1080p with RGB_565 decoding
Target SDK	API 23 to API 35	Compatible with Android 6.0 through Android 15 TV

2. 10-Foot Leanback Focus Engine

Traditional Android touch events do not exist on a television remote. Hearth uses androidx.tv:tv-material and androidx.tv:tv-foundation to manage focus state deterministically:

// Focus scale & glow transition in Compose for TV
val isFocused by interactionSource.collectIsFocusedAsState()

val scale by animateFloatAsState(
    targetValue = if (isFocused) 1.15f else 1.0f,
    animationSpec = spring(
        dampingRatio = Spring.DampingRatioMediumBouncy,
        stiffness = Spring.StiffnessLow
    )
)

Card(
    modifier = Modifier
        .graphicsLayer {
            scaleX = scale
            scaleY = scale
        }
        .border(
            width = if (isFocused) 2.dp else 0.dp,
            color = if (isFocused) Color(0xFFFF5722) else Color.Transparent,
            shape = RoundedCornerShape(14.dp)
        )
) { ... }

3. Low-RAM Engine & Shader Downscaling

On low-end 1 GB Fire TV sticks, an uncompressed 4K wallpaper bitmap occupies approximately 33 MB of heap memory (3840 × 2160 × 4 bytes in ARGB_8888). Loading just two such images causes an immediate OutOfMemoryError.

The Hearth Memory Guard:

All background images are clamped to maximum dimensions of 1920 × 1080 prior to decoding.
Images decode in RGB_565 (2 bytes per pixel) rather than ARGB_8888, reducing bitmap size to ~4.1 MB.
Dynamic blurs on Android 12+ (API 31+) use hardware RenderEffect.createBlurEffect() with zero CPU overhead.

4. Dual App Discovery & Deduplication

Many streaming apps (e.g. sideloaded APKs or utilities) declare standard phone launcher activities (android.intent.category.LAUNCHER) without providing a TV Leanback activity (android.intent.category.LEANBACK_LAUNCHER).

Hearth executes a two-phase discovery pass via PackageManager:

Queries all native Leanback activities and registers them as primary targets.
Queries standard phone launcher activities, filtering out any packages already registered in phase 1 to eliminate duplicate tiles.
Attaches a real-time BroadcastReceiver for ACTION_PACKAGE_ADDED, ACTION_PACKAGE_REMOVED, and ACTION_PACKAGE_REPLACED to update the UI instantly without restarting the launcher.

5. Zero-Permission Air-Gapped Security

Hearth does not declare android.permission.INTERNET in its core AndroidManifest.xml. It is physically impossible for the launcher to transmit your installed applications, watch logs, or user preferences to any remote server.