How anildhiman88/kinpulse works
1. Project shape
- KinPulse Phase 1 is primarily an Android Kotlin app with a small TypeScript Firebase Functions backend for optional server-side alerts.
- The Android app uses Jetpack Compose, WorkManager, Firebase/FCM, and a single app-level ViewModel. The repo also contains a demo/local persistence path so the app can run without Firebase config.
2. Top-level runtime boundary
- KinPulseApplication and AppContainer set up the app-wide dependencies.
- MainActivity hosts the Compose UI, while ui/navigation/KinPulseApp.kt drives screen flow.
- Dependency wiring is intentionally manual rather than Hilt-based, so architecture is straightforward and centralized.
3. Domain/data model boundary
- data/model/Models.kt holds the Firestore-compatible records used across the app.
- The readme indicates the key entities are things like users, companion profiles, invite codes, family connections, heartbeats, heartbeat signals, and notification logs.
- These models are the shared contract between UI, repository, background work, and Firebase.
4. Repository layer as the main data boundary
- data/repository/KinPulseRepository.kt is the abstraction used by the rest of the app.
- FirebaseKinPulseRepository is the cloud-backed implementation; DemoKinPulseRepository is the founder-demo/local fallback.
- LocalSignalStore supports local persistence for signal capture and continuity.
- This repository boundary is the main switch that determines whether the app is running against Firebase or in demo mode.
5. State management and UI flow
- viewmodel/MainViewModel.kt is the app-level state holder.
- It exposes StateFlow-based UI state and user actions to the Compose screens.
- The UI layer is split into ui/screens for feature screens, ui/components for shared widgets, and ui/theme for styling.
- The architecture is “screen driven”: the UI reads state from the ViewModel and sends events back to it, rather than talking directly to Firebase.
6. Heartbeat engine: core business logic
- The heartbeat package is the product’s main business subsystem.
- HeartbeatEngine, HeartbeatScoringService, HeartbeatTrustStateEngine, HeartbeatNotificationPolicy, HeartbeatAccessPolicy, SignalCapturePolicy, and HeartbeatExplanationService together implement the daily heartbeat rules.
- This layer converts privacy-safe signals into calm states such as received, waiting, delayed, manual check-in, and sharing paused.
- It also enforces confidence scoring, duplicate caps, time-window logic, and user-facing explanations.
7. Signal ingestion and local event sources
- The app captures only safe operational signals, not private content.
- services/BootCompletedReceiver.kt, ChargingEventReceiver.kt, and DevicePresenceReceiver.kt are Android broadcast/service entry points that feed the heartbeat logic.
- workers/HeartbeatWorker.kt provides periodic background refresh and delayed checks when the app is backgrounded.
- These inputs are best-effort because Android power policies may delay them; the app is designed around that constraint.
8. Notification subsystem
- notifications/KinPulseNotificationChannels.kt defines notification channels.
- notifications/KinPulseMessagingService.kt handles FCM messages when cloud push is available.
- notifications/NotificationRepository.kt stores notification-related state/logging.
- Notifications are emitted from both local Android logic and optional cloud events, with the product favoring local calm-state rendering and best-effort delivery in Spark mode.
9. Firebase and cloud backend
- The Android app uses Firestore and Firebase Auth for sign-in and shared family data.
- firestore.rules and firestore.indexes.json define the backend access boundary and query support.
- The functions/src/index.ts TypeScript backend is optional but supports later-stage server notifications and scheduled delayed-heartbeat checks.
- The README makes clear that cloud functions are not required for the MVP to run, but they improve notification reliability and delayed alert handling.
10. Data flow from signal to family view
- A signal arrives from the app, boot, charging, or periodic worker.
- The signal is stored locally and/or written through the repository.
- Heartbeat logic recalculates the daily state and confidence, then persists the heartbeat document.
- The family-facing UI reads the updated repository state and shows the calm status, daily timestamps, and seven-day summary.
11. Sharing and access control
- Sharing on/off is enforced at multiple levels: UI, repository writes, notifications, and Firestore rules.
- Family access is mediated by invite codes and connected-family records.
- Revocation is non-destructive but immediately removes future access for the revoked family member.
- This is a key architectural boundary: the app is privacy-first and treats access as a controlled relationship, not an open feed.
12. Time and presentation rules
- utils/TimeUtils.kt plus the heartbeat services handle local-day and timezone-sensitive behavior.
- The app uses the Companion’s timezone for daily heartbeat boundaries and late-day “appears settled around …” presentation.
- This matters because the architecture is not just storing timestamps; it is interpreting them relative to each companion’s local day and wake/sensitivity windows.
13. Testing and verification
- The repo includes focused unit tests for the heartbeat services, time utilities, and user profile capability logic.
- The docs/TESTING_CHECKLIST.md and README manual QA steps reflect the main architectural risks: access control, duplicate alerts, delayed alerts, and state transitions.
- This suggests the critical correctness surface is in the domain logic, not in UI rendering.
14. Architecture summary for a diagram
- The cleanest diagram would show: Android UI/Compose → MainViewModel → Repository → Firebase/Demo storage, with heartbeat engine as the central domain processor.
- Side inputs come from receivers/workers into the heartbeat engine, and side outputs go to local notifications / FCM / cloud functions.
- The main boundaries are UI state, repository abstraction, heartbeat rules, and Firebase/cloud integration.
Main entry points: HeartbeatEngine.kt Heartbeat engine · AppContainer.kt App container · MainViewModel.kt Main view model · KinPulseRepository.kt Repo API
Components 21
Android app
Primary Kotlin app runtime and UI layers.
- KinPulse app · Android application entry and dependency root.
app/src/main/java/com/kinpulse/app/KinPulseApplication.kt - App container · Central dependency wiring and runtime selection.
app/src/main/java/com/kinpulse/app/AppContainer.kt - Main activity · Hosts the Compose UI tree.
app/src/main/java/com/kinpulse/app/MainActivity.kt - App nav · Drives screen flow through the app.
app/src/main/java/com/kinpulse/app/ui/navigation/KinPulseApp.kt - Main view model · Single app-level state and action surface for screens.
app/src/main/java/com/kinpulse/app/viewmodel/MainViewModel.kt - Screens · Dashboard, onboarding, setup, settings, and preview flows.
app/src/main/java/com/kinpulse/app/ui/screens - Shared UI · Reusable UI components and theme styling.
app/src/main/java/com/kinpulse/app/ui/components/CommonComponents.kt
Domain
Heartbeat rules and shared data contracts.
- Models · Firestore-compatible entities shared across the app.
app/src/main/java/com/kinpulse/app/data/model/Models.kt - Repo API · Primary data boundary used by UI and heartbeat logic.
app/src/main/java/com/kinpulse/app/data/repository/KinPulseRepository.kt - Demo repo · Founder-demo and offline-friendly repository implementation.
app/src/main/java/com/kinpulse/app/data/repository/DemoKinPulseRepository.kt - Heartbeat engine · Coordinates state calculation, confidence, and calm statuses.
app/src/main/java/com/kinpulse/app/heartbeat/HeartbeatEngine.kt - Scoring · Computes confidence from safe operational signals.
app/src/main/java/com/kinpulse/app/heartbeat/HeartbeatScoringService.kt - Trust state · Derives waiting, delayed, received, and paused states.
app/src/main/java/com/kinpulse/app/heartbeat/HeartbeatTrustStateEngine.kt - Policies · Access, notification, capture, and explanation rules.
app/src/main/java/com/kinpulse/app/heartbeat/HeartbeatAccessPolicy.kt
Infrastructure
Firebase, persistence, background entry points, and notifications.
- Local signals · Stores signal capture data for continuity.
app/src/main/java/com/kinpulse/app/data/repository/LocalSignalStore.kt - Signal sources · Boot, charging, and device-presence entry points.
app/src/main/java/com/kinpulse/app/services - Heartbeat worker · Periodic refresh and delayed checks when backgrounded.
app/src/main/java/com/kinpulse/app/workers/HeartbeatWorker.kt - Notifications · Channels, local logging, and FCM message handling.
app/src/main/java/com/kinpulse/app/notifications
Cloud
Optional TypeScript backend and Firebase access boundaries.
- Firebase repo · Firestore/Auth-backed implementation.
app/src/main/java/com/kinpulse/app/data/repository/FirebaseKinPulseRepository.kt - Cloud functions · Optional scheduled checks and server-side alert support.
functions/src/index.ts - Firestore rules · Access control and query support for shared family data.
firestore.rules
Connections 26
- KinPulse app → App container: creates · Application initializes shared dependencies.
- App container → Repo API: provides · Selects cloud or demo data path.
- App container → Heartbeat engine: provides · Wires domain services into the app.
- App container → Notifications: provides · Supplies notification infrastructure.
- Main activity → App nav: hosts · Activity sets up the Compose tree.
- App nav → Main view model: reads state · Navigation reacts to app state.
- Main view model → Repo API: uses · ViewModel loads and mutates shared records.
- Main view model → Heartbeat engine: dispatches · User actions flow into heartbeat updates.
- Main view model → Screens: drives · Screens render from ViewModel state.
- Screens → Shared UI: composes · Screens reuse common widgets and theme.
- Heartbeat engine → Scoring: calls · Calculates confidence from captured signals.
- Heartbeat engine → Trust state: calls · Derives calm-state transitions.
- Heartbeat engine → Policies: applies · Enforces access, capture, and notification rules.
- Heartbeat engine → Models: reads/writes · Uses shared entities for state persistence.
- Signal sources → Heartbeat worker: triggers · Android entry points and periodic work feed the engine.
- Signal sources → Heartbeat engine: feeds · Operational signals enter the rules engine.
- Heartbeat worker → Heartbeat engine: refreshes · Runs delayed and periodic recalculation.
- Heartbeat engine → Local signals: stores · Persists safe local continuity data.
- Repo API → Firebase repo: implements · Cloud-backed repository variant.
- Repo API → Demo repo: implements · Offline/demo repository variant.
- Demo repo → Local signals: uses · Keeps demo and local signal data available.
- Firebase repo → Models: uses · Maps shared models to Firestore.
- Firebase repo → Firestore rules: constrained by · Reads and writes under backend rules.
- Notifications → Heartbeat engine: reflects · Local notifications present heartbeat state.
- Notifications → Cloud functions: receives · FCM and server-side alert support.
- Cloud functions → Firestore rules: accesses · Backend operations remain within Firestore policy.