# mufasaxz/focusforge architecture

> Architecture diagram of the GitHub repository mufasaxz/focusforge, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mufasaxz/focusforge
- Repository: https://github.com/mufasaxz/focusforge

## Overview

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: [`android/app/src/main`](https://github.com/mufasaxz/focusforge/tree/main/android/app/src/main) (Study experience), [`android/app/src/main/kotlin/dev/focusforge/focusforge/shield/FocusAccessibilityService.kt`](https://github.com/mufasaxz/focusforge/blob/main/android/app/src/main/kotlin/dev/focusforge/focusforge/shield/FocusAccessibilityService.kt) (Accessibility shield), [`android/app/src/main/kotlin/dev/focusforge/focusforge/MainActivity.kt`](https://github.com/mufasaxz/focusforge/blob/main/android/app/src/main/kotlin/dev/focusforge/focusforge/MainActivity.kt) (Android host), [`android/app/src/main/kotlin/dev/focusforge/focusforge/shield/AppBlockingService.kt`](https://github.com/mufasaxz/focusforge/blob/main/android/app/src/main/kotlin/dev/focusforge/focusforge/shield/AppBlockingService.kt) (App boundary service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Study app"]
  node_flutter["Study experience"]
  node_native["Android host<br/>[MainActivity.kt]"]
  node_export["Data export<br/>[DataExport.kt]"]
  node_pipnudges["Pip nudges<br/>[PipNudges.kt]"]
  node_localization["Device strings<br/>[DeviceStrings.kt]"]
end

subgraph group_shield["Distraction shield"]
  node_service["App boundary service"]
  node_policy["Blocking policy"]
  node_rules["Shield rules<br/>[ShieldRules.kt]"]
  node_accessibility["Accessibility shield"]
  node_overlay["Pause overlay"]
  node_bridge["Shield bridge<br/>[ShieldBridge.kt]"]
  node_events["Shield events<br/>[ShieldEvents.kt]"]
  node_ytpolicy["YouTube policy"]
  node_ytsignals["YouTube signals"]
  node_ytvisit["Window visits"]
end

subgraph group_widgets["Progress surfaces"]
  node_live["Timer notification"]
  node_widget["Home widgets<br/>[FocusWidget.kt]"]
  node_summary["Session summary"]
  node_retro["Retro renderer"]
  node_weekly["Weekly renderer"]
  node_goalplan["Goal plan<br/>[WidgetGoalPlan.kt]"]
end

subgraph group_services["Cloud services"]
  node_aiworker["Pip AI worker<br/>[index.js]"]
  node_auth["Token verification<br/>[auth.js]"]
  node_pip["Prompt handling<br/>[pip.js]"]
  node_privacy["Privacy filtering<br/>[privacy.js]"]
  node_reset["Reset delivery<br/>[reset-delivery.js]"]
  node_account["Account cleanup<br/>[cleanup.js]"]
end

node_user(("Learner"))
node_model{{"AI providers"}}
node_cloud{{"Firebase services"}}

node_user -->|"uses"| node_flutter
node_flutter -.->|"invokes platform"| node_native
node_native -->|"attaches"| node_bridge
node_native -->|"handles export"| node_export
node_flutter -.->|"configures shielding"| node_service
node_service -->|"evaluates budgets"| node_policy
node_service -->|"reads rules"| node_rules
node_service -->|"checks protected apps"| node_accessibility
node_service -->|"shows pause surface"| node_overlay
node_accessibility -->|"loads rules"| node_rules
node_accessibility -->|"tracks visits"| node_ytvisit
node_accessibility -->|"applies policy"| node_ytpolicy
node_accessibility -->|"reads signals"| node_ytsignals
node_accessibility -->|"emits events"| node_events
node_bridge -->|"drains queue"| node_events
node_flutter -.->|"starts countdown"| node_live
node_native -->|"connects timer UI"| node_live
node_native -->|"connects widgets"| node_widget
node_widget -->|"summarizes sessions"| node_summary
node_widget -->|"renders retro"| node_retro
node_widget -->|"renders weekly"| node_weekly
node_widget -->|"reads goal plan"| node_goalplan
node_flutter -.->|"presents study buddy"| node_pipnudges
node_user -.->|"asks Pip"| node_aiworker
node_aiworker -->|"verifies token"| node_auth
node_aiworker -->|"parses prompt"| node_pip
node_pip -->|"filters content"| node_privacy
node_aiworker -->|"uses reset delivery"| node_reset
node_aiworker -->|"requests completion"| node_model
node_user -->|"requests deletion"| node_account
node_account -->|"cleans cloud records"| node_cloud
node_flutter -.->|"backs up profile"| node_cloud

click node_flutter "https://github.com/mufasaxz/focusforge/tree/main/android/app/src/main"
click node_native "https://github.com/mufasaxz/focusforge/blob/main/android/app/src/main/kotlin/dev/focusforge/focusforge/MainActivity.kt"
click node_export "https://github.com/mufasaxz/focusforge/blob/main/android/app/src/main/kotlin/dev/focusforge/focusforge/DataExport.kt"
click node_pipnudges "https://github.com/mufasaxz/focusforge/blob/main/android/app/src/main/kotlin/dev/focusforge/focusforge/assistant/PipNudges.kt"
click node_localization "https://github.com/mufasaxz/focusforge/blob/main/android/app/src/main/kotlin/dev/focusforge/focusforge/localization/DeviceStrings.kt"
click node_service "https://github.com/mufasaxz/focusforge/blob/main/android/app/src/main/kotlin/dev/focusforge/focusforge/shield/AppBlockingService.kt"
click node_policy "https://github.com/mufasaxz/focusforge/blob/main/android/app/src/main/kotlin/dev/focusforge/focusforge/shield/AppBlockingPolicy.kt"
click node_rules "https://github.com/mufasaxz/focusforge/blob/main/android/app/src/main/kotlin/dev/focusforge/focusforge/shield/ShieldRules.kt"
click node_accessibility "https://github.com/mufasaxz/focusforge/blob/main/android/app/src/main/kotlin/dev/focusforge/focusforge/shield/FocusAccessibilityService.kt"
click node_overlay "https://github.com/mufasaxz/focusforge/blob/main/android/app/src/main/kotlin/dev/focusforge/focusforge/shield/BlockOverlayRoot.kt"
click node_bridge "https://github.com/mufasaxz/focusforge/blob/main/android/app/src/main/kotlin/dev/focusforge/focusforge/shield/ShieldBridge.kt"
click node_events "https://github.com/mufasaxz/focusforge/blob/main/android/app/src/main/kotlin/dev/focusforge/focusforge/shield/ShieldEvents.kt"
click node_ytpolicy "https://github.com/mufasaxz/focusforge/blob/main/android/app/src/main/kotlin/dev/focusforge/focusforge/shield/YouTubeEventPolicy.kt"
click node_ytsignals "https://github.com/mufasaxz/focusforge/blob/main/android/app/src/main/kotlin/dev/focusforge/focusforge/shield/YouTubeSurfaceSignals.kt"
click node_ytvisit "https://github.com/mufasaxz/focusforge/blob/main/android/app/src/main/kotlin/dev/focusforge/focusforge/shield/YouTubeWindowVisit.kt"
click node_live "https://github.com/mufasaxz/focusforge/blob/main/android/app/src/main/kotlin/dev/focusforge/focusforge/widgets/FocusLiveActivity.kt"
click node_widget "https://github.com/mufasaxz/focusforge/blob/main/android/app/src/main/kotlin/dev/focusforge/focusforge/widgets/FocusWidget.kt"
click node_summary "https://github.com/mufasaxz/focusforge/blob/main/android/app/src/main/kotlin/dev/focusforge/focusforge/widgets/WidgetSessionSummary.kt"
click node_retro "https://github.com/mufasaxz/focusforge/blob/main/android/app/src/main/kotlin/dev/focusforge/focusforge/widgets/RetroWidgetRenderer.kt"
click node_weekly "https://github.com/mufasaxz/focusforge/blob/main/android/app/src/main/kotlin/dev/focusforge/focusforge/widgets/WeeklyWidgetRenderer.kt"
click node_goalplan "https://github.com/mufasaxz/focusforge/blob/main/android/app/src/main/kotlin/dev/focusforge/focusforge/widgets/WidgetGoalPlan.kt"
click node_aiworker "https://github.com/mufasaxz/focusforge/blob/main/pip-ai-backend/src/index.js"
click node_auth "https://github.com/mufasaxz/focusforge/blob/main/pip-ai-backend/src/auth.js"
click node_pip "https://github.com/mufasaxz/focusforge/blob/main/pip-ai-backend/src/pip.js"
click node_privacy "https://github.com/mufasaxz/focusforge/blob/main/pip-ai-backend/src/privacy.js"
click node_reset "https://github.com/mufasaxz/focusforge/blob/main/pip-ai-backend/src/reset-delivery.js"
click node_account "https://github.com/mufasaxz/focusforge/blob/main/functions/cleanup.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_flutter,node_native,node_export,node_pipnudges,node_localization toneBlue
class node_service,node_policy,node_rules,node_accessibility,node_overlay,node_bridge,node_events,node_ytpolicy,node_ytsignals,node_ytvisit toneAmber
class node_live,node_widget,node_summary,node_retro,node_weekly,node_goalplan toneMint
class node_aiworker,node_auth,node_pip,node_privacy,node_reset,node_account toneRose
class node_user,node_model,node_cloud toneIndigo
```

## Components

### Study app

- [Study experience](https://github.com/mufasaxz/focusforge/tree/main/android/app/src/main): `android/app/src/main`
- [Android host](https://github.com/mufasaxz/focusforge/blob/main/android/app/src/main/kotlin/dev/focusforge/focusforge/MainActivity.kt): `android/app/src/main/kotlin/dev/focusforge/focusforge/MainActivity.kt`
- [Data export](https://github.com/mufasaxz/focusforge/blob/main/android/app/src/main/kotlin/dev/focusforge/focusforge/DataExport.kt): `android/app/src/main/kotlin/dev/focusforge/focusforge/DataExport.kt`
- [Pip nudges](https://github.com/mufasaxz/focusforge/blob/main/android/app/src/main/kotlin/dev/focusforge/focusforge/assistant/PipNudges.kt): `android/app/src/main/kotlin/dev/focusforge/focusforge/assistant/PipNudges.kt`
- [Device strings](https://github.com/mufasaxz/focusforge/blob/main/android/app/src/main/kotlin/dev/focusforge/focusforge/localization/DeviceStrings.kt): `android/app/src/main/kotlin/dev/focusforge/focusforge/localization/DeviceStrings.kt`

### Distraction shield

- [App boundary service](https://github.com/mufasaxz/focusforge/blob/main/android/app/src/main/kotlin/dev/focusforge/focusforge/shield/AppBlockingService.kt): `android/app/src/main/kotlin/dev/focusforge/focusforge/shield/AppBlockingService.kt`
- [Blocking policy](https://github.com/mufasaxz/focusforge/blob/main/android/app/src/main/kotlin/dev/focusforge/focusforge/shield/AppBlockingPolicy.kt): `android/app/src/main/kotlin/dev/focusforge/focusforge/shield/AppBlockingPolicy.kt`
- [Shield rules](https://github.com/mufasaxz/focusforge/blob/main/android/app/src/main/kotlin/dev/focusforge/focusforge/shield/ShieldRules.kt): `android/app/src/main/kotlin/dev/focusforge/focusforge/shield/ShieldRules.kt`
- [Accessibility shield](https://github.com/mufasaxz/focusforge/blob/main/android/app/src/main/kotlin/dev/focusforge/focusforge/shield/FocusAccessibilityService.kt): `android/app/src/main/kotlin/dev/focusforge/focusforge/shield/FocusAccessibilityService.kt`
- [Pause overlay](https://github.com/mufasaxz/focusforge/blob/main/android/app/src/main/kotlin/dev/focusforge/focusforge/shield/BlockOverlayRoot.kt): `android/app/src/main/kotlin/dev/focusforge/focusforge/shield/BlockOverlayRoot.kt`
- [Shield bridge](https://github.com/mufasaxz/focusforge/blob/main/android/app/src/main/kotlin/dev/focusforge/focusforge/shield/ShieldBridge.kt): `android/app/src/main/kotlin/dev/focusforge/focusforge/shield/ShieldBridge.kt`
- [Shield events](https://github.com/mufasaxz/focusforge/blob/main/android/app/src/main/kotlin/dev/focusforge/focusforge/shield/ShieldEvents.kt): `android/app/src/main/kotlin/dev/focusforge/focusforge/shield/ShieldEvents.kt`
- [YouTube policy](https://github.com/mufasaxz/focusforge/blob/main/android/app/src/main/kotlin/dev/focusforge/focusforge/shield/YouTubeEventPolicy.kt): `android/app/src/main/kotlin/dev/focusforge/focusforge/shield/YouTubeEventPolicy.kt`
- [YouTube signals](https://github.com/mufasaxz/focusforge/blob/main/android/app/src/main/kotlin/dev/focusforge/focusforge/shield/YouTubeSurfaceSignals.kt): `android/app/src/main/kotlin/dev/focusforge/focusforge/shield/YouTubeSurfaceSignals.kt`
- [Window visits](https://github.com/mufasaxz/focusforge/blob/main/android/app/src/main/kotlin/dev/focusforge/focusforge/shield/YouTubeWindowVisit.kt): `android/app/src/main/kotlin/dev/focusforge/focusforge/shield/YouTubeWindowVisit.kt`

### Progress surfaces

- [Timer notification](https://github.com/mufasaxz/focusforge/blob/main/android/app/src/main/kotlin/dev/focusforge/focusforge/widgets/FocusLiveActivity.kt): `android/app/src/main/kotlin/dev/focusforge/focusforge/widgets/FocusLiveActivity.kt`
- [Home widgets](https://github.com/mufasaxz/focusforge/blob/main/android/app/src/main/kotlin/dev/focusforge/focusforge/widgets/FocusWidget.kt): `android/app/src/main/kotlin/dev/focusforge/focusforge/widgets/FocusWidget.kt`
- [Session summary](https://github.com/mufasaxz/focusforge/blob/main/android/app/src/main/kotlin/dev/focusforge/focusforge/widgets/WidgetSessionSummary.kt): `android/app/src/main/kotlin/dev/focusforge/focusforge/widgets/WidgetSessionSummary.kt`
- [Retro renderer](https://github.com/mufasaxz/focusforge/blob/main/android/app/src/main/kotlin/dev/focusforge/focusforge/widgets/RetroWidgetRenderer.kt): `android/app/src/main/kotlin/dev/focusforge/focusforge/widgets/RetroWidgetRenderer.kt`
- [Weekly renderer](https://github.com/mufasaxz/focusforge/blob/main/android/app/src/main/kotlin/dev/focusforge/focusforge/widgets/WeeklyWidgetRenderer.kt): `android/app/src/main/kotlin/dev/focusforge/focusforge/widgets/WeeklyWidgetRenderer.kt`
- [Goal plan](https://github.com/mufasaxz/focusforge/blob/main/android/app/src/main/kotlin/dev/focusforge/focusforge/widgets/WidgetGoalPlan.kt): `android/app/src/main/kotlin/dev/focusforge/focusforge/widgets/WidgetGoalPlan.kt`

### Cloud services

- [Pip AI worker](https://github.com/mufasaxz/focusforge/blob/main/pip-ai-backend/src/index.js): `pip-ai-backend/src/index.js`
- [Token verification](https://github.com/mufasaxz/focusforge/blob/main/pip-ai-backend/src/auth.js): `pip-ai-backend/src/auth.js`
- [Prompt handling](https://github.com/mufasaxz/focusforge/blob/main/pip-ai-backend/src/pip.js): `pip-ai-backend/src/pip.js`
- [Privacy filtering](https://github.com/mufasaxz/focusforge/blob/main/pip-ai-backend/src/privacy.js): `pip-ai-backend/src/privacy.js`
- [Reset delivery](https://github.com/mufasaxz/focusforge/blob/main/pip-ai-backend/src/reset-delivery.js): `pip-ai-backend/src/reset-delivery.js`
- [Account cleanup](https://github.com/mufasaxz/focusforge/blob/main/functions/cleanup.js): `functions/cleanup.js`

### Other components

- **Learner**
- **AI providers**
- **Firebase services**

## Connections

- Learner → Study experience: uses
- Study experience → Android host: invokes platform (evidence: `android/app/src/main/kotlin/dev/focusforge/focusforge/shield/FocusAccessibilityService.kt`)
- Android host → Shield bridge: attaches (evidence: `android/app/src/main/kotlin/dev/focusforge/focusforge/MainActivity.kt`)
- Android host → Data export: handles export (evidence: `android/app/src/main/kotlin/dev/focusforge/focusforge/MainActivity.kt`)
- Study experience → App boundary service: configures shielding (evidence: `android/app/src/main/kotlin/dev/focusforge/focusforge/shield/FocusAccessibilityService.kt`)
- App boundary service → Blocking policy: evaluates budgets (evidence: `android/app/src/main/kotlin/dev/focusforge/focusforge/shield/AppBlockingService.kt`)
- App boundary service → Shield rules: reads rules (evidence: `android/app/src/main/kotlin/dev/focusforge/focusforge/shield/AppBlockingService.kt`)
- App boundary service → Accessibility shield: checks protected apps (evidence: `android/app/src/main/kotlin/dev/focusforge/focusforge/shield/AppBlockingService.kt`)
- App boundary service → Pause overlay: shows pause surface (evidence: `android/app/src/main/kotlin/dev/focusforge/focusforge/shield/AppBlockingService.kt`)
- Accessibility shield → Shield rules: loads rules (evidence: `android/app/src/main/kotlin/dev/focusforge/focusforge/shield/FocusAccessibilityService.kt`)
- Accessibility shield → Window visits: tracks visits (evidence: `android/app/src/main/kotlin/dev/focusforge/focusforge/shield/FocusAccessibilityService.kt`)
- Accessibility shield → YouTube policy: applies policy (evidence: `android/app/src/main/kotlin/dev/focusforge/focusforge/shield/FocusAccessibilityService.kt`)
- Accessibility shield → YouTube signals: reads signals (evidence: `android/app/src/main/kotlin/dev/focusforge/focusforge/shield/FocusAccessibilityService.kt`)
- Accessibility shield → Shield events: emits events (evidence: `android/app/src/main/kotlin/dev/focusforge/focusforge/shield/FocusAccessibilityService.kt`)
- Shield bridge → Shield events: drains queue (evidence: `android/app/src/main/kotlin/dev/focusforge/focusforge/shield/ShieldBridge.kt`)
- Study experience → Timer notification: starts countdown (evidence: `android/app/src/main/kotlin/dev/focusforge/focusforge/MainActivity.kt`)
- Android host → Timer notification: connects timer UI (evidence: `android/app/src/main/kotlin/dev/focusforge/focusforge/MainActivity.kt`)
- Android host → Home widgets: connects widgets (evidence: `android/app/src/main/kotlin/dev/focusforge/focusforge/MainActivity.kt`)
- Home widgets → Session summary: summarizes sessions (evidence: `android/app/src/main/kotlin/dev/focusforge/focusforge/widgets/FocusWidget.kt`)
- Home widgets → Retro renderer: renders retro (evidence: `android/app/src/main/kotlin/dev/focusforge/focusforge/widgets/FocusWidget.kt`)
- Home widgets → Weekly renderer: renders weekly (evidence: `android/app/src/main/kotlin/dev/focusforge/focusforge/widgets/FocusWidget.kt`)
- Home widgets → Goal plan: reads goal plan (evidence: `android/app/src/main/kotlin/dev/focusforge/focusforge/widgets/FocusWidget.kt`)
- Study experience → Pip nudges: presents study buddy (evidence: `android/app/src/main/kotlin/dev/focusforge/focusforge/MainActivity.kt`)
- Learner → Pip AI worker: asks Pip
- Pip AI worker → Token verification: verifies token (evidence: `pip-ai-backend/src/index.js`)
- Pip AI worker → Prompt handling: parses prompt (evidence: `pip-ai-backend/src/index.js`)
- Prompt handling → Privacy filtering: filters content (evidence: `pip-ai-backend/src/pip.js`)
- Pip AI worker → Reset delivery: uses reset delivery (evidence: `pip-ai-backend/src/index.js`)
- Pip AI worker → AI providers: requests completion (evidence: `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
