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

docs/MILESTONE-3.md

@@ -0,0 +1,333 @@
+# Milestone 3: Virtual Hardware
+
+**Status**: Not Started
+**Goal**: Hardware-like APIs backed by game engine or real devices.
+
+---
+
+## Overview
+
+Mosis needs to expose smartphone-like hardware interfaces that can be:
+- Provided by game engines (Unity/Unreal) in VR mode
+- Mocked for desktop testing
+- Connected to real device hardware on Android
+
+---
+
+## Components
+
+### 3.1 Camera Interface
+
+**Header**: `src/main/kernel/include/camera.h`
+
+```cpp
+namespace mosis {
+
+struct CameraFrame {
+    int width;
+    int height;
+    std::vector<uint8_t> rgba_data;  // RGBA8 format
+    int64_t timestamp_ms;
+};
+
+using CameraCallback = std::function<void(const CameraFrame& frame)>;
+
+class ICamera {
+public:
+    virtual ~ICamera() = default;
+
+    // Start/stop frame capture
+    virtual void StartCapture(CameraCallback callback) = 0;
+    virtual void StopCapture() = 0;
+
+    // Configuration
+    virtual void SetResolution(int width, int height) = 0;
+    virtual bool IsAvailable() const = 0;
+
+    // Get current state
+    virtual int GetWidth() const = 0;
+    virtual int GetHeight() const = 0;
+};
+
+} // namespace mosis
+```
+
+**Implementations**:
+
+| Implementation | Description | File |
+|----------------|-------------|------|
+| `GameCamera` | Receives texture from Unity/Unreal | `game_camera.cpp` |
+| `DesktopCamera` | System webcam via OpenCV (optional) | `desktop_camera.cpp` |
+| `AndroidCamera` | Camera2 API integration | `android_camera.cpp` |
+| `MockCamera` | Test patterns (checkerboard, gradient) | `mock_camera.cpp` |
+
+### 3.2 Microphone Interface
+
+**Header**: `src/main/kernel/include/microphone.h`
+
+```cpp
+namespace mosis {
+
+struct AudioBuffer {
+    std::vector<int16_t> samples;  // PCM 16-bit
+    int sample_rate;               // Typically 44100 or 48000
+    int channels;                  // 1 = mono, 2 = stereo
+    int64_t timestamp_ms;
+};
+
+using AudioCallback = std::function<void(const AudioBuffer& buffer)>;
+
+class IMicrophone {
+public:
+    virtual ~IMicrophone() = default;
+
+    virtual void StartCapture(AudioCallback callback) = 0;
+    virtual void StopCapture() = 0;
+
+    virtual void SetSampleRate(int rate) = 0;
+    virtual bool IsAvailable() const = 0;
+    virtual bool IsCapturing() const = 0;
+};
+
+} // namespace mosis
+```
+
+**Implementations**:
+
+| Implementation | Description |
+|----------------|-------------|
+| `GameMicrophone` | Audio from Unity/Unreal AudioSource |
+| `DesktopMicrophone` | System mic via PortAudio |
+| `AndroidMicrophone` | AudioRecord API |
+| `MockMicrophone` | Silence or test tones |
+
+### 3.3 Speaker Interface
+
+**Header**: `src/main/kernel/include/speaker.h`
+
+```cpp
+namespace mosis {
+
+class ISpeaker {
+public:
+    virtual ~ISpeaker() = default;
+
+    virtual void PlayAudio(const AudioBuffer& buffer) = 0;
+    virtual void SetVolume(float volume) = 0;  // 0.0 - 1.0
+    virtual float GetVolume() const = 0;
+
+    virtual bool IsAvailable() const = 0;
+};
+
+} // namespace mosis
+```
+
+### 3.4 Filesystem Interface
+
+**Header**: `src/main/kernel/include/filesystem.h`
+
+```cpp
+namespace mosis {
+
+enum class FileMode { Read, Write, Append };
+
+struct FileInfo {
+    std::string name;
+    bool is_directory;
+    size_t size;
+    int64_t modified_time;
+};
+
+class IFileSystem {
+public:
+    virtual ~IFileSystem() = default;
+
+    // File operations
+    virtual std::vector<uint8_t> ReadFile(const std::string& path) = 0;
+    virtual bool WriteFile(const std::string& path, const std::vector<uint8_t>& data) = 0;
+    virtual bool DeleteFile(const std::string& path) = 0;
+    virtual bool FileExists(const std::string& path) = 0;
+
+    // Directory operations
+    virtual std::vector<FileInfo> ListDirectory(const std::string& path) = 0;
+    virtual bool CreateDirectory(const std::string& path) = 0;
+    virtual bool DeleteDirectory(const std::string& path) = 0;
+
+    // Sandboxed paths
+    virtual std::string GetAppDataPath(const std::string& app_id) = 0;
+    virtual std::string GetSharedMediaPath() = 0;
+};
+
+} // namespace mosis
+```
+
+**App Storage Structure**:
+```
+/data/
+├── apps/
+│   ├── com.example.app1/
+│   │   ├── files/
+│   │   ├── cache/
+│   │   └── databases/
+│   └── com.example.app2/
+├── shared/
+│   ├── photos/
+│   ├── downloads/
+│   └── music/
+```
+
+### 3.5 Network Interface
+
+**Header**: `src/main/kernel/include/network.h`
+
+```cpp
+namespace mosis {
+
+struct HttpRequest {
+    std::string method;  // GET, POST, PUT, DELETE
+    std::string url;
+    std::map<std::string, std::string> headers;
+    std::vector<uint8_t> body;
+};
+
+struct HttpResponse {
+    int status_code;
+    std::map<std::string, std::string> headers;
+    std::vector<uint8_t> body;
+};
+
+class INetwork {
+public:
+    virtual ~INetwork() = default;
+
+    // HTTP
+    using HttpCallback = std::function<void(const HttpResponse&)>;
+    virtual void Fetch(const HttpRequest& request, HttpCallback callback) = 0;
+
+    // Connectivity
+    virtual bool IsOnline() const = 0;
+    virtual std::string GetConnectionType() const = 0;  // "wifi", "cellular", "none"
+};
+
+} // namespace mosis
+```
+
+---
+
+## Platform Integration
+
+### Platform Interface Extension
+
+**File**: `src/main/kernel/include/platform.h`
+
+```cpp
+class IPlatform {
+public:
+    // ... existing methods ...
+
+    // Hardware providers
+    virtual ICamera* GetCamera() = 0;
+    virtual IMicrophone* GetMicrophone() = 0;
+    virtual ISpeaker* GetSpeaker() = 0;
+    virtual IFileSystem* GetFileSystem() = 0;
+    virtual INetwork* GetNetwork() = 0;
+};
+```
+
+### Desktop Implementation
+
+**File**: `designer/src/desktop_platform.cpp`
+
+```cpp
+class DesktopPlatform : public IPlatform {
+    std::unique_ptr<MockCamera> m_camera;
+    std::unique_ptr<MockMicrophone> m_microphone;
+    std::unique_ptr<DesktopSpeaker> m_speaker;
+    std::unique_ptr<DesktopFileSystem> m_filesystem;
+    std::unique_ptr<DesktopNetwork> m_network;
+
+public:
+    ICamera* GetCamera() override { return m_camera.get(); }
+    // ...
+};
+```
+
+### Android Implementation
+
+**File**: `src/main/cpp/android_platform.cpp`
+
+```cpp
+class AndroidPlatform : public IPlatform {
+    // Use JNI to access Android APIs
+    std::unique_ptr<AndroidCamera> m_camera;
+    // ...
+};
+```
+
+### Game Engine Implementation
+
+**File**: Unity plugin or Unreal plugin
+
+```cpp
+class GamePlatform : public IPlatform {
+    // Receives textures/audio from game engine
+    std::unique_ptr<GameCamera> m_camera;
+    // ...
+};
+```
+
+---
+
+## Implementation Plan
+
+### Phase 1: Interfaces Only
+- [ ] Define all interface headers
+- [ ] Add to platform abstraction
+- [ ] Create mock implementations for testing
+
+### Phase 2: Desktop Implementation
+- [ ] MockCamera (test patterns)
+- [ ] PortAudio for speaker output
+- [ ] Standard filesystem access
+- [ ] libcurl for HTTP
+
+### Phase 3: Android Implementation
+- [ ] Camera2 API wrapper (JNI)
+- [ ] AudioRecord/AudioTrack wrappers
+- [ ] Android filesystem with proper sandboxing
+- [ ] OkHttp or native networking
+
+### Phase 4: Game Engine Integration
+- [ ] Unity RenderTexture → ICamera
+- [ ] Unity AudioSource → IMicrophone
+- [ ] Unity AudioListener → ISpeaker
+- [ ] Unreal equivalents
+
+---
+
+## Dependencies
+
+| Dependency | Purpose | vcpkg Package |
+|------------|---------|---------------|
+| PortAudio | Desktop audio I/O | `portaudio` |
+| OpenCV | Desktop webcam (optional) | `opencv4` |
+| libcurl | HTTP client | `curl` |
+
+---
+
+## Test Cases
+
+1. **MockCamera**: Renders test pattern, verify frame callback
+2. **FileSystem**: Create, read, write, delete operations
+3. **Network**: Mock HTTP responses, verify request/response
+4. **Audio**: Verify sample rates, buffer formats
+
+---
+
+## Acceptance Criteria
+
+- [ ] All interfaces defined in kernel/include/
+- [ ] Mock implementations work on desktop
+- [ ] Camera app can display camera frames
+- [ ] Browser app can make HTTP requests
+- [ ] Apps can persist data to filesystem