https://github.com/quentingenet/esperanzapp
Habit & abstinence tracker : private, free, no account, no ads.
https://github.com/quentingenet/esperanzapp
android capacitor fdroid gplv3 mui react sqlite typescript vite
Last synced: 1 day ago
JSON representation
Habit & abstinence tracker : private, free, no account, no ads.
- Host: GitHub
- URL: https://github.com/quentingenet/esperanzapp
- Owner: quentingenet
- License: gpl-3.0
- Created: 2026-06-29T16:54:37.000Z (11 days ago)
- Default Branch: main
- Last Pushed: 2026-07-07T05:50:33.000Z (4 days ago)
- Last Synced: 2026-07-07T07:20:51.859Z (4 days ago)
- Topics: android, capacitor, fdroid, gplv3, mui, react, sqlite, typescript, vite
- Language: TypeScript
- Homepage:
- Size: 19.2 MB
- Stars: 1
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# EsperanzApp
[](https://ko-fi.com/quentingenet)
Find EsperanzApp useful? Support its development - iOS release is on the roadmap...
**EsperanzApp** is a free, open-source, and privacy-first mobile application to help you break free from toxic habits and addictions, one day at a time.
No account. No server. No tracking. Everything stays on your device.
> _Esperanza_ : hope, in Spanish.
---
## Why EsperanzApp?
Breaking a habit is hard. Most apps make it harder: they require accounts, harvest your data, or shame you when you relapse.
EsperanzApp does none of that. It counts your days with you, celebrates your milestones, and, when a relapse happens, it reminds you that those days counted and that you can start again.
---
## Features
🔢 **Day Counter**
Track your streak since the last relapse for each habit. Every day counts...
🏆 **Milestones**
1 day, 7 days, 30 days, 90 days, 1 year… Each milestone is celebrated.
🔄 **Relapse, without shame**
If you relapse, those days are not erased. Press "Start again" and keep going. The journey continues.
💊 **Treatment Tracker**
Log your daily treatments or medications alongside your habits and be notified.
📊 **Stats & History**
Charts, streaks, history timeline: visualize your progress and understand your patterns.
🌍 **7 languages**
French · English · Spanish · German · Portuguese (BR) · Dutch · Italian, with full i18n support.
🔒 **Private by design**
No account required. No backend, no analytics, no advertising. Your data is stored in a local SQLite database and leaves your device only when you explicitly export or share it.
📤 **Export your data**
Export your history as JSON or CSV at any time, and save it wherever you want. Your data belongs to you.
---
## Stack
| Layer | Technology |
| -------- | ---------------------------------------- |
| UI | React 19 + TypeScript + MUI v9 |
| Build | Vite 8 |
| Mobile | Capacitor v8 (Android) |
| State | Zustand v5 |
| Database | SQLite via `@capacitor-community/sqlite` |
| i18n | i18next (7 locales) |
| Tests | Vitest + Testing Library |
---
## Get the app
EsperanzApp is available on the Google Play Store. You can also build it yourself from source (see instructions below).
---
## Run locally (development)
### Prerequisites
- [Node.js](https://nodejs.org/) ≥ 20
- [npm](https://www.npmjs.com/)
- Android Studio + Android SDK (for device/emulator builds)
- **Java JDK 17 or newer** with `JAVA_HOME` defined. Gradle picks it up automatically; no path is stored in the project. [sdkman](https://sdkman.io/) is a convenient way to manage JDK versions.
### Clone
```bash
git clone https://github.com/quentingenet/esperanzapp.git
cd esperanzapp
```
### Install & run in browser
```bash
npm install
npm run dev
```
Open [http://localhost:5173](http://localhost:5173)
### Build & run on Android
```bash
npm run build
npx cap sync android
npx cap run android # requires a connected device or emulator
```
Or open in Android Studio:
```bash
npx cap open android
```
### Tests
```bash
npm run test
```
### Lint
```bash
npm run lint
```
---
## Build a signed release (Android)
```bash
# 1. Build web assets
npm run build && npx cap sync android
# 2. Generate signed AAB (Play Store) or APK (sideload)
cd android
./gradlew bundleRelease # AAB
./gradlew assembleRelease # APK
```
Output: `android/app/build/outputs/`
---
## Android permissions
EsperanzApp requests the **minimum permissions necessary** to function. No `INTERNET` permission is declared by the app. No contacts, no camera, no location.
| Permission | Prompted? | Requested by | Why |
| ------------------------ | ----------------------------- | ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `POST_NOTIFICATIONS` | **Yes** (Android 13+) | You, when adding your first treatment | To send daily reminders to take your medication. You can decline: the app works fully, you just won't receive notifications. |
| `SCHEDULE_EXACT_ALARM` | **Yes** (Android 14+, manual) | You, via in-app prompt | Delivers treatment and medication reminders at the exact time the user has configured. Exact scheduling is the core feature of EsperanzApp: a reminder that fires 10 or 20 minutes late is not acceptable for someone following a treatment schedule. Without this permission, the OS places notifications in a low-priority batch window and may delay them by several minutes. This permission is declared in accordance with Google Play's requirements for applications whose primary use case is scheduling exact reminders chosen by the user. Granted automatically on Android 12 and 13. On Android 14 and later, the user enables it via the dedicated "Alarms and Reminders" system screen for this app specifically; the app detects the missing permission and opens that screen automatically. Treatment reminders are named freely by the user; the application does not require or suggest any specific medication name, dosage, or clinical detail. A reminder can simply be called "Morning routine" or any other label the user chooses. |
| `RECEIVE_BOOT_COMPLETED` | No (automatic) | `@capacitor/local-notifications` | Re-schedules your treatment reminders after a phone restart, so they don't disappear when you reboot. |
| `WAKE_LOCK` | No (automatic) | `@capacitor/local-notifications` | Allows the system to briefly wake the CPU to deliver a notification on time. Not declared in the app's own `AndroidManifest.xml` — injected by the library's manifest during Gradle's merge phase. |
| `VIBRATE` | No (automatic) | App | Allows notifications to vibrate. No prompt, no personal data. |
**No** `INTERNET`, `READ_EXTERNAL_STORAGE`, `WRITE_EXTERNAL_STORAGE`, `ACCESS_FINE_LOCATION`, `READ_CONTACTS`, or any other sensitive permission is requested.
One note on the update check: the app uses the Google Play In-App Updates API (`@capawesome/capacitor-app-update`) to check whether a newer version is available. This call goes through Google Play Services and does not require the `INTERNET` permission to be declared by the app itself. No health data is involved in this exchange. See the privacy section below for more detail.
### How file export works
The app offers two export paths.
**Share** writes the file to the app's private cache, a temporary folder only EsperanzApp can access, then opens the Android Share Sheet so you pick the destination (file manager, cloud storage, email, USB, etc.). The app hands the file off to your chosen app and immediately loses access to it.
**Save to phone** writes the file to the app's dedicated Documents folder (`Android/data/com.quentingenet.esperanzapp/files/Documents/`). This is app-specific storage, not the device's shared public Documents folder. On Android 11 and later, this path is not accessible to third-party file managers; it can be browsed with the built-in Files app or via USB. The in-app warning shown before saving explains this.
---
## Privacy policy
EsperanzApp does not collect personal data and has no backend server. There are no analytics, no crash reporting service, and no advertising SDK.
All health data (habits, treatments, logs) is stored exclusively in a local SQLite database on your device, encrypted at rest with AES-256. It never leaves your device automatically.
Two non-medical items are stored in `localStorage`: your language preference and your onboarding completion status. These remain on your device and are never transmitted.
The app includes one outbound call that does not carry health data: at startup, it queries the Google Play In-App Updates API to check whether a newer version is available. This is handled by Google Play Services. If you do not want this behavior, the manual "Check for updates" button in Settings performs the same check on demand; the startup check can be disabled in a future version if there is demand for it.
Downloading EsperanzApp through Google Play is subject to Google's own data practices for the Play Store platform. EsperanzApp itself has no control over, and no visibility into, the metadata Google collects at the platform level.
The full privacy policy is available in [PRIVACY_POLICY.md](PRIVACY_POLICY.md).
---
## Disclaimer
EsperanzApp is a personal habit and routine tracking tool. It is not a medical device and does not provide medical advice, diagnosis, or treatment recommendations. It does not replace a qualified healthcare professional. Any decision relating to a medical treatment, medication schedule, or health condition should be made in consultation with a licensed healthcare provider.
---
## Contributing
Contributions are welcome: bug reports, translations, UI improvements, or new features.
1. Fork this repository
2. Create a feature branch from `main`: `git checkout -b feat/my-feature`
3. Commit your changes: `git commit -m 'feat: add amazing feature'`
4. Push: `git push origin feat/my-feature`
5. Open a Pull Request
Please keep pull requests focused and small. One feature or fix per PR.
---
## License
EsperanzApp is released under the **GNU General Public License v3.0**.
This means you are free to:
- Use it
- Study and modify it
- Share it
- Share your modifications, under the same license
See [LICENSE](LICENSE) for the full text.
---
## Author
**Quentin Genet**
If you find EsperanzApp useful, a ⭐ on GitHub goes a long way.
If you'd like to support the development: [ko-fi.com/quentingenet](https://ko-fi.com/quentingenet)