v0.3.0.0 bundles four user-facing features, the plan-compliance polish
that was deferred from v0.2, and a permanent change to how we name
releases going forward.
VERSION SCHEME (app/build.gradle.kts)
- versionName = '0.3.0.0' (MAJOR.MINOR.MAINTENANCE.EMERGENCY)
- versionCode = 5
- New gradle taskGraph validator fails the build if versionName
doesn't match ^\d+\.\d+\.\d+\.\d+$ — we can't accidentally
regress the scheme.
- History re-keyed across README, Plan §10, CONTRIBUTING.md.
HASHTAGS
- value class Hashtag (domain/model) with normalise/parseOrNull
helpers; pattern: ^[a-z0-9][a-z0-9._-]{0,30}$
- data class HashtagUsage (name, noteCount, lastUsedAt)
- sealed class NoteFilter { Home, Favorites, Untagged, ByTag(name) }
- Note gains hashtags: List<String> (sorted ascending)
- Repository:
- new entities HashtagEntity (@Index on name) and
NoteHashtagCrossRef (many-to-many junction)
- new methods: observeFavorites / observeUntagged /
observeNotesForHashtag / observeHashtagsByRecentUse /
observeAllHashtags / searchHashtags / addHashtag / removeHashtag
- search() now matches content OR hashtag-name (case-insensitive)
- ObjectBox queries use explicit StringOrder + type annotations
(kapt's stubs are finicky around Property<String> overloads)
UI
- CenterAlignedTopAppBar on both list and editor screens
- List:
- Hamburger top-left opens a ModalNavigationDrawer (Home /
Favorites / Untagged / divider / scrollable Recent tags)
- Drawer selection drives a NoteFilter state held at root
- Search bar visible only when filter == Home
- NoteCard redesign — 14 dp vertical gradient stripe +
tinted surface (12 % colour blend) + 10 dp corner chip
- Empty-state copy is filter-aware
- Editor:
- Persistent hashtag chip row above the text field
- Tag # icon in the top bar + '+ add' chip opens a ModalBottomSheet
- Autocomplete suggestions live from repository.searchHashtags
- '+ Create name' button when the typed value is valid + new
- Snackbar 'Maximum 5 tags reached.' when the cap is hit
- Reconciled on save via addHashtag / removeHashtag diff
DOCS
- README v0.3.0.0 section + re-keyed changelog
- Development Plan §10 history re-keyed (0.1.0.0 / 0.1.1.0 /
0.2.0.0 / 0.2.0.1 / 0.3.0.0)
- CONTRIBUTING.md release-process note updated for the new scheme
VERIFIED
- ./gradlew assembleDebug assembleRelease both green
- Debug 25.7 MB, release 19.8 MB (v2-signed)
- versionCode=5, versionName='0.3.0.0'
- No INTERNET permission
- Validator regression: setting versionName='0.3' causes
assembleDebug to fail with the new scheme error message
397 lines
18 KiB
Plaintext
397 lines
18 KiB
Plaintext
# 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<UiState>`
|
|
- 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). |
|
|
|
|
|
|
---
|
|
|
|
## 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.)
|