# nst-sdc/screentime-recoder architecture

> Architecture diagram of the GitHub repository nst-sdc/screentime-recoder, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nst-sdc/screentime-recoder
- Repository: https://github.com/nst-sdc/screentime-recoder

## Overview

##### Project type and purpose
- This is a full-stack “Screen Time Recorder” application with three primary parts:
- A Browser Extension (collects real-time screen and gaze data)
- A React Frontend (“client” folder) for the user dashboard
- A Node.js/Express Backend API (“server” folder) with data storage and AI processing
- Purpose: monitor user screen usage and eye movements, analyze focus via AI tools, store results, and display analytics.

##### File structure
- Top-level folders:
- client/ – React SPA (components, pages, services, contexts)
- extension/ – browser extension (background.js, content.js, popup)
- server/ – Express REST API (config, controllers, models, routes, services, middleware, utils)
- Config and infra files: .env.example, package.json, Vercel/Railway hints, Docker (if added later)
- Notable patterns:
- Server uses MVC (models/controllers/routes) + service/util layers
- Frontend uses React Context for auth + service layer for API calls
- Extension injects scripts and sends data to the backend API

##### Extract architecture details from the README
- Tech stack: React, Node.js/Express, MongoDB/PostgreSQL (TBD), JWT/Firebase Auth, OpenCV/MediaPipe/Tesseract AI tools
- Features mapped to components: screen monitoring (extension), eye tracking (extension + AI libs on server?), focus analytics (server), personalized dashboard (frontend)

a. Main components to represent:
1. Browser Extension
2. Frontend React App
3. Backend API Server
4. Database (MongoDB/PostgreSQL)
5. Authentication Service (JWT or Firebase Auth)
6. AI Processing Modules (OpenCV, MediaPipe, Tesseract, optionally external AI service like Gemini)
7. (Optional) Notification/Reminder service (email/SMS or push)
b. Relationships & interactions:
- Extension → collects screen and eye data → sends payload over HTTPS to Backend API
- Backend → invokes AI Modules for OCR & eye-tracking analysis → writes processed records to Database
- Frontend → uses Auth Service to obtain token → calls Backend API for dashboards, reminders, analytics
- Backend → triggers Reminder Service or push notifications based on rules
c. Architectural patterns & design principles:
- Layered architecture (Presentation, API, Business Logic, Data Access)
- MVC on server side (Models, Controllers, Routes)
- Separation of concerns: extension handles capture, server handles processing+storage, client handles visualization
- Use of Context/Service abstractions in React for state & API
- React.js (client components, contexts, pages)
- Express.js & Node.js (controllers, middleware, routes)
- MongoDB or PostgreSQL (models/data)
- JWT / Firebase Auth
- OpenCV, MediaPipe, Tesseract modules (as server-side services)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data Capture Layer
    subgraph "Data Capture Layer"
        ExtBg["Background Script"]:::capture
        ExtContent["Content Script"]:::capture
        ExtPopup["Popup UI"]:::capture
        ExtConfig["Extension Config"]:::capture
    end

    %% API & Processing Layer
    subgraph "API & Processing Layer"
        APIServer["Express API Server"]:::api
        AuthConfig["Auth Setup (Passport/JWT)"]:::api
        Controllers["Controllers"]:::api
        Routes["Routes"]:::api
        Models["Data Models"]:::db
        DB["Database (MongoDB/PostgreSQL)"]:::db
        AI["AI Processing Service"]:::api
        Reminder["Reminder Service"]:::apiPending
    end

    %% Presentation Layer
    subgraph "Presentation Layer"
        ReactApp["React Application"]:::frontend
    end

    %% Connections
    ExtContent -->|"POST /track-data (JSON)"| APIServer
    ExtBg -->|"WebSocket/Push Data"| APIServer
    ExtPopup -->|"User Config & Controls"| ExtConfig
    ExtConfig -->|“Saves settings”| APIServer

    ReactApp -->|"REST GET /dashboard"| APIServer
    ReactApp -->|"Auth Token" | AuthConfig
    AuthConfig -->|“Validate Token”| APIServer

    APIServer -->|"Invoke Controllers"| Controllers
    Controllers -->|"Use Routes"| Routes
    Controllers -->|"Read/Write"| Models
    Models -->|"Store/Retrieve"| DB
    APIServer -->|"Call AI Modules"| AI
    APIServer -->|"Trigger Reminders"| Reminder

    %% Click Events
    click ExtBg "https://github.com/nst-sdc/screentime-recoder/blob/main/extension/background.js"
    click ExtContent "https://github.com/nst-sdc/screentime-recoder/blob/main/extension/content.js"
    click ExtPopup "https://github.com/nst-sdc/screentime-recoder/blob/main/extension/popup.html"
    click ExtConfig "https://github.com/nst-sdc/screentime-recoder/blob/main/extension/config.js"

    click ReactApp "https://github.com/nst-sdc/screentime-recoder/blob/main/client/src/App.jsx"

    click APIServer "https://github.com/nst-sdc/screentime-recoder/blob/main/server/server.js"
    click AuthConfig "https://github.com/nst-sdc/screentime-recoder/blob/main/server/config/passport.js"
    click Controllers "https://github.com/nst-sdc/screentime-recoder/blob/main/server/controllers/auth.controller.js"
    click Routes "https://github.com/nst-sdc/screentime-recoder/blob/main/server/routes/auth.route.js"
    click Models "https://github.com/nst-sdc/screentime-recoder/blob/main/server/models/user.model.js"
    click DB "https://github.com/nst-sdc/screentime-recoder/blob/main/server/config/db.js"
    click AI "https://github.com/nst-sdc/screentime-recoder/blob/main/server/services/geminiService.js"
    click Reminder "https://github.com/nst-sdc/screentime-recoder/blob/main/server/controllers/reminder.controller.js"

    %% Styles
    classDef capture fill:#CCE5FF,stroke:#3399FF
    classDef api fill:#CCFFCC,stroke:#33CC33
    classDef db fill:#FFEB99,stroke:#FFCC00
    classDef frontend fill:#FFE5CC,stroke:#FF9933
    classDef apiPending fill:#F0F0F0,stroke:#AAAAAA,dasharray: 5 5
```
