first commit

2026-01-11 19:47:49 -05:00
commit 1438003f94
56 changed files with 4829 additions and 0 deletions
@@ -0,0 +1,114 @@
+# ShaarIt
+
+**ShaarIt** is a native Android client for [Shaarli](https://github.com/shaarli/Shaarli), the self-hosted bookmark manager. Built with modern Android technologies, it provides a seamless mobile experience for managing your links.
+
+## Features
+
+*   **Authentication**: Secure login to your self-hosted Shaarli instance (API v1).
+*   **Feed**: Infinite scroll browsing of your bookmarks with infinite loading.
+*   **Search & Filter**: Server-side search by terms and tag filtering.
+*   **Management**: Add new private/public links and delete existing ones.
+*   **Share Intent**: Quick-save links from other apps (browser, YouTube, etc.) via the Android Share menu.
+
+## Tech Stack
+
+*   **Language**: Kotlin
+*   **UI**: Jetpack Compose (Material Design 3)
+*   **Architecture**: Clean Architecture + MVVM
+*   **Dependency Injection**: Dagger Hilt
+*   **Network**: Retrofit + Moshi + OkHttp
+*   **Concurrency**: Coroutines & Flow
+*   **Pagination**: Paging 3
+
+## Prerequisites
+
+Before building via the command line, ensure you have:
+
+1.  **JDK 17** (or newer) installed.
+2.  **Android SDK** installed.
+3.  **Gradle** (v8.0+) installed (only required if `gradlew` is missing).
+    *   *Note for Windows users with Scoop:* `scoop install gradle`
+
+## First Time Setup (If gradlew is missing)
+
+If the `./gradlew` file is missing (e.g. fresh project generation), you need to generate it using a local Gradle installation:
+
+```bash
+gradle wrapper
+```
+
+This will create `gradlew`, `gradlew.bat` and the `gradle/wrapper` folder.
+
+## Environment Setup (SDK)
+
+Ensure you have the required Android SDK components installed (Platform API 34).
+If you see a silent failure or "missing target" error, run:
+
+```powershell
+# Adjust path to your sdkmanager if needed
+$SDK_MANAGER = "$env:ANDROID_HOME\cmdline-tools\latest\bin\sdkmanager" 
+& $SDK_MANAGER "platforms;android-34" "build-tools;34.0.0"
+```
+
+## Compilation Instructions (Command Line)
+
+You can build the project without opening Android Studio by using the Gradle Wrapper included in the project.
+
+### 1. Configure SDK Location
+If your `ANDROID_HOME` environment variable is not set, create a `local.properties` file in the project root:
+
+```bash
+# Windows
+echo sdk.dir=C:\\Users\\<Username>\\AppData\\Local\\Android\\Sdk > local.properties
+
+# Linux/macOS
+echo sdk.dir=/home/<username>/Android/Sdk > local.properties
+```
+
+### 2. Build the APK
+
+Open your terminal in the project root folder.
+
+**Windows (PowerShell/CMD):**
+```powershell
+./gradlew assembleDebug
+```
+
+**Linux/macOS:**
+```bash
+chmod +x gradlew
+./gradlew assembleDebug
+```
+
+*The build process may take a few minutes as it downloads dependencies.*
+
+### 3. Locate the APK
+Once the build is successful, the APK file will be located at:
+`app/build/outputs/apk/debug/app-debug.apk`
+
+## Installation
+
+To install the app on a connected device or emulator via command line:
+
+```bash
+# Ensure your device is connected and visible
+adb devices
+
+# Install the Debug APK
+adb install -r app/build/outputs/apk/debug/app-debug.apk
+```
+
+## Running Tests
+
+To run unit tests:
+
+```bash
+./gradlew test
+```
+
+## Usage
+
+1.  Open the **ShaarIt** app.
+2.  Enter your **Shaarli Instance URL** (e.g., `https://myserver.com/shaarli`).
+3.  Enter your **API Secret** (found in your Shaarli admin settings).
+4.  Click **Connect**.