Mobile Native Architecture
Relevant source files
The following files were used as context for generating this wiki page:
KernelForge operates as a locally installable Android application targeting the arm64-v8a architecture. It functions as a specialized dashboard for orchestrating Android custom kernel development, patching, and packaging directly on mobile devices.
The architecture combines a Next.js 15 web frontend with Capacitor 6 to bridge web technologies with native Android capabilities. This setup enables standalone functionality, allowing users to configure builds, apply kernel patches (such as KernelSU and SUSFS), and generate flashable AnyKernel3 ZIPs without a primary reliance on a desktop environment.
Sources: README.md:1-25, package.json:44-58
Core Component Stack
The mobile application architecture consists of three primary layers: the Web UI Layer, the Native Bridge Layer, and the CI/CD Pipeline for distribution.
Web UI Layer (Next.js)
The frontend uses Next.js 15 and is designed as a client-side dashboard. It manages user configurations for kernel sources, device codenames, and patch selections. The interface utilizes a responsive sidebar system that adapts to mobile viewports using custom hooks.
Sources: src/app/page.tsx:43-110, src/hooks/use-mobile.tsx:5-18
Native Bridge Layer (Capacitor)
Capacitor acts as the runtime container. It wraps the statically exported Next.js build into a native Android APK. This allows the web application to interact with the device filesystem and provides the foundation for the "standalone functionality" described in the project overview.
Sources: README.md:21-25, package.json:5-18
Distribution Layer (GitHub Actions)
The architecture includes an automated pipeline that compiles the static web payload and injects it into the Android Capacitor wrapper. The pipeline then signs and aligns the APK for the arm64-v8a platform.
Sources: README.md:30-40
System Architecture Diagram
The following diagram illustrates the relationship between the web frontend, the native bridge, and the target Android environment.
The diagram shows the flow from web development to the final signed native binary.
Sources: README.md:21-40, package.json:5-15
Build and Compilation Logic
The application simulates and orchestrates kernel compilation through a state-driven dashboard. While the frontend provides the UI for "Starting compilation," the project is designed to output flashable artifacts.
| Configuration Element | Source Data / Default | Purpose |
|---|---|---|
| Compiler Toolchain | Clang 17.0.4, GCC 13.2 | Selects the binary toolchain for kernel compilation. |
| Target Architecture | arm64-v8a | Defines the native instruction set for the APK and Kernel. |
| Native Bridge | Capacitor | Provides access to device hardware and filesystem. |
| GKI/KMI Versions | android13-5.15 | Ensures compatibility with Android Generic Kernel Image. |
Sources: src/app/page.tsx:75-90, README.md:35-37
AI Analysis Architecture
The application includes an AI troubleshooting module. Currently, when exported as a static Android APK, the system utilizes a mock assistant to prevent runtime failures in environments without a backend server.
This sequence demonstrates how the application handles AI requests in a static mobile environment.
Sources: src/ai/flows/ai-build-troubleshooting-assistant.ts:25-45, src/components/dashboard/AITroubleshooter.tsx:18-30
Mobile Responsiveness & Layout
The architecture employs a "Mobile-First" layout strategy. The application identifies mobile users via the useIsMobile hook, which triggers specific UI behaviors like a collapsible sidebar and sheet-based navigation.
- Breakpoint: 768px (defined in
MOBILE_BREAKPOINT). - Viewport: Configured for
device-widthwithuser-scalable=falseto mimic native app behavior. - PWA Features: Includes a
manifest.jsonfor standalone display mode and theme color synchronization.
Sources: src/hooks/use-mobile.tsx:3-15, src/app/layout.tsx:19-25, public/manifest.json:1-10
Summary
KernelForge’s Mobile Native Architecture centers on a hybrid approach where Next.js 15 provides the logic for kernel orchestration and Capacitor 6 delivers the native Android container. This architecture facilitates the automation of complex development tasks—like SUSFS integration and AnyKernel3 packaging—directly on mobile hardware, supported by a CI/CD pipeline that ensures continuous delivery of ARM64 binaries.
Sources: README.md:1-40, package.json:1-60