Digital Behavior Mirror - Comprehensive Deployment Guide

Table of Contents

1. Overview
2. Project Structure
3. Installation
4. Running Locally
5. Chrome Extension Setup
6. Deployment
7. API Documentation
8. Testing
9. Future Enhancements

---

Overview

Digital Behavior Mirror is a full-stack web application that passively tracks browser activity and generates actionable focus insights. It consists of:

• Backend: FastAPI REST API with SQLite database
• Frontend: Next.js React application with interactive dashboards
• Extension: Chrome extension for passive browser tracking
• Analytics: AI-powered insights generation with automatic URL categorization

MVP Features

✅ Passive browser activity tracking
✅ Automatic URL categorization (Work, Learning, Social, Entertainment, Other)
✅ Daily session summaries with analytics
✅ Real-time charts and focus statistics
✅ AI-generated insights and recommendations
✅ Chrome extension for seamless tracking
✅ No authentication required
✅ Local SQLite database

---

Project Structure

digital-behavior-mirror/
├── backend/
│   ├── main.py              # FastAPI application
│   ├── database.py          # SQLite database management
│   ├── models.py            # Pydantic models
│   ├── insights.py          # AI insights & categorization logic
│   ├── requirements.txt      # Python dependencies
│   └── behavior_mirror.db   # SQLite database (auto-created)
│
├── frontend/
│   ├── pages/
│   │   ├── index.tsx        # Landing/Home page
│   │   ├── dashboard.tsx    # Analytics dashboard
│   │   ├── sessions.tsx     # Sessions history
│   │   ├── _app.tsx         # Next.js app wrapper
│   │   └── _document.tsx    # HTML document
│   ├── components/
│   │   ├── Header.tsx       # Navigation header
│   │   ├── Footer.tsx       # Footer
│   │   ├── Layout.tsx       # Page layout wrapper
│   │   ├── CategoryChart.tsx # Category time chart
│   │   ├── TabSwitchChart.tsx # Tab switch timeline
│   │   ├── FocusStats.tsx   # Focus metrics display
│   │   └── AIInsights.tsx   # AI insights component
│   ├── hooks/
│   │   └── useApi.ts        # API integration hooks
│   ├── styles/
│   │   └── globals.css      # Global styles
│   ├── package.json         # Dependencies
│   ├── tailwind.config.js   # TailwindCSS config
│   └── next.config.js       # Next.js config
│
├── extension/
│   ├── manifest.json        # Chrome extension manifest
│   ├── background.js        # Background service worker
│   ├── popup.html           # Extension popup UI
│   └── popup.js             # Popup logic
│
├── .env.example             # Environment variables template
├── README.md                # This file
└── install.sh              # Installation script

---

Installation

Prerequisites

• Python 3.8+ - For backend
• Node.js 16+ - For frontend
• npm or yarn - Package manager
• Chrome/Chromium - For extension and testing

Step 1: Clone/Extract the Project

cd digital-behavior-mirror

Step 2: Setup Backend

# Navigate to backend directory
cd backend

# Create Python virtual environment
python -m venv venv

# Activate virtual environment
# On Windows:
venv\Scripts\activate
# On macOS/Linux:
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Database will be auto-initialized on first run

Step 3: Setup Frontend

# Navigate to frontend directory
cd ../frontend

# Install Node dependencies
npm install

# Build Next.js (optional, for production)
npm run build

Step 4: Environment Configuration

# Create .env files from templates
cp .env.example .env.local

# Edit environment variables as needed
# Default values work for local development

---

Running Locally

Terminal 1: Start Backend Server

cd backend
source venv/bin/activate  # or venv\Scripts\activate on Windows
uvicorn main:app --reload --host 0.0.0.0 --port 8000

Backend will be available at: http://localhost:8000
API docs available at: http://localhost:8000/docs

Terminal 2: Start Frontend Development Server

cd frontend
npm run dev

Frontend will be available at: http://localhost:3000

Terminal 3: Load Chrome Extension

1. Open Chrome and go to chrome://extensions
2. Enable "Developer mode" (toggle in top-right)
3. Click "Load unpacked"
4. Navigate to digital-behavior-mirror/extension folder
5. Click "Select Folder"

The extension will appear in your toolbar with a purple icon.

---

Chrome Extension Setup

Manual Activity Logging (Web MVP)

If using the web version without the extension:

1. Go to http://localhost:3000
2. Click "Start Session"
3. Enter URLs and categories manually
4. Observe real-time tracking
5. Click "End Session & View Results"

Passive Tracking with Extension

With the Chrome extension installed:

1. Click the extension icon in your toolbar
2. Click "Start Tracking"
3. Browse normally - all tabs are tracked automatically
4. Click "Stop Tracking" to end the session
5. View the dashboard automatically

The extension:

• Monitors active tabs in real-time
• Sends data to the backend API
• Runs in the background
• Stores session state in Chrome storage
• No typing or interaction required

---

Deployment

Option 1: Vercel (Frontend) + Railway (Backend)

Deploy Backend to Railway

1. Create account at https://railway.app
2. Create new project → GitHub repo
3. Add repository with backend code
4. Set environment variables
5. Deploy automatically on push

# Backend start command
uvicorn main:app --host 0.0.0.0 --port $PORT

Deploy Frontend to Vercel

1. Create account at https://vercel.com
2. Import your repository
3. Set build command: npm run build
4. Set environment variables:

   NEXT_PUBLIC_API_URL=https://your-railway-app.railway.app
   

5. Deploy

Update Extension API URL

In extension/background.js, change:

const API_URL = 'https://your-railway-app.railway.app';

Option 2: Heroku (Backend) + Netlify (Frontend)

Heroku Backend

1. Install Heroku CLI
2. Create Procfile:

web: uvicorn main:app --host 0.0.0.0 --port $PORT

3. Deploy:

heroku create your-app-name
git push heroku main

Netlify Frontend

1. Connect GitHub repo to Netlify
2. Set build command: npm run build
3. Set publish directory: .next
4. Add environment variables

Option 3: Docker (Production Ready)

Create docker-compose.yml:

version: '3.8'

services:
  backend:
    build:
      context: ./backend
      dockerfile: Dockerfile
    ports:
      - "8000:8000"
    environment:
      - DATABASE_URL=sqlite:///./behavior_mirror.db
    volumes:
      - ./backend:/app
    command: uvicorn main:app --host 0.0.0.0 --port 8000

  frontend:
    build:
      context: ./frontend
      dockerfile: Dockerfile
    ports:
      - "3000:3000"
    environment:
      - NEXT_PUBLIC_API_URL=http://localhost:8000
    depends_on:
      - backend

Build and run:

docker-compose up --build

---

API Documentation

Base URL

• Local: http://localhost:8000
• Production: https://your-api-url.com

Endpoints

Start Session

POST /session/start
Response: { session_id, start_time, message }

End Session

POST /session/{session_id}/end
Response: { session_id, end_time, duration_minutes, message }

Log Tab Activity

POST /tab_activity
Body: {
  "session_id": "uuid",
  "url": "https://example.com",
  "category": "Work|Learning|Social|Entertainment|Other",
  "start_time": "2026-01-09T10:30:00Z",
  "end_time": "2026-01-09T10:40:00Z"
}
Response: { id, session_id, url, category, duration_seconds, message }

Get Session Summary

GET /session/{session_id}/summary
Response: {
  "session_id": "uuid",
  "start_time": "2026-01-09T10:30:00Z",
  "end_time": "2026-01-09T11:30:00Z",
  "duration_minutes": 60,
  "category_stats": [...],
  "tab_switches_by_hour": [...],
  "focus_stats": {...},
  "ai_insights": [...],
  "activity_count": 15
}

List Sessions

GET /sessions?limit=20
Response: [{ id, start_time, end_time, duration_minutes }, ...]

Health Check

GET /health
Response: { status, timestamp }

Interactive API Documentation

When running locally, visit: http://localhost:8000/docs
Swagger UI with interactive endpoint testing

---

Testing

Manual Testing Workflow

1. Start Backend: uvicorn main:app --reload

2. Start Frontend: npm run dev

3. Load Extension: chrome://extensions → Load unpacked

4. Test Scenario A - Manual Web Entry:

   • Go to http://localhost:3000
   • Click "Start Session"
   • Enter 5-10 different URLs with categories
   • Click "End Session"
   • Verify dashboard shows correct charts and insights

5. Test Scenario B - Extension Tracking:

   • Click extension icon → "Start Tracking"
   • Open multiple tabs (GitHub, YouTube, Slack, etc.)
   • Switch tabs 10+ times
   • Click "Stop Tracking"
   • Check dashboard for auto-categorization

Sample Data Creation

Run this Python script to populate sample data:

# sample_data.py
import requests
from datetime import datetime, timedelta
import json

API_URL = "http://localhost:8000"

# Sample sites with categories
SITES = [
    ("https://github.com/", "Work"),
    ("https://stackoverflow.com/", "Learning"),
    ("https://linkedin.com/", "Social"),
    ("https://youtube.com/", "Entertainment"),
    ("https://notion.so/", "Work"),
    ("https://twitter.com/", "Social"),
    ("https://udemy.com/", "Learning"),
]

# Create session
resp = requests.post(f"{API_URL}/session/start")
session_id = resp.json()["session_id"]

# Log activities
current_time = datetime.utcnow()
for i, (url, category) in enumerate(SITES):
    start = current_time + timedelta(minutes=i*10)
    end = start + timedelta(minutes=5)
    
    requests.post(f"{API_URL}/tab_activity", json={
        "session_id": session_id,
        "url": url,
        "category": category,
        "start_time": start.isoformat() + "Z",
        "end_time": end.isoformat() + "Z",
    })

# End session
requests.post(f"{API_URL}/session/{session_id}/end")

print(f"Sample session created: {session_id}")
print(f"View at: http://localhost:3000/dashboard?session={session_id}")

Run it:

python sample_data.py

---

URL Categorization Logic

The system automatically categorizes URLs based on patterns:

Work

• github.com, gitlab.com, jira, confluence, slack.com
• gmail.com, stackoverflow.com, developer sites
• Code editors: vscode.dev, codepen.io, repl.it

Learning

• coursera.com, udemy.com, khan academy
• w3schools.com, mdn mozilla docs
• YouTube learning videos

Social

• facebook.com, instagram.com, twitter.com, tiktok.com
• reddit.com, discord.com, linkedin.com
• quora.com, medium.com

Entertainment

• netflix.com, youtube.com, twitch.tv, hulu.com
• Gaming sites: steampowered.com, xbox.com

AI Insights Generated

1. Tab Switching Analysis: Flags high switching (>30) with Pomodoro recommendations
2. Distraction Detection: Alerts when distraction time exceeds 60 minutes
3. Focus Capability: Celebrates long focus periods (45+ min)
4. Productivity Score: Calculates % of productive vs distracting time
5. Pattern Recognition: Identifies time-of-day patterns and suggests optimizations

---

Database Schema

session Table

CREATE TABLE session (
  id TEXT PRIMARY KEY,
  start_time TEXT NOT NULL,
  end_time TEXT,
  duration_minutes INTEGER,
  created_at TEXT DEFAULT CURRENT_TIMESTAMP
)

tab_activity Table

CREATE TABLE tab_activity (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  session_id TEXT NOT NULL,
  url TEXT NOT NULL,
  category TEXT NOT NULL,
  start_time TEXT NOT NULL,
  end_time TEXT,
  duration_seconds INTEGER,
  created_at TEXT DEFAULT CURRENT_TIMESTAMP,
  FOREIGN KEY (session_id) REFERENCES session(id)
)

---

Architecture & Tech Stack

Backend

• Framework: FastAPI (async Python framework)
• Database: SQLite (local file-based)
• ORM: Raw SQL with context managers
• Validation: Pydantic models
• Server: Uvicorn ASGI server

Frontend

• Framework: Next.js 14
• UI Library: React 18
• Styling: TailwindCSS
• Charts: Recharts
• Icons: Lucide React
• HTTP Client: Axios

Extension

• API: Chrome Extension Manifest V3
• Service Worker: Background scripts
• Storage: Chrome Storage API
• Communication: Chrome Runtime Messaging

DevOps

• Version Control: Git
• Containerization: Docker (optional)
• Frontend Hosting: Vercel / Netlify
• Backend Hosting: Railway / Heroku
• CI/CD: GitHub Actions (optional)

---

Future Enhancements

Phase 2 Features

• User authentication with OAuth2
• Cloud database (PostgreSQL)
• Weekly/monthly analytics views
• Custom focus goal tracking
• Website blocking during focus hours
• Personalized notifications
• Export data as CSV/JSON
• Dark mode UI

Phase 3 Features

• Advanced ML predictions
• Collaborative team analytics
• Mobile app (React Native)
• Integration with Slack, GitHub
• Productivity leaderboards
• Custom categorization rules
• Browser sync across devices

Code Placeholders for Future Development

# In backend/main.py - Future authentication
# from fastapi.security import OAuth2PasswordBearer
# from jose import JWTError, jwt
# oauth2_scheme = OAuth2PasswordBearer(tokenUrl="token")

# In frontend - Future notifications
// import { toast } from 'react-hot-toast';
// toast.success('Session saved!');

# In extension - Future site blocking
// chrome.webRequest.onBeforeRequest.addListener(
//   (details) => {
//     if (blockedSites.includes(new URL(details.url).hostname)) {
//       return { redirectUrl: chrome.runtime.getURL("blocked.html") };
//     }
//   },
//   { urls: ["<all_urls>"] },
//   ["blocking"]
// );

---

Troubleshooting

Issue: Backend won't start

Solution: Ensure port 8000 is available

# Find process using port 8000 and kill it
lsof -i :8000  # macOS/Linux
netstat -ano | findstr :8000  # Windows

Issue: Extension not connecting to backend

Solution: Verify API URL in extension/background.js

const API_URL = 'http://localhost:8000';  // Change if different

Issue: CORS errors in browser console

Solution: Backend CORS is enabled for all origins in dev mode

# In main.py - already configured
app.add_middleware(
    CORSMiddleware,
    allow_origins=["*"],  # Change in production!
    ...
)

Issue: Database errors

Solution: Delete database and reinitialize

rm backend/behavior_mirror.db
cd backend
python -c "from database import init_db; init_db()"

---

Performance Optimizations

Completed

✅ Async API with FastAPI/Uvicorn
✅ React component memoization
✅ TailwindCSS purging for smaller CSS
✅ Next.js code splitting
✅ Chrome storage for session state
✅ SQLite indexes on foreign keys

Recommendations

• Add Redis caching for /sessions endpoint
• Implement pagination for large datasets
• Compress images in UI
• Use Next.js ISR for dashboards
• Add database connection pooling

---

Security Considerations

Current (Development)

⚠️ CORS enabled for all origins
⚠️ No authentication required
⚠️ SQLite database (file-based)
⚠️ No HTTPS enforcement

Production TODO

• Implement OAuth2 authentication
• Restrict CORS to known domains
• Use PostgreSQL with encryption
• Implement rate limiting
• Add HTTPS/TLS
• Hash sensitive data
• Regular security audits
• GDPR compliance for data storage

---

Support & Contributing

Getting Help

1. Check the API docs: http://localhost:8000/docs
2. Review database schema in database.py
3. Check insights.py for categorization logic
4. Review component props in frontend files

Contributing

1. Create a feature branch
2. Make changes
3. Test thoroughly
4. Create pull request

---

License

This project is open source and available under the MIT License.

---

Happy tracking! 🚀

For questions or issues, check the GitHub discussions or create an issue with:

• Browser version
• Steps to reproduce
• Expected vs actual behavior
• Error messages or screenshots