# shreenathmehta32/focusorm architecture

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

- Interactive diagram: https://gitdiagram.com/shreenathmehta32/focusorm
- Repository: https://github.com/shreenathmehta32/focusorm

## Overview

FocusORM is a local-first productivity tracker: it observes desktop and browser activity, groups it into sessions, classifies sessions, stores metrics locally, and presents analytics and privacy controls. The README documents additional analytics capabilities whose implementations were not sampled; these are represented at their documented module paths, with uncertain internal wiring omitted.

Main entry points: [`agent/main.py`](https://github.com/shreenathmehta32/focusorm/blob/main/agent/main.py) (Tracking agent), [`frontend/src/api/client.js`](https://github.com/shreenathmehta32/focusorm/blob/main/frontend/src/api/client.js) (API client), [`backend/routes`](https://github.com/shreenathmehta32/focusorm/tree/main/backend/routes) (Product API routes), [`classifier/local_classifier.py`](https://github.com/shreenathmehta32/focusorm/blob/main/classifier/local_classifier.py) (Local classifier)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_capture["Activity capture"]
  node_desktop["Desktop tracker<br/>[tracker.py]"]
  node_interactions["Interaction metrics"]
  node_coding["Coding metrics<br/>[coding_tracker.py]"]
  node_idle["Idle detection<br/>[idle_detector.py]"]
  node_extension["Browser extension<br/>[background.js]"]
  node_agent["Tracking agent<br/>[main.py]"]
end

subgraph group_classify["Session intelligence"]
  node_sessions["Session lifecycle<br/>[session_manager.py]"]
  node_classifier["Local classifier"]
  node_rules["Classification rules<br/>[rules.py]"]
  node_sanitizer["Privacy sanitizer<br/>[sanitizer.py]"]
end

subgraph group_analysis["Local analytics"]
  node_sqlite[("Local SQLite<br/>[database.py]")]
  node_analytics["Productivity analytics"]
  node_focus["Focus analysis<br/>[focus_service.py]"]
  node_inactivity["Inactivity analysis"]
end

subgraph group_service["Local service"]
  node_api["FastAPI backend<br/>[main.py]"]
  node_routes["Product API routes"]
  node_privacy["Privacy controls<br/>[privacy.py]"]
  node_settings["Settings controls<br/>[settings.py]"]
end

subgraph group_experience["Dashboard experience"]
  node_dashboard["Dashboard pages"]
  node_client["API client<br/>[client.js]"]
end

node_student(("Student"))
node_groq{{"Groq AI"}}

node_student -->|"uses"| node_desktop
node_student -->|"uses"| node_extension
node_desktop -->|"window state"| node_agent
node_interactions -->|"metrics"| node_agent
node_coding -->|"file metrics"| node_agent
node_idle -->|"idle state"| node_agent
node_extension -->|"tab context"| node_agent
node_api -->|"starts and stops"| node_agent
node_agent -->|"manages sessions"| node_sessions
node_agent -->|"classifies sessions"| node_classifier
node_classifier -->|"checks rules"| node_rules
node_classifier -.->|"sanitizes unknowns"| node_sanitizer
node_classifier -.->|"classifies unknowns"| node_groq
node_sessions -->|"writes sessions"| node_sqlite
node_analytics -->|"reads sessions"| node_sqlite
node_focus -->|"reads sessions"| node_sqlite
node_inactivity -->|"reads sessions"| node_sqlite
node_api -->|"registers routes"| node_routes
node_routes -->|"requests stats"| node_analytics
node_routes -->|"requests focus"| node_focus
node_routes -->|"requests analysis"| node_inactivity
node_dashboard -->|"requests data"| node_client
node_client -->|"HTTP requests"| node_api
node_client -->|"calls endpoints"| node_routes
node_client -->|"privacy actions"| node_privacy
node_client -->|"settings actions"| node_settings
node_sanitizer -.->|"minimal payload"| node_groq

click node_desktop "https://github.com/shreenathmehta32/focusorm/blob/main/agent/tracker.py"
click node_interactions "https://github.com/shreenathmehta32/focusorm/blob/main/agent/interaction_tracker.py"
click node_coding "https://github.com/shreenathmehta32/focusorm/blob/main/agent/coding_tracker.py"
click node_idle "https://github.com/shreenathmehta32/focusorm/blob/main/agent/idle_detector.py"
click node_extension "https://github.com/shreenathmehta32/focusorm/blob/main/browser_extension/background.js"
click node_agent "https://github.com/shreenathmehta32/focusorm/blob/main/agent/main.py"
click node_sessions "https://github.com/shreenathmehta32/focusorm/blob/main/agent/session_manager.py"
click node_classifier "https://github.com/shreenathmehta32/focusorm/blob/main/classifier/local_classifier.py"
click node_rules "https://github.com/shreenathmehta32/focusorm/blob/main/classifier/rules.py"
click node_sanitizer "https://github.com/shreenathmehta32/focusorm/blob/main/classifier/sanitizer.py"
click node_sqlite "https://github.com/shreenathmehta32/focusorm/blob/main/backend/database.py"
click node_analytics "https://github.com/shreenathmehta32/focusorm/blob/main/backend/services/analytics_service.py"
click node_focus "https://github.com/shreenathmehta32/focusorm/blob/main/backend/services/focus_service.py"
click node_inactivity "https://github.com/shreenathmehta32/focusorm/blob/main/backend/services/inactivity_service.py"
click node_api "https://github.com/shreenathmehta32/focusorm/blob/main/backend/main.py"
click node_routes "https://github.com/shreenathmehta32/focusorm/tree/main/backend/routes"
click node_dashboard "https://github.com/shreenathmehta32/focusorm/tree/main/frontend/src/pages"
click node_client "https://github.com/shreenathmehta32/focusorm/blob/main/frontend/src/api/client.js"
click node_privacy "https://github.com/shreenathmehta32/focusorm/blob/main/backend/routes/privacy.py"
click node_settings "https://github.com/shreenathmehta32/focusorm/blob/main/backend/routes/settings.py"

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_desktop,node_interactions,node_coding,node_idle,node_extension,node_agent toneBlue
class node_sessions,node_classifier,node_rules,node_sanitizer toneAmber
class node_sqlite,node_analytics,node_focus,node_inactivity toneMint
class node_api,node_routes,node_privacy,node_settings toneRose
class node_dashboard,node_client,node_student,node_groq toneIndigo
```

## Components

### Activity capture

- [Desktop tracker](https://github.com/shreenathmehta32/focusorm/blob/main/agent/tracker.py): `agent/tracker.py`
- [Interaction metrics](https://github.com/shreenathmehta32/focusorm/blob/main/agent/interaction_tracker.py): `agent/interaction_tracker.py`
- [Coding metrics](https://github.com/shreenathmehta32/focusorm/blob/main/agent/coding_tracker.py): `agent/coding_tracker.py`
- [Idle detection](https://github.com/shreenathmehta32/focusorm/blob/main/agent/idle_detector.py): `agent/idle_detector.py`
- [Browser extension](https://github.com/shreenathmehta32/focusorm/blob/main/browser_extension/background.js): `browser_extension/background.js`
- [Tracking agent](https://github.com/shreenathmehta32/focusorm/blob/main/agent/main.py): `agent/main.py`

### Session intelligence

- [Session lifecycle](https://github.com/shreenathmehta32/focusorm/blob/main/agent/session_manager.py): `agent/session_manager.py`
- [Local classifier](https://github.com/shreenathmehta32/focusorm/blob/main/classifier/local_classifier.py): `classifier/local_classifier.py`
- [Classification rules](https://github.com/shreenathmehta32/focusorm/blob/main/classifier/rules.py): `classifier/rules.py`
- [Privacy sanitizer](https://github.com/shreenathmehta32/focusorm/blob/main/classifier/sanitizer.py): `classifier/sanitizer.py`

### Local analytics

- [Local SQLite](https://github.com/shreenathmehta32/focusorm/blob/main/backend/database.py): `backend/database.py`
- [Productivity analytics](https://github.com/shreenathmehta32/focusorm/blob/main/backend/services/analytics_service.py): `backend/services/analytics_service.py`
- [Focus analysis](https://github.com/shreenathmehta32/focusorm/blob/main/backend/services/focus_service.py): `backend/services/focus_service.py`
- [Inactivity analysis](https://github.com/shreenathmehta32/focusorm/blob/main/backend/services/inactivity_service.py): `backend/services/inactivity_service.py`

### Local service

- [FastAPI backend](https://github.com/shreenathmehta32/focusorm/blob/main/backend/main.py): `backend/main.py`
- [Product API routes](https://github.com/shreenathmehta32/focusorm/tree/main/backend/routes): `backend/routes`
- [Privacy controls](https://github.com/shreenathmehta32/focusorm/blob/main/backend/routes/privacy.py): `backend/routes/privacy.py`
- [Settings controls](https://github.com/shreenathmehta32/focusorm/blob/main/backend/routes/settings.py): `backend/routes/settings.py`

### Dashboard experience

- [Dashboard pages](https://github.com/shreenathmehta32/focusorm/tree/main/frontend/src/pages): `frontend/src/pages`
- [API client](https://github.com/shreenathmehta32/focusorm/blob/main/frontend/src/api/client.js): `frontend/src/api/client.js`

### Other components

- **Student**
- **Groq AI**

## Connections

- Student → Desktop tracker: uses
- Student → Browser extension: uses
- Desktop tracker → Tracking agent: window state
- Interaction metrics → Tracking agent: metrics
- Coding metrics → Tracking agent: file metrics
- Idle detection → Tracking agent: idle state
- Browser extension → Tracking agent: tab context
- FastAPI backend → Tracking agent: starts and stops
- Tracking agent → Session lifecycle: manages sessions
- Tracking agent → Local classifier: classifies sessions
- Local classifier → Classification rules: checks rules
- Local classifier → Privacy sanitizer: sanitizes unknowns
- Local classifier → Groq AI: classifies unknowns
- Session lifecycle → Local SQLite: writes sessions
- Productivity analytics → Local SQLite: reads sessions
- Focus analysis → Local SQLite: reads sessions
- Inactivity analysis → Local SQLite: reads sessions
- FastAPI backend → Product API routes: registers routes
- Product API routes → Productivity analytics: requests stats
- Product API routes → Focus analysis: requests focus
- Product API routes → Inactivity analysis: requests analysis
- Dashboard pages → API client: requests data
- API client → FastAPI backend: HTTP requests
- API client → Product API routes: calls endpoints
- API client → Privacy controls: privacy actions
- API client → Settings controls: settings actions
- Privacy sanitizer → Groq AI: minimal payload