move docs to docs/ folder, merge architecture files, update references

docs/ARCHITECTURE.md

@@ -0,0 +1,105 @@
+# 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)