# patilninad18/timeboard architecture

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

- Interactive diagram: https://gitdiagram.com/patilninad18/timeboard
- Repository: https://github.com/patilninad18/timeboard

## Overview

TimeBoard is a local-first Electron desktop app for tracking application use and helping users understand focus. The main flow is OS activity and idle sampling into SQLite, followed by classification and analytics; the Electron IPC bridge serves onboarding, dashboard, activity, analytics, reports, and settings in the React renderer. README documents midnight splitting, theme persistence, and CSV export; those capabilities are represented, though their internal wiring is not fully shown in the excerpts. Several backend services and UI pages are indexed but unsampled, so their detailed internal calls are omitted.

Main entry points: [`backend/main.js`](https://github.com/patilninad18/timeboard/blob/main/backend/main.js) (Electron main and IPC), [`frontend/src/App.jsx`](https://github.com/patilninad18/timeboard/blob/main/frontend/src/App.jsx) (Onboarding and routes), [`backend/db/database.js`](https://github.com/patilninad18/timeboard/blob/main/backend/db/database.js) (SQLite activity store), [`backend/services/classificationService.js`](https://github.com/patilninad18/timeboard/blob/main/backend/services/classificationService.js) (App classification)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_capture["Activity capture"]
  node_tracker["Usage tracker<br/>[appTracker.js]"]
  node_idle["Idle detection<br/>[idleService.js]"]
  node_domain["Browser domain mapping<br/>[domainExtractor.js]"]
end

subgraph group_backend["Local analysis"]
  node_database[("SQLite activity store<br/>[database.js]")]
  node_classification["App classification"]
  node_settings["Productivity and block rules"]
  node_stats["Focus statistics<br/>[statsService.js]"]
  node_aggregate["Daily usage rollup<br/>[dataAggregator.js]"]
  node_analytics["Usage analytics"]
  node_activity["Session timeline<br/>[activityService.js]"]
  node_reports["Reports and CSV<br/>[reportsService.js]"]
  node_insights["Productivity insights"]
  node_cleanup["Data management<br/>[dataCleanup.js]"]
end

subgraph group_bridge["Desktop bridge"]
  node_main["Electron main and IPC<br/>[main.js]"]
  node_preload["Safe renderer API<br/>[preload.cjs]"]
end

subgraph group_renderer["User experience"]
  node_renderer["React application<br/>[main.jsx]"]
  node_routing["Onboarding and routes<br/>[App.jsx]"]
  node_userctx["User settings context<br/>[UserContext.jsx]"]
  node_theme["Theme preferences<br/>[ThemeContext.jsx]"]
  node_dashboard["Dashboard<br/>[Dashboard.jsx]"]
  node_activitypage["Activity timeline<br/>[Activity.jsx]"]
  node_analyticspage["Analytics views<br/>[Analytics.jsx]"]
  node_reportspage["Reports view<br/>[Reports.jsx]"]
  node_settingspage["Settings view<br/>[Settings.jsx]"]
  node_landing["Landing and onboarding<br/>[Landing.jsx]"]
end

node_user(("Desktop user"))
node_os{{"Active window and idle state"}}

node_user -.->|"uses"| node_renderer
node_os -.->|"sampled by"| node_tracker
node_tracker -.->|"records sessions"| node_database
node_idle -.->|"reports idle"| node_tracker
node_domain -.->|"maps titles"| node_tracker
node_main -->|"starts tracking"| node_tracker
node_main -->|"dispatches stats"| node_stats
node_main -->|"dispatches usage"| node_aggregate
node_main -->|"dispatches queries"| node_analytics
node_main -->|"dispatches sessions"| node_activity
node_main -->|"dispatches reports"| node_reports
node_main -->|"dispatches insights"| node_insights
node_main -->|"dispatches cleanup"| node_cleanup
node_main -->|"updates rules"| node_settings
node_main -->|"sets classification"| node_classification
node_stats -->|"queries"| node_database
node_stats -->|"uses joins"| node_classification
node_activity -->|"queries sessions"| node_database
node_activity -->|"uses joins"| node_classification
node_reports -->|"queries aggregates"| node_database
node_reports -->|"uses joins"| node_classification
node_insights -->|"queries activity"| node_database
node_insights -->|"uses joins"| node_classification
node_classification -->|"reads rules"| node_database
node_settings -->|"stores rules"| node_database
node_renderer -->|"renders"| node_routing
node_renderer -->|"provides context"| node_userctx
node_renderer -->|"provides theme"| node_theme
node_routing -->|"routes to"| node_dashboard
node_routing -->|"routes to"| node_activitypage
node_routing -->|"routes to"| node_analyticspage
node_routing -->|"routes to"| node_reportspage
node_routing -->|"routes to"| node_settingspage
node_routing -->|"shows onboarding"| node_landing
node_userctx -.->|"calls API"| node_preload
node_preload -.->|"bridges IPC"| node_main
node_theme -.->|"persists preference"| node_user

click node_tracker "https://github.com/patilninad18/timeboard/blob/main/backend/services/appTracker.js"
click node_idle "https://github.com/patilninad18/timeboard/blob/main/backend/services/idleService.js"
click node_domain "https://github.com/patilninad18/timeboard/blob/main/backend/services/domainExtractor.js"
click node_database "https://github.com/patilninad18/timeboard/blob/main/backend/db/database.js"
click node_classification "https://github.com/patilninad18/timeboard/blob/main/backend/services/classificationService.js"
click node_settings "https://github.com/patilninad18/timeboard/blob/main/backend/services/productivityService.js"
click node_stats "https://github.com/patilninad18/timeboard/blob/main/backend/services/statsService.js"
click node_aggregate "https://github.com/patilninad18/timeboard/blob/main/backend/services/dataAggregator.js"
click node_analytics "https://github.com/patilninad18/timeboard/blob/main/backend/services/analyticsService.js"
click node_activity "https://github.com/patilninad18/timeboard/blob/main/backend/services/activityService.js"
click node_reports "https://github.com/patilninad18/timeboard/blob/main/backend/services/reportsService.js"
click node_insights "https://github.com/patilninad18/timeboard/blob/main/backend/services/aiInsightsService.js"
click node_cleanup "https://github.com/patilninad18/timeboard/blob/main/backend/services/dataCleanup.js"
click node_main "https://github.com/patilninad18/timeboard/blob/main/backend/main.js"
click node_preload "https://github.com/patilninad18/timeboard/blob/main/backend/preload.cjs"
click node_renderer "https://github.com/patilninad18/timeboard/blob/main/frontend/src/main.jsx"
click node_routing "https://github.com/patilninad18/timeboard/blob/main/frontend/src/App.jsx"
click node_userctx "https://github.com/patilninad18/timeboard/blob/main/frontend/src/context/UserContext.jsx"
click node_theme "https://github.com/patilninad18/timeboard/blob/main/frontend/src/context/ThemeContext.jsx"
click node_dashboard "https://github.com/patilninad18/timeboard/blob/main/frontend/src/pages/Dashboard.jsx"
click node_activitypage "https://github.com/patilninad18/timeboard/blob/main/frontend/src/pages/Activity.jsx"
click node_analyticspage "https://github.com/patilninad18/timeboard/blob/main/frontend/src/pages/Analytics.jsx"
click node_reportspage "https://github.com/patilninad18/timeboard/blob/main/frontend/src/pages/Reports.jsx"
click node_settingspage "https://github.com/patilninad18/timeboard/blob/main/frontend/src/pages/Settings.jsx"
click node_landing "https://github.com/patilninad18/timeboard/blob/main/frontend/src/pages/Landing.jsx"

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_tracker,node_idle,node_domain,node_user toneBlue
class node_database,node_classification,node_settings,node_stats,node_aggregate,node_analytics,node_activity,node_reports,node_insights,node_cleanup toneAmber
class node_main,node_preload toneMint
class node_renderer,node_routing,node_userctx,node_theme,node_dashboard,node_activitypage,node_analyticspage,node_reportspage,node_settingspage,node_landing toneRose
class node_os toneIndigo
```

## Components

### Activity capture

- [Usage tracker](https://github.com/patilninad18/timeboard/blob/main/backend/services/appTracker.js): `backend/services/appTracker.js`
- [Idle detection](https://github.com/patilninad18/timeboard/blob/main/backend/services/idleService.js): `backend/services/idleService.js`
- [Browser domain mapping](https://github.com/patilninad18/timeboard/blob/main/backend/services/domainExtractor.js): `backend/services/domainExtractor.js`

### Local analysis

- [SQLite activity store](https://github.com/patilninad18/timeboard/blob/main/backend/db/database.js): `backend/db/database.js`
- [App classification](https://github.com/patilninad18/timeboard/blob/main/backend/services/classificationService.js): `backend/services/classificationService.js`
- [Productivity and block rules](https://github.com/patilninad18/timeboard/blob/main/backend/services/productivityService.js): `backend/services/productivityService.js`
- [Focus statistics](https://github.com/patilninad18/timeboard/blob/main/backend/services/statsService.js): `backend/services/statsService.js`
- [Daily usage rollup](https://github.com/patilninad18/timeboard/blob/main/backend/services/dataAggregator.js): `backend/services/dataAggregator.js`
- [Usage analytics](https://github.com/patilninad18/timeboard/blob/main/backend/services/analyticsService.js): `backend/services/analyticsService.js`
- [Session timeline](https://github.com/patilninad18/timeboard/blob/main/backend/services/activityService.js): `backend/services/activityService.js`
- [Reports and CSV](https://github.com/patilninad18/timeboard/blob/main/backend/services/reportsService.js): `backend/services/reportsService.js`
- [Productivity insights](https://github.com/patilninad18/timeboard/blob/main/backend/services/aiInsightsService.js): `backend/services/aiInsightsService.js`
- [Data management](https://github.com/patilninad18/timeboard/blob/main/backend/services/dataCleanup.js): `backend/services/dataCleanup.js`

### Desktop bridge

- [Electron main and IPC](https://github.com/patilninad18/timeboard/blob/main/backend/main.js): `backend/main.js`
- [Safe renderer API](https://github.com/patilninad18/timeboard/blob/main/backend/preload.cjs): `backend/preload.cjs`

### User experience

- [React application](https://github.com/patilninad18/timeboard/blob/main/frontend/src/main.jsx): `frontend/src/main.jsx`
- [Onboarding and routes](https://github.com/patilninad18/timeboard/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [User settings context](https://github.com/patilninad18/timeboard/blob/main/frontend/src/context/UserContext.jsx): `frontend/src/context/UserContext.jsx`
- [Theme preferences](https://github.com/patilninad18/timeboard/blob/main/frontend/src/context/ThemeContext.jsx): `frontend/src/context/ThemeContext.jsx`
- [Dashboard](https://github.com/patilninad18/timeboard/blob/main/frontend/src/pages/Dashboard.jsx): `frontend/src/pages/Dashboard.jsx`
- [Activity timeline](https://github.com/patilninad18/timeboard/blob/main/frontend/src/pages/Activity.jsx): `frontend/src/pages/Activity.jsx`
- [Analytics views](https://github.com/patilninad18/timeboard/blob/main/frontend/src/pages/Analytics.jsx): `frontend/src/pages/Analytics.jsx`
- [Reports view](https://github.com/patilninad18/timeboard/blob/main/frontend/src/pages/Reports.jsx): `frontend/src/pages/Reports.jsx`
- [Settings view](https://github.com/patilninad18/timeboard/blob/main/frontend/src/pages/Settings.jsx): `frontend/src/pages/Settings.jsx`
- [Landing and onboarding](https://github.com/patilninad18/timeboard/blob/main/frontend/src/pages/Landing.jsx): `frontend/src/pages/Landing.jsx`

### Other components

- **Desktop user**
- **Active window and idle state**

## Connections

- Desktop user → React application: uses
- Active window and idle state → Usage tracker: sampled by
- Usage tracker → SQLite activity store: records sessions
- Idle detection → Usage tracker: reports idle
- Browser domain mapping → Usage tracker: maps titles
- Electron main and IPC → Usage tracker: starts tracking (evidence: `backend/main.js`)
- Electron main and IPC → Focus statistics: dispatches stats (evidence: `backend/main.js`)
- Electron main and IPC → Daily usage rollup: dispatches usage (evidence: `backend/main.js`)
- Electron main and IPC → Usage analytics: dispatches queries (evidence: `backend/main.js`)
- Electron main and IPC → Session timeline: dispatches sessions (evidence: `backend/main.js`)
- Electron main and IPC → Reports and CSV: dispatches reports (evidence: `backend/main.js`)
- Electron main and IPC → Productivity insights: dispatches insights (evidence: `backend/main.js`)
- Electron main and IPC → Data management: dispatches cleanup (evidence: `backend/main.js`)
- Electron main and IPC → Productivity and block rules: updates rules (evidence: `backend/main.js`)
- Electron main and IPC → App classification: sets classification (evidence: `backend/main.js`)
- Focus statistics → SQLite activity store: queries (evidence: `backend/services/statsService.js`)
- Focus statistics → App classification: uses joins (evidence: `backend/services/statsService.js`)
- Session timeline → SQLite activity store: queries sessions (evidence: `backend/services/activityService.js`)
- Session timeline → App classification: uses joins (evidence: `backend/services/activityService.js`)
- Reports and CSV → SQLite activity store: queries aggregates (evidence: `backend/services/reportsService.js`)
- Reports and CSV → App classification: uses joins (evidence: `backend/services/reportsService.js`)
- Productivity insights → SQLite activity store: queries activity (evidence: `backend/services/aiInsightsService.js`)
- Productivity insights → App classification: uses joins (evidence: `backend/services/aiInsightsService.js`)
- App classification → SQLite activity store: reads rules (evidence: `backend/services/classificationService.js`)
- Productivity and block rules → SQLite activity store: stores rules (evidence: `backend/services/productivityService.js`)
- React application → Onboarding and routes: renders (evidence: `frontend/src/main.jsx`)
- React application → User settings context: provides context (evidence: `frontend/src/main.jsx`)
- React application → Theme preferences: provides theme (evidence: `frontend/src/main.jsx`)
- Onboarding and routes → Dashboard: routes to (evidence: `frontend/src/App.jsx`)
- Onboarding and routes → Activity timeline: routes to (evidence: `frontend/src/App.jsx`)
- Onboarding and routes → Analytics views: routes to (evidence: `frontend/src/App.jsx`)
- Onboarding and routes → Reports view: routes to (evidence: `frontend/src/App.jsx`)
- Onboarding and routes → Settings view: routes to (evidence: `frontend/src/App.jsx`)
- Onboarding and routes → Landing and onboarding: shows onboarding (evidence: `frontend/src/App.jsx`)
- User settings context → Safe renderer API: calls API
- Safe renderer API → Electron main and IPC: bridges IPC
- Theme preferences → Desktop user: persists preference