Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/apursley2012/PunctuOwlity/llms.txt

Use this file to discover all available pages before exploring further.

The PunctuOwlity Android app is the original version of the project — a native Java application using SQLite for persistent storage and Material Design components for the UI. It targets API 35 (Android 15) and supports devices back to API 21 (Android 5.0 Lollipop). The app declares the SEND_SMS permission with telephony marked as optional (android:required="false"), so it installs and runs correctly on emulators and tablets that do not have a SIM card. This guide walks you through cloning the source, opening it in Android Studio, and running it on an emulator or physical device.

​
Prerequisites

  • Android Studio — latest stable release (Hedgehog or newer recommended)
  • JDK 11 or higher — the project sets sourceCompatibility and targetCompatibility to JavaVersion.VERSION_11
  • Android SDK with API 35 — install via Android Studio’s SDK Manager under SDK Platforms
  • An emulator or USB-connected physical device running Android API 21 or higher
The project’s build.gradle sets compileSdk 35, minSdk 21, and targetSdk 35. Make sure you have the API 35 platform installed in your SDK Manager before attempting to sync or build. The build file also applies the Kotlin Android and Kotlin Compose plugins, so Android Studio’s Kotlin support must be available even though the Activity source files are written in Java.

​
Getting Started

1

Clone the repository

Clone the PunctuOwlity repository to your local machine:
git clone https://github.com/apursley2012/PunctuOwlity.git
The Android source lives inside the android-fixed-source/ directory. You do not need to open the root of the repository — Android Studio should be pointed directly at the Gradle project folder.
2

Open the Android project in Android Studio

Launch Android Studio and choose File → Open (or Open from the Welcome screen). Navigate to:
PunctuOwlity/android-fixed-source/PunctuOwlityEventTracker/
Select that folder and click OK. Android Studio will recognize the build.gradle at the root of the module and treat it as a standard Gradle Android project.
3

Wait for Gradle sync to complete

Android Studio will automatically begin a Gradle sync after the project opens. The sync downloads the declared dependencies — appcompat, material, constraintlayout, gridlayout, lifecycle-runtime-ktx, and the Compose BOM — from Maven Central. This may take a minute or two on first run.Watch the Build panel at the bottom of Android Studio. When you see Gradle sync finished, the project is ready to build.If the sync fails with a missing SDK error, open File → Project Structure → SDK Location and confirm that the Android SDK path points to a valid installation that includes API 35.
4

Select a run target and click Run

In the Android Studio toolbar, open the device dropdown (next to the run ▶ button) and select an existing AVD emulator or a connected physical device. If you need to create an emulator, go to Tools → Device Manager → Create Device and choose a phone profile with a system image at API 21 or higher.Click Run ▶ (or press Shift+F10). Android Studio will compile the project, assemble a debug APK, install it on the selected device, and launch the app. The first screen you see will be the Login screen — LoginActivity is declared as the launcher activity in AndroidManifest.xml.
5

Grant SMS permission when prompted

When MainActivity starts, it immediately checks whether the SEND_SMS permission has already been granted by the OS. If the permission is not yet held, MainActivity launches SmsPermissionActivity before rendering the events grid. The app has declared android.permission.SEND_SMS in its manifest, and telephony hardware is marked android:required="false" so the app installs and runs on devices and emulators without cellular capability.
  • Tap Allow to trigger the Android system permission dialog. Once you grant the permission, the app proceeds to the events screen. Because the OS permission is now held, MainActivity will no longer launch this screen on future starts.
  • Tap Deny to proceed to the events screen without SMS alerts. Because the permission was never granted, MainActivity will check again and re-display this screen on every subsequent launch until you allow the permission.
Unlike the web app, the Android version does not store your SMS choice in a persistent preference — it reads the live OS permission state each time MainActivity starts. Granting the permission is the only way to prevent the screen from appearing again.
6

Create an account and add events

On the Login screen, tap Sign Up to open SignupActivity. Enter a username and password, then tap Sign Up to create your account. The Android sign-up form collects a username (stored in the username column), a password, and a confirm-password field. Credentials are stored directly in the SQLite users table.Once logged in and past the SMS screen, you land on MainActivity — the events grid. Tap the floating ＋ button to open AddEventActivity. Enter an event title, date, and time, then tap Save to write the record to the SQLite database. Your event will appear as a card in the two-column grid.Tap the edit icon on any card to reopen AddEventActivity pre-populated with that event’s data. Tap the delete icon to remove it permanently from the database.

​
Package and Activity Reference

The application’s package name is com.example.punctuowlityeventtracker. The five activities declared in AndroidManifest.xml are:
ActivityExportedRole
LoginActivitytrue (launcher)Entry point — username + password login
SignupActivityfalseNew account registration
SmsPermissionActivityfalseSMS permission request screen, shown from MainActivity when permission is not granted
AddEventActivityfalseAdd a new event or edit an existing one
MainActivityfalseEvents grid — browse, search, and manage events

​
Database Schema

PunctuOwlity stores all data in a private SQLite database named punctuowlity.db, managed by the DatabaseHelper class (extends SQLiteOpenHelper). The database contains two tables: 
-- User accounts
CREATE TABLE users (
  id       INTEGER PRIMARY KEY AUTOINCREMENT,
  username TEXT UNIQUE,
  password TEXT
);

-- Events
CREATE TABLE events (
  id    INTEGER PRIMARY KEY AUTOINCREMENT,
  title TEXT,
  date  TEXT,
  time  TEXT
);
The DatabaseHelper exposes methods for inserting users (insertUser), authenticating (checkUser), and full CRUD on events (insertEvent, updateEvent, deleteEvent, getAllEvents, getEventById).
The SQLite database file punctuowlity.db is private to the app’s data directory on the device (/data/data/com.example.punctuowlityeventtracker/databases/). It is not accessible to other apps and is removed when the app is uninstalled.
PunctuOwlity is a demonstration project. User passwords are stored in plain text in the SQLite users table — there is no hashing or salting. Do not use a password that you use for any real account, and do not ship this app to production users without implementing a proper password-hashing scheme (e.g., bcrypt) and a secure authentication flow.

Build docs developers (and LLMs) love

Get started for freeTalk to us