MosisService/docs/ARCHITECTURE.md

Architecture Overview

MosisService is an Android application combining Kotlin UI with native C++ libraries for UI rendering via Android's Binder IPC system.

Two Native Libraries

mosis-service (libmosis-service.so):

• Main Android Binder service implementation
• Implements IMosisService.aidl interface for touch events and initialization
• Contains the Kernel rendering engine with RmlUi integration
• Links against RmlUi for HTML/CSS-like UI rendering

mosis-test (libmosis-test.so):

• Test/rendering client implementation
• Implements IMosisListener.aidl for receiving callbacks
• OpenGL ES 2.0 rendering pipeline using GLAD

IPC Flow

Kotlin NativeService → JNI → mosis-service (IMosisService)
                              ↓
                         IMosisListener callbacks
                              ↓
                         mosis-test (rendering client)

Key Interfaces (AIDL)

IMosisService: initOS(), onTouchDown(), onTouchMove(), onTouchUp()

IMosisListener (oneway/async): onServiceInitialized(), onBufferAvailable(), onFrameAvailable()

Multi-threading Model

• Service layer runs in main thread for event handling
• Rendering loop runs in dedicated thread managed by Kernel
• Async task processing for UI updates
• Thread-safe communication between components using std::mutex

Rendering Pipeline

1. Initialization: Service connects to test layer, creates EGL context
2. Buffer Management: Hardware buffers allocated and shared between layers
3. Event Processing: Touch events processed and forwarded to Kernel
4. Rendering Loop: Continuous rendering with frame synchronization
5. UI Updates: RmlUi engine updates UI based on events and data

Data Flow

User Touch Events → IMosisService.onTouch* → Kernel.process → RmlUi UI Updates
Service Initialized → IMosisListener.onServiceInitialized → Rendering Setup
Buffer Available → IMosisListener.onBufferAvailable → Texture Creation
Frame Available → IMosisListener.onFrameAvailable → Frame Rendering

Native Code Structure (src/main/cpp/)

Core:

• kernel.cpp - Core rendering engine, RmlUi integration, event processing
• mosis-service.cpp - Binder service implementation, JNI entry points
• mosis-test.cpp - Test client implementation
• egl_context.cpp - OpenGL ES context management
• render_target.cpp - Framebuffer and buffer management
• RmlUi_Renderer_GL3.cpp - RmlUi OpenGL renderer backend
• assets_manager.cpp - Android AssetManager integration

App Management (apps/):

• app_manager.cpp - App install/uninstall/launch lifecycle
• app_api.cpp - Lua API bindings for app management
• update_service.cpp - Background update checking

Lua Sandbox (sandbox/):

• sandbox_manager.cpp - Multi-app sandbox orchestrator
• lua_sandbox.cpp - Core Lua sandbox with resource limits
• permission_gate.cpp - Permission system (normal/dangerous/signature)
• virtual_fs.cpp - Per-app virtual filesystem with quotas
• database_manager.cpp - SQLite database per app
• network_manager.cpp - HTTP request validation
• websocket_manager.cpp - WebSocket connections
• timer_manager.cpp - setTimeout/setInterval implementation
• json_api.cpp - Safe JSON encode/decode
• crypto_api.cpp - Cryptographic functions (SHA256, HMAC)
• camera_interface.cpp - Camera access with indicators
• microphone_interface.cpp - Microphone access with indicators
• audio_output.cpp - Audio playback
• location_interface.cpp - GPS with precision reduction
• sensor_interface.cpp - Accelerometer, gyroscope, etc.
• bluetooth_interface.cpp - Bluetooth device access
• contacts_interface.cpp - Contacts read/write
• message_bus.cpp - Inter-app communication

Code Style

• C++23 standard with modern features (std::span, std::format)
• PascalCase for classes/functions, camelCase for variables
• RAII principles with smart pointers
• Kotlin code follows Android conventions

Dependencies

• vcpkg manages native dependencies (RmlUi, GLFW, Freetype, Lua, libpng, nlohmann-json, minizip, sqlite3)
• CMake build system with vcpkg toolchain integration
• Android target architecture: arm64-v8a only
• Desktop target: Windows x64 (MSVC)