Merge pull request #27 from SmilingPixel/doc/project_doc_0519

doc: add project docs

Author: SmilingPixel

README.md

@@ -1 +1,80 @@
-# mark-day
+# MarkDay Diary App
+
+MarkDay is a cross-platform diary and journaling application built with **Kotlin** and **Compose Multiplatform**. The application seamlessly targets **Android**, **Desktop (JVM)**, and **Web (Wasm)** from a unified codebase, maintaining consistency across platforms using Material Design 3. 
+
+## Features
+
+- **Cross-Platform:** Write your diary on Android, Desktop, or directly in the browser.
+- **Unified UI:** Beautiful and consistent Material 3 interface across all devices, powered by Compose Multiplatform.
+- **Local Storage:** Fast and reliable text storage utilizing Room Multiplatform (SQLite) on Android, Desktop, and iOS. Web (Wasm) uses in-memory storage with browser localStorage for preferences.
+- **Rich Content:** Support for rich text and image rendering (via multiplatform-markdown-renderer and Coil).
+- **Sync & Backup (Android/Desktop JVM only):** Google Drive integration for seamless data backups and remote sync. Web (Wasm) support is not implemented yet.
+
+## Project Structure
+
+The codebase is organized into Gradle/Kotlin Multiplatform source sets under `composeApp/src`:
+- `commonMain/` – Core business logic, UI layer (Compose), Navigation, API, and DB interfaces.
+- `androidMain/` – Android-specific implementations (e.g., Ktor OkHttp client, Play Services Auth).
+- `jvmMain/` – Desktop entry point, Swing interop, and JVM implementations.
+- `wasmJsMain/` – WebAssembly implementations for browser deployment.
+- `nonWebMain/` – Shared implementations for non-web platforms (Android, Desktop), primarily dealing with local DB interactions using Room.
+- `iosMain/` – iOS-specific logic (currently suspended).
+
+## Prerequisites
+
+To build the MarkDay application, ensure you have the following installed and configured:
+
+- **Java Development Kit (JDK):** JDK 21+ recommended.
+- **Kotlin:** 2.0+ 
+- **Android SDK:** Required for Android builds.
+
+## Configuration
+
+### Android Setup
+To build the Android application, you must configure the path to your Android SDK. If you haven't set the `ANDROID_HOME` environment variable, you can create a `local.properties` file in the root of the project.
+
+**Example `local.properties`:**
+```properties
+# Add this file to the project root
+sdk.dir=/path/to/your/android-sdk
+# On Windows, this might look like: sdk.dir=C\:\\Users\\Username\\AppData\\Local\\Android\\Sdk
+# On Linux/Codespaces: sdk.dir=/usr/lib/android-sdk
+```
+
+### iOS Development
+> This setup ensures that iOS development remains suspended by default (saving build time and avoiding configuration issues on non-Mac environments) but can be easily re-enabled by setting `enableIos=true` in `gradle.properties` or passing `-PenableIos=true` as a command-line argument.
+
+## Development
+
+### Running the Application
+
+- **Android:** 
+  ```sh
+  ./gradlew installDebug
+  ```
+- **Desktop (JVM):** 
+  ```sh
+  ./gradlew run
+  ```
+- **Web (Wasm):** 
+  ```sh
+  ./gradlew wasmJsBrowserRun
+  ```
+
+### Building for Android (Debug)
+To build a debug APK for Android from the command line, run:
+```sh
+./gradlew assembleDebug
+```
+Once the build completes successfully, the generated APK will be located at:
+`composeApp/build/outputs/apk/debug/composeApp-debug.apk`
+
+### Running Tests
+To run all multiplatform tests across configured targets:
+```sh
+./gradlew allTests
+```
+Or to run tests for a specific platform (e.g., Desktop/JVM):
+```sh
+./gradlew composeApp:jvmTest
+```

composeApp/src/androidMain/README.md

@@ -0,0 +1,11 @@
+# Android Target (androidMain)
+
+## Introduction
+The `androidMain` source directory holds the Android-specific implementation details for the MarkDay application. These implementations fulfill the `expect` declarations found in `commonMain` and handle Android-native integrations.
+
+## Structure
+Key components found in this module:
+- **Application Context & Entry Points:** `MainActivity` and OS-level lifecycle hooks.
+- **Networking:** Android-native networking components, like the Ktor `okhttp` client engine.
+- **System Integrations:** Access to Google Play Services for things like Google Drive Auth and Cloud Sync features.
+- **Platform APIs:** Specific implementations requiring `Context` or Android application framework resources.

composeApp/src/commonMain/README.md

@@ -0,0 +1,13 @@
+# Shared Core (commonMain)
+
+## Introduction
+The `commonMain` directory is the heart of the MarkDay application. It contains the cross-platform, multiplatform codebase shared across all targets (Android, Desktop, Web, and potentially iOS).
+
+## Structure
+All UI presentation and core business logic reside here:
+- **UI (Compose Multiplatform):** Screens, components, and Material 3 theming.
+- **Navigation:** Core application routing logic using Compose Navigation.
+- **Models & Logic:** Domain entities, view models, and state management.
+- **Networking/Data Interfaces:** Shared expect/actual declarations and DB interfaces (Room).
+
+Modify code here to implement features that will automatically propagate to all application targets.

composeApp/src/jvmMain/README.md

@@ -0,0 +1,11 @@
+# Desktop Target (jvmMain)
+
+## Introduction
+The `jvmMain` directory is dedicated to the Desktop (Windows, macOS, Linux) target for the MarkDay application. It uses Compose for Desktop running on the JVM.
+
+## Structure
+Key components typically found here include:
+- **Application Entry Point:** Desktop `main()` function defining window state, size, and icons.
+- **Swing Interop:** Any integration with underlying AWT/Swing capabilities if needed.
+- **Networking:** Desktop-specific HTTP client engines for Ktor (e.g., `java` engine).
+- **File System:** Logic relying on `java.io` or desktop-specific file systems for exports, caching, and IO matching expected interfaces in `commonMain`.

composeApp/src/nonWebMain/README.md

@@ -0,0 +1,11 @@
+# Non-Web Targets (nonWebMain)
+
+## Introduction
+The `nonWebMain` source set is an intermediate layer designed to share code for non-web targets while specifically excluding WebAssembly (Wasm). In the current build setup, it is shared by Android and Desktop (JVM), and iOS also participates when `enableIos=true` in `composeApp/build.gradle.kts`.
+
+## Structure
+This module solves the problem of sharing technologies that the browser environment does not support across the non-web targets configured in the build:
+- **Database (Room SQL):** The Room database implementation, KSP-generated DAOs, and SQLite drivers operate across JVM and native targets where configured, but are not viable on Web targets.
+- **Local Persistence (DataStore):** Storage APIs tailored for actual file systems.
+
+Any shared logic relying on robust, file-backed local storage schemas should be located here rather than `commonMain` so it can be omitted from web browser compilations without causing errors.

composeApp/src/wasmJsMain/README.md

@@ -0,0 +1,10 @@
+# WebAssembly Target (wasmJsMain)
+
+## Introduction
+The `wasmJsMain` source set targets the browser using modern Kotlin WebAssembly (Wasm). This allows the application to run natively inside web browsers with excellent performance.
+
+## Structure
+WebAssembly implementation specifics:
+- **Browser APIs:** JavaScript interoperability or Browser DOM capabilities bridging the `commonMain` UI to the browser.
+- **Networking:** Fetch-API based engines for Ktor to work smoothly within browser CORS and networking models.
+- **Storage limitations:** Alternative approaches for local persistence, handling capabilities missing from native SQL (since `nonWebMain` features are excluded here).