How mufasaxz/focusforge works
FocusForge is an Android study-focus app: users start and track study sessions, optionally shield distracting apps, and see progress through widgets and shared features. The visible native code hosts Flutter and implements Android shielding, event bridging, timer notifications, and widgets; the README describes broader app features whose Flutter implementation is not present in the supplied tree. A separate Pip AI worker authenticates requests and proxies model calls. Relationships for unsampled app features are documented at a subsystem level; no unsupported implementation detail is inferred.
Main entry points: main Study experience · FocusAccessibilityService.kt Accessibility shield · MainActivity.kt Android host · AppBlockingService.kt App boundary service
Components 30
Study app
- Study experience
android/app/src/main - Android host
android/app/src/main/kotlin/dev/focusforge/focusforge/MainActivity.kt - Data export
android/app/src/main/kotlin/dev/focusforge/focusforge/DataExport.kt - Pip nudges
android/app/src/main/kotlin/dev/focusforge/focusforge/assistant/PipNudges.kt - Device strings
android/app/src/main/kotlin/dev/focusforge/focusforge/localization/DeviceStrings.kt
Distraction shield
- App boundary service
android/app/src/main/kotlin/dev/focusforge/focusforge/shield/AppBlockingService.kt - Blocking policy
android/app/src/main/kotlin/dev/focusforge/focusforge/shield/AppBlockingPolicy.kt - Shield rules
android/app/src/main/kotlin/dev/focusforge/focusforge/shield/ShieldRules.kt - Accessibility shield
android/app/src/main/kotlin/dev/focusforge/focusforge/shield/FocusAccessibilityService.kt - Pause overlay
android/app/src/main/kotlin/dev/focusforge/focusforge/shield/BlockOverlayRoot.kt - Shield bridge
android/app/src/main/kotlin/dev/focusforge/focusforge/shield/ShieldBridge.kt - Shield events
android/app/src/main/kotlin/dev/focusforge/focusforge/shield/ShieldEvents.kt - YouTube policy
android/app/src/main/kotlin/dev/focusforge/focusforge/shield/YouTubeEventPolicy.kt - YouTube signals
android/app/src/main/kotlin/dev/focusforge/focusforge/shield/YouTubeSurfaceSignals.kt - Window visits
android/app/src/main/kotlin/dev/focusforge/focusforge/shield/YouTubeWindowVisit.kt
Progress surfaces
- Timer notification
android/app/src/main/kotlin/dev/focusforge/focusforge/widgets/FocusLiveActivity.kt - Home widgets
android/app/src/main/kotlin/dev/focusforge/focusforge/widgets/FocusWidget.kt - Session summary
android/app/src/main/kotlin/dev/focusforge/focusforge/widgets/WidgetSessionSummary.kt - Retro renderer
android/app/src/main/kotlin/dev/focusforge/focusforge/widgets/RetroWidgetRenderer.kt - Weekly renderer
android/app/src/main/kotlin/dev/focusforge/focusforge/widgets/WeeklyWidgetRenderer.kt - Goal plan
android/app/src/main/kotlin/dev/focusforge/focusforge/widgets/WidgetGoalPlan.kt
Cloud services
- Pip AI worker
pip-ai-backend/src/index.js - Token verification
pip-ai-backend/src/auth.js - Prompt handling
pip-ai-backend/src/pip.js - Privacy filtering
pip-ai-backend/src/privacy.js - Reset delivery
pip-ai-backend/src/reset-delivery.js - Account cleanup
functions/cleanup.js
Other components
- Learner
- AI providers
- Firebase services
Connections 32
- Learner → Study experience: uses
- Study experience → Android host: invokes platform
android/app/src/main/kotlin/dev/focusforge/focusforge/shield/FocusAccessibilityService.kt - Android host → Shield bridge: attaches
android/app/src/main/kotlin/dev/focusforge/focusforge/MainActivity.kt - Android host → Data export: handles export
android/app/src/main/kotlin/dev/focusforge/focusforge/MainActivity.kt - Study experience → App boundary service: configures shielding
android/app/src/main/kotlin/dev/focusforge/focusforge/shield/FocusAccessibilityService.kt - App boundary service → Blocking policy: evaluates budgets
android/app/src/main/kotlin/dev/focusforge/focusforge/shield/AppBlockingService.kt - App boundary service → Shield rules: reads rules
android/app/src/main/kotlin/dev/focusforge/focusforge/shield/AppBlockingService.kt - App boundary service → Accessibility shield: checks protected apps
android/app/src/main/kotlin/dev/focusforge/focusforge/shield/AppBlockingService.kt - App boundary service → Pause overlay: shows pause surface
android/app/src/main/kotlin/dev/focusforge/focusforge/shield/AppBlockingService.kt - Accessibility shield → Shield rules: loads rules
android/app/src/main/kotlin/dev/focusforge/focusforge/shield/FocusAccessibilityService.kt - Accessibility shield → Window visits: tracks visits
android/app/src/main/kotlin/dev/focusforge/focusforge/shield/FocusAccessibilityService.kt - Accessibility shield → YouTube policy: applies policy
android/app/src/main/kotlin/dev/focusforge/focusforge/shield/FocusAccessibilityService.kt - Accessibility shield → YouTube signals: reads signals
android/app/src/main/kotlin/dev/focusforge/focusforge/shield/FocusAccessibilityService.kt - Accessibility shield → Shield events: emits events
android/app/src/main/kotlin/dev/focusforge/focusforge/shield/FocusAccessibilityService.kt - Shield bridge → Shield events: drains queue
android/app/src/main/kotlin/dev/focusforge/focusforge/shield/ShieldBridge.kt - Study experience → Timer notification: starts countdown
android/app/src/main/kotlin/dev/focusforge/focusforge/MainActivity.kt - Android host → Timer notification: connects timer UI
android/app/src/main/kotlin/dev/focusforge/focusforge/MainActivity.kt - Android host → Home widgets: connects widgets
android/app/src/main/kotlin/dev/focusforge/focusforge/MainActivity.kt - Home widgets → Session summary: summarizes sessions
android/app/src/main/kotlin/dev/focusforge/focusforge/widgets/FocusWidget.kt - Home widgets → Retro renderer: renders retro
android/app/src/main/kotlin/dev/focusforge/focusforge/widgets/FocusWidget.kt - Home widgets → Weekly renderer: renders weekly
android/app/src/main/kotlin/dev/focusforge/focusforge/widgets/FocusWidget.kt - Home widgets → Goal plan: reads goal plan
android/app/src/main/kotlin/dev/focusforge/focusforge/widgets/FocusWidget.kt - Study experience → Pip nudges: presents study buddy
android/app/src/main/kotlin/dev/focusforge/focusforge/MainActivity.kt - Learner → Pip AI worker: asks Pip
- Pip AI worker → Token verification: verifies token
pip-ai-backend/src/index.js - Pip AI worker → Prompt handling: parses prompt
pip-ai-backend/src/index.js - Prompt handling → Privacy filtering: filters content
pip-ai-backend/src/pip.js - Pip AI worker → Reset delivery: uses reset delivery
pip-ai-backend/src/index.js - Pip AI worker → AI providers: requests completion
pip-ai-backend/src/index.js - Learner → Account cleanup: requests deletion
- Account cleanup → Firebase services: cleans cloud records
- Study experience → Firebase services: backs up profile