# Incido — Development Plan ## 0. Project Overview **Name:** Incido (Latin, pronounced "een-chi-do" — *incido* = "I cut into / I inscribe") **Mission:** A privacy-first, on-device note-taking application. All data stays on the user's device by default. Built to be free, offline-capable, and never lock user content behind a vendor. **Target Audience:** Privacy-conscious users, anyone wanting a Google Keep alternative without cloud dependency, users who want to avoid paid subscriptions for basic note-taking. **v0.1 Scope (this plan):** Android-only proof-of-concept / Minimum Viable Product. Demonstrates the core architecture, data layer, and UI shell. Sets the technical foundation for all future features without requiring rewrites. **Tagline (suggested):** *Your notes. Your device. Your terms.* --- ## 1. Licensing ### 1.1 FOSS Flavor — License: AGPL-3.0 - Anyone may use, modify, and redistribute the code. - Anyone who runs a modified version (even as a network service) **must publish their source code changes**. - This enforces the "contribute back" requirement for downstream users while still allowing them to profit from their own derivative applications. - Full license text: https://www.gnu.org/licenses/agpl-3.0.en.html - A `LICENSE` file containing the full AGPL-3.0 text must be committed to the repository root. - A `NOTICE` file should credit contributors and reference the license. ### 1.2 Commercial Flavor — Future Feature A separate commercial build under a proprietary license, intended for users/organizations who want the commercial sync service, premium support, or integration features. Not in v0.1 scope. --- ## 2. Repository & Project Setup ### 2.1 Hosting - **Host:** Self-hosted Gitea - **Visibility:** Public (for FOSS community contribution) - **Repository name suggestion:** `incido` ### 2.2 Package & Identity - **Application ID:** `org.incido.app` - **Display name:** Incido - **License file:** `LICENSE` (AGPL-3.0) - **Notice file:** `NOTICE` ### 2.3 Local Toolchain Requirements The following must be installed on the development machine before any build will succeed: | Tool | Version (recommended) | Purpose | |------|----------------------|---------| | JDK | 17 (LTS) | Kotlin/Java compilation | | Android Studio | Ladybug (2024.2.1) or newer | IDE, SDK management, device deployment | | Android SDK Platform | API 35 | Compile target | | Android SDK Build-Tools | 35.0.0 | Build pipeline | | Android SDK Platform-Tools | Latest | `adb` for device install | | Kotlin | 2.0.21+ | Language (bundled with Android Studio) | | Gradle | 8.10+ | Build system (wrapper handles this) | For a non-developer: Android Studio bundles JDK, Kotlin, Gradle, and the SDK. **Install Android Studio first; everything else follows.** ### 2.4 SDK Levels - `minSdk = 26` (Android 8.0 Oreo — covers ~95% of active devices) - `targetSdk = 35` (Android 15) - `compileSdk = 35` --- ## 3. Architecture & Technology Choices ### 3.1 Language & UI Framework - **Kotlin** 2.0.21+ as the primary language - **Jetpack Compose** as the UI framework (Android-recommended; maps cleanly to Compose Multiplatform for future ports) - **Kotlin Multiplatform (KMP)** with the UI in the **shared module** from day one. This is the core future-proofing decision: when iOS/Desktop ports come later, no UI rewrite is needed. ### 3.2 Build System - **Gradle 8.10+** with **Kotlin DSL** (`.kts` build files) - **Version catalog** (`gradle/libs.versions.toml`) — a single source of truth for all library versions. Critical for AI-assisted workflows to avoid version drift. ### 3.3 Module Structure (Multi-Module) The project is split into the following Gradle modules: ``` incido/ ├── app/ # Android application module (entry point, manifest, MainActivity) ├── composeApp/ # KMP shared module — UI lives here from day 1 │ └── src/ │ ├── commonMain/ # Shared Kotlin + Compose UI (works on Android, iOS, Desktop) │ └── androidMain/ # Android-specific glue (Activity host, resources) ├── core/ │ ├── data/ # KMP shared module — ObjectBox wrapper, repository, models │ └── domain/ # KMP shared module — use cases, business logic interfaces ├── gradle/ │ └── libs.versions.toml # Version catalog (single source of truth) └── settings.gradle.kts ``` **Why this structure:** - `core/data` and `core/domain` are pure Kotlin and reusable on iOS/Desktop later. - `composeApp` is the KMP UI module that all platforms consume. - `app` is just the Android wrapper (manifest, MainActivity, app icon). - Adding iOS later = create `iosApp/` module pointing at `composeApp`. Adding Desktop = add `desktopMain` source set. ### 3.4 Data Layer - **ObjectBox** for persistence - Supports KMP shared modules - Native blob support for images/audio (future-proofing media storage) - Built-in encryption support (for future feature) - Vector search capability (future-proofing semantic search) - **Data model for v0.1:** Single `NoteEntity` with fields: - `id: Long` (ObjectBox-managed) - `content: String` (the note text) - `createdAt: Long` (epoch millis) - `updatedAt: Long` (epoch millis) - **Repository pattern:** `NoteRepository` interface in `core/domain`, ObjectBox-backed implementation in `core/data`. ViewModels consume the interface, not the implementation. ### 3.5 State Management - **ViewModel + StateFlow** (standard Jetpack pattern) - Each screen has a single ViewModel exposing immutable UI state as a `StateFlow` - No third-party state management library in v0.1 (Redux/MVI/Compose-Runtime can come later if needed) ### 3.6 Navigation - **Navigation Compose** (`androidx.navigation:navigation-compose`) - Two screens in v0.1: 1. `NoteListScreen` — shows all notes as cards 2. `NoteEditorScreen` — add/edit a single note --- ## 4. v0.1 Feature Specification ### 4.1 Functional Requirements | ID | Requirement | Acceptance Criteria | |----|-------------|---------------------| | F1 | **List of currently saved notes** | On app launch (and at all times when on the home screen), the user sees a scrollable list of all notes currently stored in the database. Each note is represented as a card showing a preview of its content and its last-updated timestamp. | | F2 | Create a new note | Tapping "+" opens an empty editor; saving adds the note to the list and database. | | F3 | Edit an existing note | Tapping a note card opens the editor pre-filled with its content; saving updates the note in place and reflects the change on the list. | | F4 | Delete a note | A delete action on a note card (or in the editor) removes the note from both the list and the database. | | F5 | Data persists across restarts | Notes created in one session are visible in the list after force-closing and reopening the app. | | F6 | Empty state | When the list is empty (no notes saved), show a friendly empty-state message instead of an empty list. | | F7 | List refreshes automatically | The list of saved notes updates immediately after creating, editing, or deleting a note — no manual reload required. | ### 4.2 Non-Functional Requirements | ID | Requirement | |----|-------------| | N1 | App launches in under 2 seconds on a mid-range device | | N2 | No network permission required (offline-first) | | N3 | No analytics, telemetry, or third-party trackers | | N4 | Single APK, no dynamic feature modules | | N5 | Dark mode follows system setting (light/dark theming scaffolded for future customization) | ### 4.3 Out of Scope for v0.1 (deferred to future features) All features listed in §6. --- ## 5. UI/UX Skeleton ### 5.1 Screen 1 — Note List (Home) - **Purpose:** Display the list of currently saved notes. - **Top bar:** App title "Incido" - **Body:** - If empty: centered text "No notes yet. Tap + to start." - If populated: vertical scroll of `NoteCard` items, newest first - **Floating Action Button (FAB):** "+" icon, bottom-right, navigates to editor for a new note - **`NoteCard` design:** - Displays the note content (first ~3 lines, truncated) - Shows relative timestamp ("2 min ago", "Yesterday", etc.) - Whole card is tappable → opens editor for that note - Long-press or swipe reveals delete action ### 5.2 Screen 2 — Note Editor - **Top bar:** Back arrow + Save action - **Body:** Single multi-line `TextField` filling the screen, auto-focused - **Behavior:** - Back arrow without save = discard (no confirmation in v0.1; v0.2 should confirm if content changed) - Save action persists and returns to the list; the updated/created note is visible immediately on the list - Delete button (only when editing existing note) at bottom or in top bar overflow ### 5.3 Theming - **Material 3** (Material You) design system - **Dynamic color** on Android 12+ (system-derived accent) - **Light/Dark mode** automatic via system setting - Brand-neutral palette in v0.1 (custom theming in future) --- ## 6. Future Features (Backlog) This list is the canonical backlog. Items can be promoted into future versions as the project matures. ### 6.1 Keep Parity - Rich text formatting (bold, italic, lists, headings) - Checklists / to-do items within notes - Color-coded notes and labels - Pinning notes to top - Archive (vs. delete) with archive view - Trash with soft-delete and recovery window - Full-text search across note content - Tag / hashtag system with dedicated tag browser - Search by color, tag, or content - Reminders / time-based notifications on notes - Home screen widgets (list widget, quick-capture widget) - Share-into: receive text/images from other apps - Drawing / handwritten notes - Image attachments from camera and gallery - Audio attachments / voice notes ### 6.2 On-Device Machine Learning - **OCR (Optical Character Recognition):** - Extract text from images attached to notes - Handwriting recognition - Document scanning with perspective correction - Table extraction - **Speech-to-Text:** - Transcription of audio note attachments - Live dictation while composing notes - Translation - Speaker diarization - **Search index:** automatically index extracted OCR text for full-text search - ML inference runs entirely on-device (ML Kit, Gemini Nano, or Whisper-tiny) ### 6.3 Cross-Platform Ports - **iOS** — via Compose Multiplatform (UI already shared) - **Linux** — Compose Multiplatform Desktop (JVM) - **Windows** — Compose Multiplatform Desktop (JVM) - **macOS** — Compose Multiplatform Desktop (JVM) - Each platform shares `core/data`, `core/domain`, and `composeApp` ### 6.4 Security & Privacy - ObjectBox database encryption (AES-256 at rest) - App-lock with PIN - App-lock with biometric (fingerprint / face) - Auto-lock timeout - Encrypted exports - Secure clipboard handling ### 6.5 Sync & Cloud (Optional, Future) - Self-hosted sync server (open source, user-runs) - E2E-encrypted sync protocol - Multi-device sync - Optional premium/hosted sync service (Commercial flavor) ### 6.6 Commercial Flavor - Separate proprietary build under commercial license - Bundled sync service subscription - Premium support tier - Integration APIs for enterprise ### 6.7 Quality of Life - Markdown rendering and editing - Import from Google Keep, Evernote, plain text, Markdown files - Export to plain text, Markdown, PDF, HTML - Custom themes and color schemes - Note linking / wiki-style cross-references - Folders / notebooks in addition to tags - Versioning / note history - Undo/redo ### 6.8 Developer / Community - Continuous Integration via Gitea Actions - Automated APK builds on commit - Translation infrastructure (Weblate or Crowdin) - Contribution guidelines (`CONTRIBUTING.md`) - Code of conduct - Issue and PR templates - Documentation site (public) - Release/signing infrastructure for Play Store distribution --- ## 7. Build & Verification Plan for v0.1 ### 7.1 "Done" Definition for v0.1 v0.1 is considered complete when **all** of the following are true: 1. `./gradlew assembleDebug` succeeds on a clean clone of the repository 2. The generated APK installs on a real Android device via Android Studio's Run button 3. Manual test pass on a real device: - App launch shows the list of currently saved notes (empty state on first run) - Create 3 notes with different content → all 3 are visible on the list - Edit one note → change appears on its card on the list - Delete one note → it disappears from the list - Force-stop the app, reopen → all remaining notes still appear on the list 4. `README.md` contains: - Project description - Build instructions - Install/run instructions - License notice 5. `LICENSE` (AGPL-3.0) is committed 6. `NOTICE` is committed ### 7.2 Manual Smoke Test Script (run before tagging v0.1) ``` [ ] Launch app — see empty state message ("No notes yet. Tap + to start.") [ ] Tap FAB — editor opens, cursor in text field [ ] Type "Test note 1" — tap save — returns to list, "Test note 1" card visible [ ] Repeat for "Test note 2" and "Test note 3" [ ] Confirm all 3 notes visible on the list, newest at top [ ] Tap "Test note 2" card — editor opens with existing content [ ] Change to "Test note 2 (edited)" — tap save [ ] Confirm updated text appears on the card on the list [ ] Long-press "Test note 3" — delete option appears [ ] Confirm delete — note removed from the list [ ] Force-stop app from system settings [ ] Reopen app — "Test note 1" and "Test note 2 (edited)" both visible on the list [ ] Pass — v0.1 verified ``` --- ## 8. Development Workflow (for AI-Assisted Building) Because the developer is not a coder, the following workflow is recommended: ### 8.1 Iteration Loop 1. **State the task in plain English** to the AI coding assistant (e.g., "create the NoteEditorScreen Composable with a single TextField and a save button"). 2. **AI writes code** into the appropriate module/file. 3. **AI reports what files were created/modified.** 4. **Developer reviews the diff** in Android Studio or VS Code. 5. **Build via Android Studio** (green Run button) or terminal `./gradlew assembleDebug`. 6. **Install on real device** (Android Studio handles this). 7. **Manual smoke test.** 8. **Commit to Gitea** with a meaningful message. ### 8.2 Recommended Commit Cadence - Commit after each working milestone (e.g., "scaffold multi-module project", "implement NoteRepository", "build NoteListScreen"). - Use Conventional Commits: `feat:`, `fix:`, `chore:`, `docs:`, `refactor:`. ### 8.3 Where AI Helpers Should Place Code A short reference for AI assistants: | What you're building | Where it goes | |----------------------|---------------| | Activity / Application class | `app/src/main/kotlin/...` | | Composables (UI screens) | `composeApp/src/commonMain/kotlin/...` | | ViewModels | `composeApp/src/commonMain/kotlin/.../viewmodel/` | | ObjectBox entities | `core/data/src/commonMain/kotlin/.../entity/` | | Repositories | `core/data/src/commonMain/kotlin/.../repository/` | | Use cases | `core/domain/src/commonMain/kotlin/.../usecase/` | | Android-specific resources | `app/src/main/res/` | | Dependencies | `gradle/libs.versions.toml` (never hardcode versions elsewhere) | --- ## 9. Risks & Open Questions ### 9.1 Known Risks - **ObjectBox KMP setup is non-trivial** — first-time KMP+ObjectBox configuration may require debugging. Allow extra time for initial build configuration. - **Compose Multiplatform is mature but Android-first** — minor adjustments may be needed when iOS/Desktop ports happen. Not a v0.1 concern. - **AGPL-3.0 is strict** — some potential contributors or downstream users may prefer MIT/Apache. This is intentional per requirements; document clearly in README. ### 9.2 Open Questions (to resolve during v0.1 development) - App icon design — placeholder for v0.1; designed icon in v0.2. - Splash screen design — Android 12+ splash API; minimal in v0.1. - ObjectBox license — verify ObjectBox's own license terms are compatible with AGPL-3.0 distribution. - Play Store distribution — not in v0.1; F-Droid distribution should be evaluated for FOSS flavor. --- ## 10. Document History > **Version scheme (from v0.3.0.0 onwards):** `MAJOR.MINOR.MAINTENANCE.EMERGENCY` — > e.g. `0.3.0.0`. `MAJOR.MINOR.MAINTENANCE` are normal release numbers; > `EMERGENCY` is non-zero only for hotfixes shipped out-of-band. > `versionCode` is a monotonic int and always +1 per release. > The build refuses to compile if `versionName` doesn't match this shape. | Version | Date | Notes | |---------|------|-------| | 0.1.0.0 | 2026-08-14 | Initial plan drafted via interview | | 0.1.1.0 | 2026-08-14 | F1 explicit "list of currently saved notes" requirement + F7 auto-refresh + clarified UI section + editor IME fix (contentWindowInsets + adjustResize) + title/body on cards | | 0.2.0.0 | 2026-08-14 | Polish + first Keep-parity features. Discard-confirm dialog; release signing config (dev keystore). Favorites (renamed from Pinned Notes), full-text search, 6 colour-coded notes, inline GFM checklists (open/done counts). ObjectBox KMP migration deferred to v0.5 (tracked). | | 0.2.0.1 | 2026-08-14 | Hotfix: search-active flag folded into uiState so the search icon actually opens the field. | | 0.3.0.0 | 2026-08-14 | Hashtags (separate entity + cross-ref, 5-tag cap, autocomplete, persistent chips on editor, search() also matches tag names) + bolder colour accent (14 dp gradient stripe + tinted card background + corner chip) + nav drawer (Home / Favorites / Untagged + recent tags) + centred app-bar title + new version scheme adopted (validator in app/build.gradle.kts). | | 0.3.0.1 | 2026-08-14 | Urgent UI polish: editor hashtag row moved to the bottom (and hidden when empty), `+ add` chip removed (use `#` icon in top bar), colour picker centred horizontally, list-card dog-ear colour accent replaces the small circle chip, list cards show a hashtag row (with `+N` abbreviation when capped). | | 0.3.0.2 | 2026-08-14 | Hotfix: dropped the redundant leading `#` from the AddTagSheet placeholder (was `#tag-name`, now `hashtag-name` — the leading `#` icon in the field already signals the format). | --- ## Appendix A — Key Library Versions (for the version catalog) These versions are current as of plan drafting. The AI assistant should verify and pin them in `gradle/libs.versions.toml` at project scaffold time: | Library | Version | Purpose | |---------|---------|---------| | Kotlin | 2.0.21 | Language | | Compose Multiplatform | 1.7.0 | Cross-platform UI | | Jetpack Compose BOM | 2024.10.00 | Android UI | | AndroidX Lifecycle | 2.8.7 | ViewModels, lifecycle | | AndroidX Navigation Compose | 2.8.4 | Screen navigation | | AndroidX Activity Compose | 1.9.3 | Activity integration | | ObjectBox | 4.0.3 | Database | | Coroutines | 1.9.0 | Async | (AIs: confirm latest stable versions before scaffolding.)