Hey AI Logo # Hey AI ### Persian smart personal assistant · by **DevDasht** Natural-language reminders · triple calendar · multi-layer alarms · admin panel **Android (Kotlin + Compose) · PHP 8.3 · MySQL · MIT**
[![Live Demo](https://img.shields.io/badge/Live_Demo-GitHub_Pages-7C4DFF?style=for-the-badge&labelColor=0A0E28)](https://askarniroomand.github.io/Hey/) [![Download APK](https://img.shields.io/badge/Download_APK-v1.0.1-00BCD4?style=for-the-badge&labelColor=0A0E28)](https://github.com/askarniroomand/Hey/releases) [![License: MIT](https://img.shields.io/badge/License-MIT-7C4DFF?style=for-the-badge)](LICENSE) [![CI](https://img.shields.io/github/actions/workflow/status/askarniroomand/Hey/ci.yml?style=for-the-badge&label=CI)](https://github.com/askarniroomand/Hey/actions) [![Stars](https://img.shields.io/github/stars/askarniroomand/Hey?style=for-the-badge&color=FFC107)](https://github.com/askarniroomand/Hey/stargazers)
Hey AI — Persian Smart Assistant by DevDasht

Open Source · Production-oriented structure · No API secrets in the repository

[English](#hey-ai) · [فارسی](#-فارسی)
--- # Hey AI **Hey AI** is a Persian-first personal assistant that turns natural language into structured reminders, with a native Android client, a modular PHP API, and an operations-ready admin panel. --- ## Features | Feature | Description | |:--------|:------------| | **DevDasht AI NLP** | Persian phrases → structured reminders (“فردا ساعت ۵ برو دکتر”) | | **Triple calendar** | Jalali · Gregorian · Hijri with month/week/day views | | **Multi-layer alarms** | Fullscreen · vibration · flash · TTS · snooze · re-alert · FCM | | **AI personas** | Multiple assistant tones (fun, formal, coach, …) | | **Admin panel** | Users · ads · notifications · AI center · logs · backups · roles | | **Production security** | JWT access/refresh · rate limits · server-side AI keys only | | **Hosting pack** | Shared-host friendly tree under `hosting/` | | **Live demo** | Static interactive preview on GitHub Pages |
Full capability list - Create / edit / delete reminders with priority, color, category, location, attachments - Multi-offset reminder chains (5/10/30 minutes, hours, days, weeks, custom) - Home-screen “today” widget synced with Room - Onboarding: name, age, gender, theme, voice, persona - Banner / interstitial / native / rewarded ad slots (configurable) - Crash reporting hooks · FCM · admin broadcast - OpenAPI + Swagger UI for the HTTP API
--- ## Tech stack | Layer | Stack | |:------|:------| | Mobile | Kotlin · Jetpack Compose · Room · Hilt · FCM | | API | PHP 8.3 · custom modular core · JWT · middleware | | Database | MySQL 8 · SQL migrations | | Admin | PHP views · RTL CSS | | Docs | Markdown · OpenAPI | | Demo | Static HTML | --- ## Architecture ```text ┌──────────────┐ HTTPS/JSON ┌────────────────┐ │ Android App │ ──────────────────► │ PHP API │ │ Compose UI │ ◄────────────────── │ modules/* │ │ Room cache │ │ services/* │ └──────────────┘ └───────┬────────┘ │ ┌──────────────┐ ▼ │ Admin Panel │ ──────────────────► MySQL 8 └──────────────┘ cron: push, backup, cleanup, AI digest ``` | Module | Responsibility | |:-------|:---------------| | `Auth` | Register/login, JWT issue/refresh | | `Reminder` | CRUD + scheduling metadata | | `AI` | NLP parse via server-side provider | | `Admin` | Dashboard & operations | | `Ads` / `File` / `User` | Supporting domains | Deep dives: [`docs/02-architecture.md`](docs/02-architecture.md) · [`docs/05-api.md`](docs/05-api.md) --- ## Screenshots > **Placeholder — add device frames under `docs/media/`.** | Home | Reminder editor | Alarm | Admin | |:----:|:---------------:|:----:|:-----:| | ![Home](docs/media/shot-home.png) | ![Editor](docs/media/shot-editor.png) | ![Alarm](docs/media/shot-alarm.png) | ![Admin](docs/media/shot-admin.png) | --- ## Requirements ### Android build - Android Studio Hedgehog+ (or recent stable) - JDK 17 - Android SDK 34+ - Optional: Firebase project for FCM / Crashlytics ### API / admin - PHP 8.3+ - MySQL 8+ - HTTPS-capable host (Apache/Nginx) - `openssl`, `pdo_mysql`, `json`, `mbstring` extensions ### Demo only - Any static file server (or GitHub Pages) --- ## Installation ### 30-second paths | Path | Action | |:-----|:-------| | Demo | [Open live demo](https://askarniroomand.github.io/Hey/) | | APK | [Download release](https://github.com/askarniroomand/Hey/releases) | | Source | Clone steps below | ```bash git clone https://github.com/askarniroomand/Hey.git cd Hey # Static demo cd demo && python3 -m http.server 8080 ``` ### Backend (development) ```bash cd backend # 1) Create DB and import database/schema.sql (or migrations) # 2) Copy env example → configure DSN + JWT secret # 3) Point document root to backend/public php -S 0.0.0.0:8080 -t public ``` ### Android ```bash cd android # Add local google-services.json from Firebase (never commit real file) ./gradlew assembleDebug ``` ### Shared hosting See [HOSTING-GUIDE-FA.md](./HOSTING-GUIDE-FA.md) and the `hosting/` package. Complete guide: [INSTALL.md](./INSTALL.md) --- ## Usage ### End users (app) 1. Install APK or build debug 2. Complete onboarding 3. Type a Persian natural-language reminder or use the form UI 4. Allow notification / exact-alarm permissions for reliable alerts ### Operators (admin) 1. Deploy API + import schema 2. Set admin password via `scripts/set_admin_password.php` 3. Open admin login · manage users, ads, broadcasts, backups ### API example ```bash # Login curl -s -X POST https://YOUR_HOST/api/auth/login \ -H 'Content-Type: application/json' \ -d '{"username":"demo","password":"secret"}' # Create reminder (Bearer token) curl -s -X POST https://YOUR_HOST/api/reminders \ -H "Authorization: Bearer $TOKEN" \ -H 'Content-Type: application/json' \ -d '{"title":"Doctor","due_at":"2026-07-20T17:00:00+03:30"}' ``` OpenAPI: [`docs/openapi.yaml`](docs/openapi.yaml) · Swagger UI under `backend/public/swagger.html` --- ## Configuration | Setting | Location | Notes | |:--------|:---------|:------| | DB DSN / credentials | `.env` / host config | Never commit | | JWT secret | server env | Long random string | | AI provider key | server only | Never ship inside the APK | | FCM | Firebase + server | Use example JSON in git | | Ad unit IDs | admin / config | Prefer remote config | | App API base URL | Android build config | Point to your host | --- ## Project structure ```text Hey/ ├── android/ # Kotlin application ├── backend/ # PHP API (canonical server code) │ ├── core/ middleware/ modules/ services/ │ ├── public/ # front controller + swagger │ └── tests/ ├── admin/ # Admin UI (dev tree) ├── database/ # schema · migrations · seeds ├── demo/ # GitHub Pages interactive demo ├── docs/ # Architecture, API, security, roadmap ├── hosting/ # Shared-host deploy bundle ├── releases/ # Public APK artifacts ├── scripts/ # DB helpers ├── CONTRIBUTING.md ├── SECURITY.md ├── CODE_OF_CONDUCT.md ├── CHANGELOG.md └── LICENSE ``` --- ## Roadmap - [x] MVP Android + API + admin - [x] NLP reminder capture - [x] Public demo + APK release - [x] Security / contributing baselines - [ ] Broader automated test coverage in CI - [ ] English UI pack (optional language toggle) - [ ] Widget polish + offline conflict resolution - [ ] Hardened rate limits & abuse controls See [`docs/08-roadmap.md`](docs/08-roadmap.md). --- ## Future plans 1. Public plugin system for reminder channels 2. End-to-end encrypted backup export 3. Tablet layouts 4. Contributor “good first issue” board 5. Rename discussion: package id vs public name consistency --- ## Known issues | Issue | Severity | Notes | |:------|:---------|:------| | `hosting/public_html` can drift from `backend/` + `admin/` | Medium | Prefer generate-from-source script (planned) | | Android tests are thin | Medium | Accepting PRs | | AI quality depends on provider & prompt | Medium | Server-side only — swap provider carefully | | Exact alarms restricted on some OEMs | Medium | Document OEM permission steps | --- ## FAQ
Is this production ready? The structure is production-oriented. You must still configure secrets, HTTPS, backups, and monitoring for your environment.
Where do AI keys live? Only on the server. The Android app must never embed provider tokens.
Can I use it without AI? Yes — manual reminder forms still work if AI endpoints are disabled.
Why is the repo named Hey? Product name is Hey AI under the DevDasht brand. A future rename to `hey-ai` may improve discoverability.
How do I report security issues? Privately via Telegram — see SECURITY.md.
--- ## Contributing Please read [CONTRIBUTING.md](./CONTRIBUTING.md) and [CODE_OF_CONDUCT.md](./CODE_OF_CONDUCT.md). 1. Fork + branch 2. Make changes without secrets 3. Open a PR with screenshots for UI work --- ## Changelog See [CHANGELOG.md](./CHANGELOG.md) and GitHub Releases. --- ## License MIT © Askar Niroomand / DevDasht — [LICENSE](./LICENSE) --- ## Contact | Channel | Link | |:--------|:-----| | Author | [github.com/askarniroomand](https://github.com/askarniroomand) | | Telegram | [t.me/MRROBOT_DT](https://t.me/MRROBOT_DT) | | Live demo | https://askarniroomand.github.io/Hey/ | --- ## فارسی **Hey AI** دستیار هوشمند شخصی فارسی است: یادآور با زبان طبیعی، تقویم شمسی/میلادی/قمری، آلارم چندلایه، اپ اندروید بومی و API ماژولار PHP. | شروع سریع | لینک | |:----------|:-----| | دمو | https://askarniroomand.github.io/Hey/ | | APK | [Releases](https://github.com/askarniroomand/Hey/releases) | | نصب کامل | [INSTALL.md](./INSTALL.md) | | هاست اشتراکی | [HOSTING-GUIDE-FA.md](./HOSTING-GUIDE-FA.md) | مشارکت: [CONTRIBUTING.md](./CONTRIBUTING.md) · امنیت: [SECURITY.md](./SECURITY.md) ---

Built with care for Persian users · Star the repo if it helps you