felipap/nudge

How felipap/nudge works

Nudge is a macOS focus-session app: users configure screen access and an AI backend, set an activity and duration, then the app periodically captures the screen, assesses whether it matches the goal, and nudges when it does not. The graph separates desktop orchestration, user-facing windows, capture/session processing, AI assessment, and persisted state. Several subsystem links are supported only by README or SOURCE INDEX references; unsampled implementation details are not inferred.

Main entry points: capture-service.ts Capture scheduler · shared/ipc.ts Renderer IPC API · src/ipc.ts Main IPC handlers · main.ts App lifecycle

Components 25

Desktop runtime

App lifecycle src/main.ts
Window manager src/windows.ts
Tray controls src/tray.ts
Main IPC handlers src/ipc.ts

User windows

Renderer IPC API windows/shared/ipc.ts
Onboarding flow windows/onboard/App/index.tsx
Model selection windows/onboard/App/step4-model/index.tsx
Settings screens windows/settings/App/screen/index.tsx
Goal input windows/main/App/InputScreen/index.tsx
Active session UI windows/main/App/ActiveSessionScreen/index.tsx

Session processing

Capture scheduler src/lib/capture-service.ts
Screen capture src/lib/screenshot.ts

AI assessment

AI assessment API src/ai/index.ts
OpenAI assessment src/ai/openai/assess-capture/index.ts
Gemini assessment src/ai/gemini/assess-capture/index.ts
Cloud proxy assessment src/ai/cloud/assess-capture.ts
Goal feedback src/ai/goal-feedback.ts

State and services

Persisted app state src/store/index.ts
File persistence src/store/backend.ts
Session and capture types src/store/types.ts
Telemetry src/lib/telemetry.ts
Logging and errors src/lib/logger.ts

Other components

User
AI service
macOS notifications

Connections 28

User → Onboarding flow: configures README.md
User → Goal input: sets activity README.md
App lifecycle → Main IPC handlers: registers src/main.ts
App lifecycle → Window manager: creates windows src/main.ts
App lifecycle → Capture scheduler: starts src/main.ts
App lifecycle → Tray controls: creates src/main.ts
Onboarding flow → Renderer IPC API: uses windows/onboard/App/index.tsx
Model selection → Renderer IPC API: updates settings windows/onboard/App/step4-model/index.tsx
Settings screens → Renderer IPC API: checks permissions windows/settings/App/screen/index.tsx
Goal input → Renderer IPC API: requests backend windows/main/App/InputScreen/useEvolvingFeedback.ts
Active session UI → Renderer IPC API: controls session
Renderer IPC API → Main IPC handlers: invokes handlers windows/shared/ipc.ts
Main IPC handlers → Persisted app state: reads and updates src/ipc.ts
Main IPC handlers → Goal feedback: requests feedback src/ipc.ts
Main IPC handlers → Telemetry: registers onboarding src/ipc.ts
Capture scheduler → Screen capture: captures screen src/lib/capture-service.ts
Capture scheduler → AI assessment API: assesses screenshot src/lib/capture-service.ts
Capture scheduler → Persisted app state: reads and updates src/lib/capture-service.ts
Capture scheduler → macOS notifications: sends nudge README.md
AI assessment API → OpenAI assessment: dispatches
AI assessment API → Gemini assessment: dispatches
AI assessment API → Cloud proxy assessment: dispatches
OpenAI assessment → AI service: sends image README.md
Cloud proxy assessment → AI service: proxies requests README.md
Goal feedback → AI service: requests feedback
Persisted app state → File persistence: persists through src/store/index.ts
Persisted app state → Session and capture types: uses state types src/store/index.ts
Capture scheduler → Logging and errors: logs events src/lib/capture-service.ts

Drawn by GitDiagram on November 11, 2026 from the repository's file tree, README and source files. Read as Markdown ·