Developers
Build & contribute
Build a clean local Android app, verify changes, and extend a module without embedding personal data or shared credentials.
In the appRepository → develop
On this page
Project structure
| Area | Responsibility |
|---|---|
| core/ | Typed models, validation, module defaults/preferences, context scope, budgets, ranking, and backup contracts. |
| app/ | Jetpack Compose UI, repositories, provider transports, browser account flow, local alarms, and background work. |
| service/ | Optional single-person Python service with authenticated endpoints, SQLite, provider isolation, and its own cap. |
| docs/ | User/developer contracts, native screenshots, release evidence, and this dependency-free static site. |
Read AGENTS.md, the contribution guide, and the full development reference before changing behavior. Development uses develop; stable public source is on master.
Set up the Android build
Use JDK 17, Android SDK platform 36, and Build Tools 35.0.0. The repository pins Gradle 8.13, Android Gradle Plugin 8.13.2, and Kotlin 2.2.21. The app targets API 36 and supports API 26+.
git clone https://github.com/EmmanuelMmanda/MeBot.git cd MeBot git switch develop
sdkmanager "platform-tools" "platforms;android-36" "build-tools;35.0.0" sdkmanager --licenses
Configure your own JAVA_HOME and ANDROID_HOME, review SDK licenses, and keep machine-specific SDK/proxy paths out of source. The first build downloads public dependencies. A clean build needs no private profile, live AI key, or owner account.
Build and verify
Run the project’s required verification gate from the repository root:
./scripts/build.sh verify
It runs core tests, app host tests, debug lint, and debug APK assembly. The equivalent wrapper tasks are:
./gradlew :core:test :app:testDebugUnitTest :app:lintDebug :app:assembleDebug
Windows can run the same tasks with .\gradlew.bat. For an APK-only iteration, ./scripts/build.sh debug assembles the debug variant; it does not replace the review gate.
adb install -r app/build/outputs/apk/debug/app-debug.apk
Debug uses mebot.nguli.com.debug and can coexist with release. Native UI screenshots use synthetic host fixtures; tests do not prove live account eligibility, physical Keystore behavior, or a phone’s overnight alarm delivery.
Read the verification record and device acceptance guide for the remaining live/physical checks.
Keep configuration and credentials separate
Public defaults belong in reusable typed configuration. Personal preferences belong in reviewed runtime context. The empty context example supplies the portable format; modules: [] preserves the user’s choices on import.
The connection routes have different credentials and billing. Do not silently fall back from ChatGPT to API billing, send OAuth tokens through a personal service, or ship a shared developer key. A failed or cancelled replacement must preserve the existing connection.
Only confirmed module-scoped notes may enter a request. A reusable default focus does not grant broader context. Treat fetched pages, attachments, previous messages, and user topics as data rather than privileged instructions. Keep factual-link evidence checks and bounded public-HTTPS networking intact.
Run the optional service
Use Python 3.12 and an isolated environment inside service/. Tests use a fake provider and do not need a paid account.
python3 -m venv .venv .venv/bin/python -m pip install -r requirements-dev.txt .venv/bin/python -m pip check .venv/bin/python -m pytest -q --junitxml=test-results.xml
Production needs a protected provider key, a distinct service token, persistent storage, and public HTTPS routing. It is one person per deployment, not a multi-tenant hosted account system. Match the app model to MEBOT_MODEL.
The service has its own attempted-call cap, default 48 per UTC day, and returns completed answers. The supplied local configuration is not automatically reachable from an Android phone. Use the full service deployment reference for environment variables, endpoints, and retention.
Add a module properly
- Add a typed kind/preset with purpose, category, output, and real retrieval capability in ModuleCatalog.
- Add validated kind-specific choices in ModulePreferences and reusable editorial guidance in ModuleDefaults.
- Provide English and Kiswahili strings, default focus, editor controls, icons, grouping, and accessible ordering.
- Wire discovery, story answers, and search with relevant confirmed context only. Extend service schemas/defaults if that route supports the kind.
- Test meaningful validation, scope, evidence, persistence, and failure cases using local fixtures. Verify the actual narrow-screen journey.
- Update the user catalog, FAQ, request contracts, and changelog. New kinds should arrive paused without rewriting saved preferences.
A source adapter needs a legitimate public retrieval contract, timeouts, size bounds, safe redirects, and credential isolation. A private connector needs its own explicit authorization design; an AI grant is not permission to access another account.
Release and contribute
Release signing identity is part of update compatibility. A new key cannot update an existing release signed by another key. The latest production app is publicly released. Building its source does not reproduce a production signature; any distributed update needs the correct package, signing certificate and higher version code.
Keep keystores, signing passwords, API/OAuth secrets, personal profile assets, exports, databases, local SDK paths, and build caches out of public source. Configure signing privately using the documented MEBOT_* environment variables.
See release signing and publication, public artifact provenance, and CONTRIBUTING.md. This site’s download manifest stays pending until the corresponding public assets and tags are verified.
Code is Apache 2.0; retain LICENSE, NOTICE, the Figtree license, and other applicable source/media notices. Report sensitive issues through the security policy.
Some steps depend on the installed app release. Check the download page for the version currently offered and the verification record for known device/provider limits.