Client-Side Overview

Interactive map of the apps/native/ codebase — click any module to dive into its documentation.

Client-Side Overview

This is your interactive launchpad for the entire apps/native/ codebase. Every box below links to its deep-dive documentation page. Click to explore.

---

The Monorepo at a Glance

apps/
├── native/             ← You are here (React Native + Expo)
├── web/                ← Tauri desktop dashboard
├── extension/          ← Browser distraction blocker (WXT)
└── BugReport/          ← Issue tracking templates

Everything below documents the native client — the core Android application.

---

app/ — Screens and Routing

File-based routing powered by Expo Router. Each folder maps to a route group with its own layout and navigation stack.

Root Layout & Provider Tree

The entry point — 9-layer provider nesting, console hijack, and invisible system components.

Authentication Flow

Sign-in, OAuth, welcome screen, and session-based routing guards.

Dashboard & Main Tabs

Bottom tab navigator: Commits, Schedules, Presets, Alerts, Profile.

Commitment Wizard

Hub-and-Spoke architecture for building commitments with spoke screens.

Time & Location Setup

Day picker, time windows, Google Maps geofencing, per-slot attachments.

App Blocker Screen

Three-tab interface: Apps (native bridge), Websites (manual), Search.

Calendar & Schedules

CalendarKit grid with drag-and-drop event management.

Penalties Flow

Photo, email, money, and direct-commit penalty sub-screens.

Waivers Flow

CAPTCHA and paragraph transcription redemption challenges.

Settings & Permissions

8-point hardware permission audit with deep-link to Android Settings.

Strict Mode

Immutability lock activation — edits and deletes rejected until expiry.

Preset Editing

Location, blocklist, and rule preset CRUD with isolated state.

Verification Flow

Active verification: GPS polling, photo capture, checkpoint checks.

---

lib/ — Core Infrastructure

The engine room. These modules handle data persistence, synchronization, and hardware coordination.

Triple-Write Orchestrator

Saga-pattern engine: Convex → SQLite → AlarmManager with automatic rollback.

Sync Engine

Delta payload ingestion with Freshness Guard and corruption recovery.

Sync Lock Mutex

Singleton Promise-chain mutex serializing all database writes.

Local Database Schema

V12 Instance-Dependent SQLite schema and Nuke & Pave migration strategy.

Local DB Commits

Task-level CRUD with Unified Identity strategy and prepared statement batching.

Local DB Instances

Instance lifecycle management with orphan survival and atomic clobber-and-spawn.

Logger

Console hijack with persistent daily log files and auto-tracing.

Scheduler Bridge

JS-side interface to the Kotlin AlarmManager native module.

Auth Client

Better Auth client configuration and session management.

Time Utilities

Date formatting, epoch conversion, and timezone-safe helpers.

Validation

Runtime validation for task drafts and time slot configurations.

---

modules/ — Native Kotlin Bridges (JSI)

Kotlin native modules that bypass the React Native bridge for direct hardware access via JSI.

Scheduler Module

AlarmManager + WakeLock orchestration. BootReceiver re-hydrates state on device restart.

App Lister Module

High-speed JSI extraction of all installed packages via Android PackageManager.

Blocker Module

Accessibility-based anti-circumvention engine for app and website blocking.

Enforcement Module

Permission deep-links and Device Admin management for enforcement settings.

Recovery Module

Nuclear reset and self-healing connection recovery (process restart).

Logcat Module

Native in-memory buffer bridging Android logcat output to the JS Logger.

---

stores/ — Zustand State Machines

Client-side state managed by Zustand stores with logger middleware.

Task Draft Store

The 800+ line, 26KB store powering the entire commitment wizard state machine.

Calendar Store

Calendar grid state, view modes, date selection, and event interaction tracking.

Preset Store

Read-only store of hydrated location, blocklist, and rule presets from Convex.

Commit Store

Dashboard list selection, context menu, and deletion state.

Verification Store

Real-time GPS, geofence match, camera, and CAPTCHA verification state.

Heal Store

Dual-mode recovery: healing spinner and crash confirmation with nuclear reset.

Preset Edit Store

Isolated editing state for preset CRUD without affecting the wizard.

App Store

Global foreground/background state for HydrationSync triggers.

Task Store

Read-only SQLite task cache for the Dashboard commits list.

Chaos Store

Dev-only store for injecting failures and testing system resilience.

---

hooks/ — React Hooks

Custom hooks that orchestrate data flow between stores, Convex, SQLite, and native modules.

useHydrationSync

Background sync engine: boot sync, foreground re-sync, zombie detection, and Smart Blame Logic.

usePresetHydration

One-shot hook at wizard layout mount to pre-load all presets from Convex.

useCommitTask

Master orchestrator that fires the Triple-Write when the user commits (~450 lines).

useTaskActions

CRUD actions: delete, edit, move, and strict-mode lock via Triple-Write.

useTasks

Convex reactive query for tasks with Zustand store synchronization.

useVerificationEngine

Drives active verification: GPS polling, photo capture, status transitions.

useUpcomingVerification

Server-authoritative subscription to the next pending event (zero-horizon).

useLocation

GPS tracking with three-branch permission handling (granted, askable, blocked).

usePermissions

8-point Android permission audit and deep-link triggers.

useCalendarEvents

Transforms instances into CalendarKit event blocks with status-based coloring.

useCalendarRange

Computes visible date range for the calendar grid query scope.

useEventDetail

Data layer for EventDetailModal: instance parsing, verification status, and actions.

usePenaltySync

Bidirectional sync between penalty sub-screens and the draft store.

useWaiverSync

Bidirectional sync between waiver sub-screens and the draft store.

useTaskSelection

Multi-select state for bulk task operations on the Dashboard.

useAppDiscovery

JSI-powered installed app enumeration from AppListerModule.

useAccountabilityPrefill

Auto-populates penalty and waiver fields from saved accountability presets.

useFreshPhotoUrl

Time-limited signed URL generation for penalty photo uploads to Convex Storage.

---

components/ — UI Components

HydrationEngine

Invisible root component that runs useHydrationSync for background data sync.

SecurityShield

Root/jailbreak detection gate that unmounts the entire app tree on compromised devices.

HealOverlay

Full-screen recovery modal: healing spinner during sync, crash confirmation on failure.

UI Components

Reusable primitives: buttons, inputs, modals, sliders, skeletons, and layout containers.

Developer Tools

ChaosFab and DbDebugFab — floating debug buttons for resilience testing.

ConnectionWatchdog

DEPRECATED — Legacy zombie detector. Replaced by HydrationSync.

---

providers/ and contexts/ — React Providers

ResurrectionProvider

Catastrophic failure recovery — increments iteration counter for full client rebirth.

ConvexClientWrapper

Manages Convex client lifecycle with graceful teardown on resurrection.

App Theme Context

Uniwind dark-mode theming with the Hardened Saffron design token system.

Tab Context

Tab navigation state, visit tracking, state persistence, and preload optimization.

---

plugins/ — Expo Config Plugins

Expo config plugins that patch the AndroidManifest.xml at build time via AST transforms:

• withAlarmPermissions — Injects SCHEDULE_EXACT_ALARM and USE_EXACT_ALARM permissions into the manifest, required for hardware alarm scheduling on Android 12+.

---

Quick Reference: File to Documentation Map

For the full directory tree with line-by-line annotations, see the Folder Structure page.