Period Vault
Privacy-First, Offline-First Period Tracking
A native mobile application for iOS and Android built with Kotlin Multiplatform, designed for maximum privacy, zero data collection, and complete offline functionality.
Documentation map: This README is the single source for app functionality and product map — what the app does and how features fit together. BACKLOG.md lists only remaining work (incomplete items). COMPLETED-WORK.md archives completed backlog items with evidence. Engineering architecture, data model, development workflow, testing internals, and contribution process live in DEVELOPER-GUIDE.md.
Table of Contents
Overview
Period Vault is a menstrual cycle tracking application that prioritizes user privacy above all else. Unlike mainstream period trackers that monetize user data, Period Vault:
- Stores 100% of data locally on device
- Functions completely offline (no network required)
- Collects zero analytics or telemetry
- Contains no ads or third-party integrations
- Provides native iOS and Android experiences
- Encrypts all backups with AES-256-GCM
The project is governed by a Constitution (v3.0.0, 20 principles) that enforces privacy, platform parity, testing standards, and architectural discipline.
Features
Core user-facing functionality is implemented on both iOS and Android unless noted.
| Feature | What users can do | Platforms |
|---|---|---|
| Period tracking | Add, edit, delete period entries with overlap/date validation and ongoing-period support | iOS + Android |
| Prediction + statistics | View next predicted period and cycle stats when enough history exists | iOS + Android |
| Calendar + day detail | Browse month view with period, symptom, and flow markers; tap day for detail | iOS + Android |
| Flow intensity logging | Set spotting/light/medium/heavy per day during a period | iOS + Android |
| Symptom logging + history | Log symptoms with severity/notes, filter history, edit/delete entries | iOS + Android |
| Medication tracking | Add medications and toggle taken/not-taken status for today | iOS + Android |
| History management | Review period history, open entries for edit, delete with confirmation | iOS + Android |
| CSV import | Import period data with preview, validation, and conflict handling | iOS + Android |
| Encrypted backup/restore | Create encrypted backup and restore local data from passphrase-protected file | iOS + Android |
| Settings | Configure theme, date format, first day of week, and data actions | iOS + Android |
Navigation model:
- Bottom tabs:
Home,Calendar,Symptoms,History - Secondary screens:
AddEditPeriod,Medication,Settings,SymptomHistory,Import
Known gaps (tracked in BACKLOG.md):
M6.1: selectable alternate app iconsM7.1: local reminders/notifications
Privacy & Security
Zero Data Collection
Period Vault collects absolutely zero data:
- No user accounts or authentication
- No cloud storage or sync
- No analytics or telemetry
- No crash reporting
- No advertising or tracking SDKs
- No network calls for any functionality
Local-First Storage
All data stored locally using SQLDelight (SQLite) with platform-native drivers:
- Android:
AndroidSqliteDriver - iOS:
NativeSqliteDriver - Tests:
JdbcSqliteDriver(in-memory)
Encrypted Backup/Restore
Backups are encrypted with:
- Algorithm: AES-256-GCM (authenticated encryption)
- Key Derivation: PBKDF2-HMAC-SHA256 with 210,000 iterations
- Salt: 16 random bytes per backup
- Nonce: 12 random bytes per backup
- AAD:
"periodvault-backup:1"(authenticated additional data) - Restore: Atomic — either all data is replaced or none is (no partial writes)
- Platform crypto: Android uses
javax.crypto.Cipher, iOS uses CryptoKit via Swift bridge - No third-party crypto libraries
Backup format:
{
"version": 2,
"salt": "<base64>",
"nonce": "<base64>",
"ciphertext": "<base64>"
}
Backup file I/O is fully implemented: Android uses SAF (Storage Access Framework) for file save/open, iOS uses share sheet for export and document picker for import.
Getting Started
Prerequisites
Required (all platforms):
- Git
- JDK 17+ (for Gradle)
Android run support:
- Android SDK / Android Studio
iOS run support (macOS only):
- Xcode 15+
- iOS Simulator
Installation
# Clone repository
git clone https://github.com/AIinfusedS/periodvault.git
cd periodvault
# Quick verification build
./gradlew shared:jvmTest
For full developer bootstrap, hooks, and local CI workflow, see DEVELOPER-GUIDE.md.
Running the App
# Android (emulator - auto-starts if not running)
./scripts/deploy-emulator.sh android
# iOS (simulator - auto-starts if available)
./scripts/deploy-emulator.sh ios
# Both platforms
./scripts/deploy-emulator.sh all
# Physical devices
./scripts/deploy-device.sh android
./scripts/deploy-device.sh ios
Product Roadmap
Current State
Core user-facing functionality is available on both iOS and Android.
Roadmap and planning sources:
- BACKLOG.md for active/incomplete work
- DEVELOPER-GUIDE.md for milestone history and delivery details
Near-term product themes:
- Add alternate/discreet app icon options
- Add local reminder notifications
Completed Work (Since 20th Feb 2026)
| Item | Summary |
|---|---|
| CQ.1 | Critical cross-platform test trust, runtime parity, and audit hardening. 142/142 tests pass on both Android and iOS (CQ.1.1 debloated 18 Android + 3 iOS duplicates, filled 5 iOS gaps, dissolved CombinationComprehensive into logical homes). Anti-pattern enforcement (Thread.sleep, catch(AssertionError), conditional .exists) via validate-test-quality.sh in CI. check-process.sh validates spec artifacts, iteration counter, commit tags, and file-scope allowlist. validate-audit-report.sh upgraded to semantic checks. run-emulator-tests.sh emits structured RUNTIME_EVIDENCE JSON. monitor-pr-checks.sh documented. |
Out of Scope
- User accounts or authentication
- Cloud sync or remote storage
- Social features or sharing
- Fertility tracking for conception (medical device regulation)
- Advertisements or monetization
License
MIT License - See LICENSE for details.
Built with Kotlin Multiplatform, SQLDelight, Jetpack Compose, and SwiftUI.