save state

ARCHITECTURE.md

@@ -0,0 +1,96 @@
+# MosisService Architecture
+
+## Overview
+MosisService is an Android application that combines Kotlin UI components with native C++ libraries for UI rendering and system interaction. The architecture is built around a service-oriented design using Android's Binder system and integrates with RmlUi for rich UI rendering.
+
+## Core Components
+
+### 1. Service Layer (mosis-service)
+- **Purpose**: Main Android Binder service implementation
+- **Interface**: Implements `IMosisService.aidl` 
+- **Functionality**:
+  - Touch event processing (onTouchDown, onTouchMove, onTouchUp)
+  - Service initialization and listener management
+  - Integration with kernel-based rendering system
+  - Asset loading through Android AssetManager
+
+### 2. Rendering Layer (mosis-test)
+- **Purpose**: UI rendering and testing infrastructure
+- **Interface**: Implements `IMosisListener.aidl`
+- **Functionality**:
+  - OpenGL ES 2.0 rendering pipeline using GLAD
+  - Multi-threaded rendering with EGL context management
+  - Surface and buffer handling for Android native windows
+  - Task queue management for asynchronous rendering operations
+  - Hardware buffer management and processing
+
+### 3. Core Engine (Kernel)
+- **Purpose**: Central rendering and event processing engine
+- **Components**:
+  - RmlUi-based UI rendering engine
+  - EGL context creation and management
+  - Render target handling
+  - Touch event processing and UI updates
+  - Multi-threaded execution using std::thread
+
+### 4. Supporting Libraries
+- **AssetsManager**: Asset loading from Android AssetManager
+- **Logger**: Cross-platform logging system
+- **EGL Context**: OpenGL ES context management
+- **Render Target**: Framebuffer and buffer management
+- **Shader**: OpenGL shader program handling
+- **External Texture**: Hardware buffer texture creation
+
+## System Architecture
+
+### Android Binder Integration
+- Uses AIDL (Android Interface Definition Language) for cross-process communication
+- Service exposes `IMosisService` interface for touch events and initialization
+- Listener pattern with `IMosisListener` for rendering callbacks
+- Binds to Java/Kotlin components through JNI
+
+### 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
+
+### 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
+```
+
+## Key Technologies
+- **Android NDK**: Native development with C++23
+- **CMake**: Build system for native libraries
+- **RmlUi**: UI rendering engine with HTML/CSS-like markup
+- **OpenGL ES 2.0**: Graphics rendering
+- **GLAD**: OpenGL loader library
+- **AIDL**: Inter-process communication
+- **Binder**: Android's IPC mechanism
+
+## File Structure
+- `mosis-service.cpp`: Main service implementation
+- `mosis-test.cpp`: Test/rendering implementation  
+- `kernel.cpp`: Core rendering engine and event processing
+- `assets_manager.cpp`: Asset loading utilities
+- `egl_context.cpp`: EGL context management
+- `render_target.cpp`: Framebuffer handling
+- `logger.cpp`: Cross-platform logging
+
+## Code Standards
+- Modern C++23 with smart pointers and RAII
+- Thread-safe operations using std::mutex
+- Resource management with proper cleanup
+- Use of std::span, std::format for modern features
+- Cross-platform compatibility through Android NDK