# shubgupta10/focus-app architecture

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

- Interactive diagram: https://gitdiagram.com/shubgupta10/focus-app
- Repository: https://github.com/shubgupta10/focus-app

## Overview

Lockout is an offline-first Android focus app: users choose distracting apps, start a timed or open-ended focus session, and the native blocker enforces it; completed sessions contribute to on-device statistics and coin rewards. The app also supports recurring routines, strict mode, appearance customization, permissions, notifications, data management, and feedback. The graph combines documented product capabilities with relationships visible in sampled excerpts and the source index; several screens and native implementation files were not sampled, so their internal wiring is not inferred.

Main entry points: [`src/hooks/useFocusEngine.ts`](https://github.com/shubgupta10/focus-app/blob/main/src/hooks/useFocusEngine.ts) (Focus engine), [`src/features/session/hooks/useSessionController.ts`](https://github.com/shubgupta10/focus-app/blob/main/src/features/session/hooks/useSessionController.ts) (Session lifecycle), [`src/hooks/useRoutines.ts`](https://github.com/shubgupta10/focus-app/blob/main/src/hooks/useRoutines.ts) (Routine manager), [`src/features/shop/hooks/useShopController.ts`](https://github.com/shubgupta10/focus-app/blob/main/src/features/shop/hooks/useShopController.ts) (Theme shop)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["App experience"]
  node_home["Home and sessions<br/>[index.tsx]"]
  node_app_navigation["App navigation<br/>[_layout.tsx]"]
  node_onboarding["Onboarding"]
end

subgraph group_focus["Focus and blocking"]
  node_blocklist_screen["App blocklist<br/>[apps.tsx]"]
  node_blocklist_controller["Blocklist controls"]
  node_session_controller["Session lifecycle"]
  node_focus_engine["Focus engine<br/>[useFocusEngine.ts]"]
  node_native_bridge["Blocker module"]
  node_android_service["Android blocker<br/>[FocusService.kt]"]
end

subgraph group_routines["Routine scheduling"]
  node_routines_screen["Routine schedules<br/>[routines.tsx]"]
  node_routine_controller["Routine controls"]
  node_routine_hook["Routine manager<br/>[useRoutines.ts]"]
  node_routine_repository[("Routine storage")]
end

subgraph group_data_rewards["Data and rewards"]
  node_local_database[("Local database<br/>[database.ts]")]
  node_app_state["App state<br/>[useAppStore.ts]"]
  node_statistics[("Statistics<br/>[statsRepository.ts]")]
  node_shop["Theme shop"]
  node_catalog["Shop catalog<br/>[shopCatalog.ts]"]
end

subgraph group_support["Settings and support"]
  node_theme["Appearance<br/>[ThemeContext.tsx]"]
  node_settings["Settings<br/>[useSettings.ts]"]
  node_data_management["Data management"]
  node_feedback["Feedback"]
  node_analytics["Anonymous analytics<br/>[analytics.ts]"]
end

node_user(("User"))
node_aptabase["Aptabase"]

node_user -->|"opens app"| node_app_navigation
node_app_navigation -.->|"shows home"| node_home
node_onboarding -->|"configures apps"| node_focus_engine
node_blocklist_screen -->|"uses controls"| node_blocklist_controller
node_blocklist_controller -->|"toggles apps"| node_focus_engine
node_focus_engine -->|"updates state"| node_app_state
node_focus_engine -->|"updates blocklist"| node_native_bridge
node_session_controller -->|"controls sessions"| node_focus_engine
node_session_controller -.->|"records session"| node_app_state
node_native_bridge -.->|"dispatches blocking"| node_android_service
node_user -->|"sets schedules"| node_routines_screen
node_routines_screen -.->|"uses controls"| node_routine_controller
node_routine_controller -->|"manages routines"| node_routine_hook
node_routine_hook -->|"reads and writes"| node_routine_repository
node_routine_hook -->|"schedules alarms"| node_native_bridge
node_app_state -->|"loads statistics"| node_statistics
node_session_controller -.->|"updates totals"| node_statistics
node_user -->|"customizes orb"| node_shop
node_shop -->|"reads catalog"| node_catalog
node_shop -->|"saves appearance"| node_settings
node_theme -->|"loads preferences"| node_settings
node_user -.->|"backs up data"| node_data_management
node_user -.->|"sends feedback"| node_feedback
node_analytics -->|"sends events"| node_aptabase

click node_home "https://github.com/shubgupta10/focus-app/blob/main/src/app/(tabs)/index.tsx"
click node_app_navigation "https://github.com/shubgupta10/focus-app/blob/main/src/app/(tabs)/_layout.tsx"
click node_onboarding "https://github.com/shubgupta10/focus-app/blob/main/src/features/onboarding/hooks/useOnboardingController.ts"
click node_blocklist_screen "https://github.com/shubgupta10/focus-app/blob/main/src/app/(tabs)/apps.tsx"
click node_blocklist_controller "https://github.com/shubgupta10/focus-app/blob/main/src/features/blocklist/hooks/useBlocklistController.ts"
click node_session_controller "https://github.com/shubgupta10/focus-app/blob/main/src/features/session/hooks/useSessionController.ts"
click node_focus_engine "https://github.com/shubgupta10/focus-app/blob/main/src/hooks/useFocusEngine.ts"
click node_native_bridge "https://github.com/shubgupta10/focus-app/blob/main/modules/focus-blocker/src/FocusBlockerModule.ts"
click node_android_service "https://github.com/shubgupta10/focus-app/blob/main/modules/focus-blocker/android/src/main/java/expo/modules/focusblocker/FocusService.kt"
click node_routines_screen "https://github.com/shubgupta10/focus-app/blob/main/src/app/(tabs)/routines.tsx"
click node_routine_controller "https://github.com/shubgupta10/focus-app/blob/main/src/features/routines/hooks/useRoutinesController.ts"
click node_routine_hook "https://github.com/shubgupta10/focus-app/blob/main/src/hooks/useRoutines.ts"
click node_routine_repository "https://github.com/shubgupta10/focus-app/blob/main/src/features/routines/db/routineRepository.ts"
click node_local_database "https://github.com/shubgupta10/focus-app/blob/main/src/store/database.ts"
click node_app_state "https://github.com/shubgupta10/focus-app/blob/main/src/store/useAppStore.ts"
click node_statistics "https://github.com/shubgupta10/focus-app/blob/main/src/features/stats/db/statsRepository.ts"
click node_shop "https://github.com/shubgupta10/focus-app/blob/main/src/features/shop/hooks/useShopController.ts"
click node_catalog "https://github.com/shubgupta10/focus-app/blob/main/src/features/shop/data/shopCatalog.ts"
click node_theme "https://github.com/shubgupta10/focus-app/blob/main/src/contexts/ThemeContext.tsx"
click node_settings "https://github.com/shubgupta10/focus-app/blob/main/src/hooks/useSettings.ts"
click node_data_management "https://github.com/shubgupta10/focus-app/blob/main/src/features/data-management/hooks/useDataManagementController.ts"
click node_feedback "https://github.com/shubgupta10/focus-app/blob/main/src/features/feedback/hooks/useFeedbackController.ts"
click node_analytics "https://github.com/shubgupta10/focus-app/blob/main/src/utils/analytics.ts"

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_home,node_app_navigation,node_onboarding,node_user toneBlue
class node_blocklist_screen,node_blocklist_controller,node_session_controller,node_focus_engine,node_native_bridge,node_android_service toneAmber
class node_routines_screen,node_routine_controller,node_routine_hook,node_routine_repository toneMint
class node_local_database,node_app_state,node_statistics,node_shop,node_catalog toneRose
class node_theme,node_settings,node_data_management,node_feedback,node_analytics,node_aptabase toneIndigo
```

## Components

### App experience

- [Home and sessions](https://github.com/shubgupta10/focus-app/blob/main/src/app/(tabs)/index.tsx): `src/app/(tabs)/index.tsx`
- [App navigation](https://github.com/shubgupta10/focus-app/blob/main/src/app/(tabs)/_layout.tsx): `src/app/(tabs)/_layout.tsx`
- [Onboarding](https://github.com/shubgupta10/focus-app/blob/main/src/features/onboarding/hooks/useOnboardingController.ts): `src/features/onboarding/hooks/useOnboardingController.ts`

### Focus and blocking

- [App blocklist](https://github.com/shubgupta10/focus-app/blob/main/src/app/(tabs)/apps.tsx): `src/app/(tabs)/apps.tsx`
- [Blocklist controls](https://github.com/shubgupta10/focus-app/blob/main/src/features/blocklist/hooks/useBlocklistController.ts): `src/features/blocklist/hooks/useBlocklistController.ts`
- [Session lifecycle](https://github.com/shubgupta10/focus-app/blob/main/src/features/session/hooks/useSessionController.ts): `src/features/session/hooks/useSessionController.ts`
- [Focus engine](https://github.com/shubgupta10/focus-app/blob/main/src/hooks/useFocusEngine.ts): `src/hooks/useFocusEngine.ts`
- [Blocker module](https://github.com/shubgupta10/focus-app/blob/main/modules/focus-blocker/src/FocusBlockerModule.ts): `modules/focus-blocker/src/FocusBlockerModule.ts`
- [Android blocker](https://github.com/shubgupta10/focus-app/blob/main/modules/focus-blocker/android/src/main/java/expo/modules/focusblocker/FocusService.kt): `modules/focus-blocker/android/src/main/java/expo/modules/focusblocker/FocusService.kt`

### Routine scheduling

- [Routine schedules](https://github.com/shubgupta10/focus-app/blob/main/src/app/(tabs)/routines.tsx): `src/app/(tabs)/routines.tsx`
- [Routine controls](https://github.com/shubgupta10/focus-app/blob/main/src/features/routines/hooks/useRoutinesController.ts): `src/features/routines/hooks/useRoutinesController.ts`
- [Routine manager](https://github.com/shubgupta10/focus-app/blob/main/src/hooks/useRoutines.ts): `src/hooks/useRoutines.ts`
- [Routine storage](https://github.com/shubgupta10/focus-app/blob/main/src/features/routines/db/routineRepository.ts): `src/features/routines/db/routineRepository.ts`

### Data and rewards

- [Local database](https://github.com/shubgupta10/focus-app/blob/main/src/store/database.ts): `src/store/database.ts`
- [App state](https://github.com/shubgupta10/focus-app/blob/main/src/store/useAppStore.ts): `src/store/useAppStore.ts`
- [Statistics](https://github.com/shubgupta10/focus-app/blob/main/src/features/stats/db/statsRepository.ts): `src/features/stats/db/statsRepository.ts`
- [Theme shop](https://github.com/shubgupta10/focus-app/blob/main/src/features/shop/hooks/useShopController.ts): `src/features/shop/hooks/useShopController.ts`
- [Shop catalog](https://github.com/shubgupta10/focus-app/blob/main/src/features/shop/data/shopCatalog.ts): `src/features/shop/data/shopCatalog.ts`

### Settings and support

- [Appearance](https://github.com/shubgupta10/focus-app/blob/main/src/contexts/ThemeContext.tsx): `src/contexts/ThemeContext.tsx`
- [Settings](https://github.com/shubgupta10/focus-app/blob/main/src/hooks/useSettings.ts): `src/hooks/useSettings.ts`
- [Data management](https://github.com/shubgupta10/focus-app/blob/main/src/features/data-management/hooks/useDataManagementController.ts): `src/features/data-management/hooks/useDataManagementController.ts`
- [Feedback](https://github.com/shubgupta10/focus-app/blob/main/src/features/feedback/hooks/useFeedbackController.ts): `src/features/feedback/hooks/useFeedbackController.ts`
- [Anonymous analytics](https://github.com/shubgupta10/focus-app/blob/main/src/utils/analytics.ts): `src/utils/analytics.ts`

### Other components

- **User**
- **Aptabase**

## Connections

- User → App navigation: opens app
- App navigation → Home and sessions: shows home
- Onboarding → Focus engine: configures apps (evidence: `src/features/onboarding/hooks/useOnboardingController.ts`)
- App blocklist → Blocklist controls: uses controls (evidence: `src/app/(tabs)/apps.tsx`)
- Blocklist controls → Focus engine: toggles apps (evidence: `src/features/blocklist/hooks/useBlocklistController.ts`)
- Focus engine → App state: updates state (evidence: `src/hooks/useFocusEngine.ts`)
- Focus engine → Blocker module: updates blocklist (evidence: `src/hooks/useFocusEngine.ts`)
- Session lifecycle → Focus engine: controls sessions (evidence: `src/features/session/hooks/useSessionController.ts`)
- Session lifecycle → App state: records session (evidence: `src/features/session/hooks/useSessionController.ts`)
- Blocker module → Android blocker: dispatches blocking
- User → Routine schedules: sets schedules
- Routine schedules → Routine controls: uses controls
- Routine controls → Routine manager: manages routines (evidence: `src/features/routines/hooks/useRoutinesController.ts`)
- Routine manager → Routine storage: reads and writes (evidence: `src/hooks/useRoutines.ts`)
- Routine manager → Blocker module: schedules alarms (evidence: `src/hooks/useRoutines.ts`)
- App state → Statistics: loads statistics (evidence: `src/store/useAppStore.ts`)
- Session lifecycle → Statistics: updates totals
- User → Theme shop: customizes orb
- Theme shop → Shop catalog: reads catalog (evidence: `src/features/shop/hooks/useShopController.ts`)
- Theme shop → Settings: saves appearance (evidence: `src/features/shop/hooks/useShopController.ts`)
- Appearance → Settings: loads preferences (evidence: `src/contexts/ThemeContext.tsx`)
- User → Data management: backs up data
- User → Feedback: sends feedback
- Anonymous analytics → Aptabase: sends events (evidence: `src/utils/analytics.ts`)
